> ## 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 特效模板目录，包括模板 ID、支持的选项、预览资源、积分消耗和输入说明。

## 概述

使用此接口查询 Crun 提供的可用 Vidu 特效模板。

此接口面向希望通过单一 API 连接集成所有 Vidu 模板的开发者。它会分页返回经过 Crun 侧标准化后的模板目录、支持的选项、预览资源、输入说明、Vidu 官方分类信息、热门/新模板标记和积分消耗。

<Tip>
  开发者可以将此接口作为模板 ID 和各模板能力的可信来源，然后将选定的模板配置直接传入 <code>vidu/template</code>，从而一键集成所有支持的模板。
</Tip>

## 使用场景

1. 构建模板市场或模板选择器 UI
2. 按计划同步最新模板列表
3. 通过传入可选的 `template` 参数查询单个模板
4. 基于返回的模板元数据驱动动态表单渲染
5. 使用 `page` 和 `page_size` 分页获取大量模板

## 官方参考

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

## 相关资源

<CardGroup cols={2}>
  <Card title="Vidu 模板视频" icon="sparkles" href="/zh/templates/vidu/template-video-generation">
    使用选定模板和模板专属输入提交 Vidu 模板视频生成任务。
  </Card>

  <Card title="获取任务信息" icon="magnifying-glass" href="/zh/models/common/get-task-info">
    任务提交后查询生成状态并获取最终结果。
  </Card>
</CardGroup>


## OpenAPI

````yaml zh/templates/vidu-template-list.json get /api/v1/client/job/vidu-templates
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/vidu-templates:
    get:
      summary: 查询 Vidu 模板列表
      operationId: vidu-template-list
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
          description: 分页查询的页码。提供 `template` 时会忽略该参数。
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            maximum: 50
            default: 20
          description: 每页返回的模板数量，最大值为 50。提供 `template` 时会忽略该参数。
        - name: template
          in: query
          required: false
          schema:
            type: string
            default: ''
          description: 可选的模板 ID。提供该参数时，API 仅返回匹配的模板。
      responses:
        '200':
          description: 请求成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          total:
                            type: integer
                            description: 模板总数。提供 `template` 时表示匹配到的模板数量。
                            example: 120
                          templates:
                            type: array
                            items:
                              $ref: '#/components/schemas/ViduTemplate'
              example:
                code: 200
                message: success
                data:
                  total: 120
                  templates:
                    - template: Vintage_Moment_of_Mom
                      resolution:
                        - 1080p
                      duration:
                        - 0
                      aspect_ratio:
                        - '9:16'
                      output_type: unspecified
                      name: 妈妈的复古时刻
                      cover: >-
                        https://scene.cf.vidu.studio/media-asset/083048-QXAxiKtJUEYIy8ti.png
                      video: >-
                        https://scene.cf.vidu.studio/media-asset/083048-QXAxiKtJUEYIy8ti.png
                      credits: 9
                      person_count: 仅支持单人女性照片
                      input_instruction: >-
                        {"image_count":"仅可上传一张图片","image_url":["https://scene.cf.vidu.studio/media-asset/083031-h9r9GH4Ll5AYpoF1.png"],"person_count":"仅支持单人女性照片","attention":"单人半身或全身照片效果最佳","prompt_instruction":"此模式无需提示词","effect_boundary":"有较低概率出现面部特征轻微变化等问题"}
                      category_name: 节日
                      category_id: 11
                      is_hot: true
                      is_new: false
        '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
    ViduTemplate:
      type: object
      properties:
        template:
          type: string
          description: Vidu 模板 ID
          example: Vintage_Moment_of_Mom
        resolution:
          type: array
          items:
            type: string
          description: 支持的输出分辨率
          example:
            - 1080p
        duration:
          type: array
          items:
            type: integer
          description: 支持的输出时长
          example:
            - 0
        aspect_ratio:
          type: array
          items:
            type: string
          description: 支持的宽高比
          example:
            - '9:16'
        output_type:
          type: string
          description: Vidu 返回的输出类型
          example: unspecified
        name:
          type: string
          description: 便于阅读的模板名称
          example: 妈妈的复古时刻
        cover:
          type: string
          format: uri
          description: 模板封面图片
          example: https://scene.cf.vidu.studio/media-asset/083048-QXAxiKtJUEYIy8ti.png
        video:
          type: string
          format: uri
          description: 模板预览资源
          example: https://scene.cf.vidu.studio/media-asset/083048-QXAxiKtJUEYIy8ti.png
        credits:
          type: number
          description: 模板在 Crun 上消耗的积分
          example: 9
        person_count:
          type: string
          description: 模板支持的人数或主体限制
          example: 仅支持单人女性照片
        input_instruction:
          type: string
          description: 上游服务返回的序列化模板专属输入说明
          example: >-
            {"image_count":"仅可上传一张图片","image_url":["https://scene.cf.vidu.studio/media-asset/083031-h9r9GH4Ll5AYpoF1.png"],"person_count":"仅支持单人女性照片","attention":"单人半身或全身照片效果最佳","prompt_instruction":"此模式无需提示词","effect_boundary":"有较低概率出现面部特征轻微变化等问题"}
        category_name:
          type: string
          description: 模板分类名称
          example: 节日
        category_id:
          type: integer
          description: Vidu 官方分类 ID
          example: 11
        is_hot:
          type: boolean
          description: 是否为 Vidu 官方热门模板
          example: true
        is_new:
          type: boolean
          description: 是否为 Vidu 官方新模板
          example: false
  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 已泄露，请立即在管理页面中重置

````