> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Crun Vidu 模板 API

> 通过 Crun 统一任务接口使用 Vidu 特效模板生成视频。input 对象保持与 Vidu 官方模板 API 相同的字段结构。

## 概述

使用此接口通过 Crun 的统一任务创建 API，基于指定的 Vidu 特效模板生成视频。

`input` 对象与 Vidu 官方模板请求结构保持一致，而外层包装遵循 Crun 统一任务格式：

```json theme={null}
{
  "model": "vidu/template",
  "input": {
    "template": "Easter_cute_pets",
    "images": [
      "https://static.crunai.com/u/9b4262e8-4051-4ae8-abf8-e8d8955a948c.png"
    ],
    "bgm": true
  }
}
```

<Tip>
  如需一次性集成所有可用的 Vidu 模板，请先调用位于 <code>/api/v1/client/job/vidu-templates</code> 的 Vidu 模板列表接口，然后动态渲染模板元数据，并将选定的模板提交到此生成接口。
</Tip>

## 模板发现

在创建任务之前，开发者可以从 Crun Vidu 模板列表接口获取最新模板目录：

<Card title="Vidu 模板列表" icon="list" href="/zh/templates/vidu/template-list">
  查询所有可用的 Vidu 特效模板、支持的选项、封面资源和各模板的输入说明。
</Card>

列表接口可以帮助你轻松构建面向所有模板的一键集成流程：

1. 查询 `/api/v1/client/job/vidu-templates`
2. 在你的应用中展示返回的模板列表
3. 使用选定的 `template` 值和支持的字段调用 `vidu/template`

## 官方参考

* Vidu 官方模板库示例：[Templates](https://platform.vidu.cn/docs/templates)
* Vidu 官方模板生成 API：[Template](https://platform.vidu.cn/docs/template)

## 查询任务状态

提交任务后，使用统一查询接口检查进度并获取结果：

<Card title="获取任务信息" icon="magnifying-glass" href="/zh/models/common/get-task-info">
  了解如何查询任务状态并获取生成结果
</Card>

<Tip>
  在生产环境中，我们建议使用 `callback_url` 参数在生成完成时接收自动通知，而不是轮询状态接口。
</Tip>

## 相关资源

<CardGroup cols={2}>
  <Card title="Vidu 模板列表" icon="list" href="/zh/templates/vidu/template-list">
    查询所有可用的 Vidu 特效模板，并支持一键模板集成。
  </Card>

  <Card title="模型概览" icon="store" href="/zh/models/quickstart">
    浏览 Crun 上所有可用的生成模型。
  </Card>
</CardGroup>


## OpenAPI

````yaml zh/templates/vidu-template.json post /api/v1/client/job/CreateTask
openapi: 3.0.0
info:
  title: Crun Vidu 模板视频生成 API
  description: crun.ai Vidu 模板视频生成 API 文档
  version: 1.0.0
  contact:
    name: 技术支持
    email: support@crun.ai
servers:
  - url: https://api.crun.ai
    description: API 服务器
security:
  - ApiKeyAuth: []
paths:
  /api/v1/client/job/CreateTask:
    post:
      summary: 使用 Vidu 特效模板生成视频
      operationId: vidu-template-video-generation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - input
              properties:
                model:
                  type: string
                  enum:
                    - vidu/template
                  description: |-
                    用于生成的模型名称。必填字段。

                    - 此接口必须使用 `vidu/template`
                callback_url:
                  type: string
                  format: uri
                  description: |-
                    可选。用于接收任务完成通知的回调 URL。

                    - 系统会在生成完成后向该 URL POST 任务状态和结果
                    - 回调负载结构与任务状态查询返回的 `data` 对象一致
                    - 你的回调接口应支持接收包含结果的 JSON 负载的 POST 请求
                    - 成功接收后应返回 HTTP 200 状态码
                  example: https://your-domain.com/api/callback
                input:
                  type: object
                  description: >-
                    Vidu 模板视频生成的输入参数。字段结构与 Vidu 官方模板 API 保持一致，而外层请求遵循 Crun
                    统一任务格式。
                  required:
                    - template
                    - images
                  properties:
                    template:
                      type: string
                      description: >-
                        模板标识符。你可以通过 `/api/v1/client/job/vidu-templates` 查询支持的模板
                        ID。
                      example: Easter_cute_pets
                    images:
                      type: array
                      description: 模板输入图片。实际支持的图片数量取决于所选模板。请参考模板列表响应和 Vidu 官方示例中各模板的输入要求。
                      items:
                        type: string
                      minItems: 1
                      example:
                        - >-
                          https://static.crunai.com/u/9b4262e8-4051-4ae8-abf8-e8d8955a948c.png
                    prompt:
                      type: string
                      nullable: true
                      maxLength: 2000
                      description: 可选文本提示词。某些模板不需要此字段。
                      example: A warm spring memory with cute pets.
                    aspect_ratio:
                      type: string
                      nullable: true
                      description: 可选的输出宽高比。可用性取决于所选模板。
                      example: '9:16'
                    area:
                      type: string
                      nullable: true
                      description: 某些模板使用的可选风格控制字段，例如区域特定变体。
                      example: japan
                    beast:
                      type: string
                      nullable: true
                      description: 某些模板使用的可选风格控制字段，例如动物伙伴变体。
                      example: tiger
                    bgm:
                      type: boolean
                      nullable: true
                      description: 是否添加背景音乐。
                      example: true
                    story:
                      type: string
                      nullable: true
                      description: 可选的故事模板字段，适用于支持基于故事生成的模板。
                      example: romantic_confession
            example:
              model: vidu/template
              input:
                template: Easter_cute_pets
                images:
                  - >-
                    https://static.crunai.com/u/9b4262e8-4051-4ae8-abf8-e8d8955a948c.png
                bgm: true
      responses:
        '200':
          description: 请求成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          task_id:
                            type: string
                            description: 任务 ID，可与获取任务详情接口配合使用以查询任务状态
                            example: task_12345678
              example:
                code: 200
                message: success
                data:
                  task_id: task_12345678
        '422':
          description: 验证错误
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      errors:
                        type: array
                        description: 详细的验证错误消息
                        items:
                          type: string
                        example:
                          - >-
                            Value error, Invalid input for model vidu/template:
                            images must contain at least 1 item
              example:
                code: 422
                message: 缺少参数或类型错误
                errors:
                  - >-
                    Value error, Invalid input for model vidu/template: images
                    must contain at least 1 item
        '500':
          $ref: '#/components/responses/Error'
components:
  schemas:
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          enum:
            - 200
            - 401
            - 402
            - 404
            - 422
            - 429
            - 455
            - 500
            - 501
            - 505
          description: |-
            响应状态码

            - **200**：成功 - 请求已成功处理
            - **401**：未授权 - 身份验证凭证缺失或无效
            - **402**：积分不足 - 账户没有足够的积分执行该操作
            - **404**：未找到 - 请求的资源或接口不存在
            - **422**：验证错误 - 请求参数未通过验证检查
            - **429**：请求频率受限 - 已超过该资源的请求限制
            - **455**：服务不可用 - 系统当前正在维护
            - **500**：服务器错误 - 处理请求时发生意外错误
            - **501**：生成失败 - 内容生成任务失败
            - **505**：功能已禁用 - 请求的功能当前已被禁用
        message:
          type: string
          description: 响应消息，失败时为错误描述
          example: success
  responses:
    Error:
      description: 服务器错误
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: |-
        所有 API 都需要通过 API Key 进行身份验证。

        获取 API Key：
        1. 访问 [API Key 管理页面](https://crun.ai/zh/user-api-key) 获取你的 API Key

        使用方式：
        添加到请求头：

        x-api-key: YOUR_API_KEY

        注意：
        - 请妥善保管你的 API Key，不要与他人共享
        - 如果你怀疑 API Key 已泄露，请立即在管理页面中重置

````