> ## 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.

# ByteDance AI 特效模板列表 API

> 通过 Crun 查询 ByteDance AI 特效模板目录，包括模板 ID、封面、预览视频、支持分辨率、输入要求和积分消耗。部分模板由 ByteDance Seedance 2.0 支持。

## 概述

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

此接口面向希望通过单一 API 连接集成所有 ByteDance 模板的开发者。它会返回模板元数据、封面资源、预览视频、输入图片要求、支持的宽高比、支持的分辨率，以及经过 Crun 标准化后的积分消耗。

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

## 使用场景

1. 构建 ByteDance 模板市场或模板选择器 UI
2. 按计划同步最新模板列表
3. 通过传入可选的 `template_id` 参数查询单个模板
4. 基于 `InputNum`、`InputRequirement`、`TemplateType` 和 `ConsumeItems` 驱动动态表单渲染

## 官方模板库

你也可以打开 ByteDance 官方模板库，选择模板并获取模板 ID：

* ByteDance 官方模板库：[TemplateAI](https://console.volcengine.com/kickart/templateAI)

## 相关资源

<CardGroup cols={2}>
  <Card title="ByteDance 模板视频" icon="sparkles" href="/zh/templates/bytedance-template">
    使用选定模板和图片输入提交 ByteDance 模板视频生成任务。
  </Card>

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


## OpenAPI

````yaml zh/templates/bytedance-template-list.json get /api/v1/client/job/bytedance-templates
openapi: 3.0.0
info:
  title: Crun ByteDance AI 特效模板列表 API
  description: crun.ai ByteDance AI 特效模板列表 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/bytedance-templates:
    get:
      summary: 查询 ByteDance AI 特效模板列表
      operationId: bytedance-template-list
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
          description: 页码。提供 `template_id` 时忽略。
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            maximum: 50
            default: 20
          description: 每页模板数量，最大值为 50。提供 `template_id` 时忽略。
        - name: template_id
          in: query
          required: false
          schema:
            type: string
            default: ''
          description: 可选模板 ID。提供后仅返回匹配的模板。
      responses:
        '200':
          description: 请求成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          total:
                            type: integer
                            description: 模板总数；提供 `template_id` 时为匹配的模板数量
                            example: 280
                          templates:
                            type: array
                            items:
                              $ref: '#/components/schemas/ByteDanceTemplate'
              example:
                code: 200
                message: success
                data:
                  total: 280
                  templates:
                    - MediaId: '7642552612302307355'
                      Title: 战斗游戏
                      Cover: >-
                        https://muse.console.volcengine.com/api/storage/objects/media/7642552364255297590_transcode_image_jpeg_480p/example.jpeg
                      Duration: 10123
                      PreviewVideo: >-
                        https://muse.console.volcengine.com/api/storage/objects/media/7642552612302307355_transcode_video_mp4_480p_h264.mp4
                      Tags:
                        - 🔥Seedance2.0模型
                      ServiceId: '217677058'
                      TemplateId: '104909826'
                      TemplateType: BEGIN_END_FRAME
                      InputRequirement: SINGLE_PERSON
                      InputNum: 1
                      ReleaseOnlineTime: 1779421051
                      ConsumeItems:
                        - Resolution: 480p
                          Credit: 166.5
                        - Resolution: 720p
                          Credit: 355.2
                      Title_en: Battle Game
                      Tags_en:
                        - 🔥Seedance2.0 Model
                      CoverAspectRatio: '9:16'
                      SupportAspectRatio: 9:16,1:1,16:9,4:3,3:4
        '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
    ByteDanceTemplate:
      type: object
      properties:
        MediaId:
          type: string
          description: 模板媒体 ID
          example: '7642552612302307355'
        Title:
          type: string
          description: 模板标题
          example: 战斗游戏
        Title_en:
          type: string
          description: 英文模板标题
          example: Battle Game
        Cover:
          type: string
          format: uri
          description: 模板封面图片 URL
        Duration:
          type: integer
          description: 预览或输出时长，单位为毫秒
          example: 10123
        PreviewVideo:
          type: string
          format: uri
          description: 模板预览视频 URL
        Tags:
          type: array
          items:
            type: string
          description: 模板标签
          example:
            - 🔥Seedance2.0模型
        Tags_en:
          type: array
          items:
            type: string
          description: 英文模板标签
          example:
            - 🔥Seedance2.0 Model
        ServiceId:
          type: string
          description: ByteDance 服务 ID
          example: '217677058'
        TemplateId:
          type: string
          description: 创建 `bytedance/template` 任务时作为 `input.template_id` 传入的模板 ID
          example: '104909826'
        TemplateType:
          type: string
          description: 模板类型
          example: BEGIN_END_FRAME
        InputRequirement:
          type: string
          description: 模板输入主体要求
          example: SINGLE_PERSON
        InputNum:
          type: integer
          description: 所需输入图片数量
          example: 1
        ReleaseOnlineTime:
          type: integer
          description: 模板上线时间戳
          example: 1779421051
        ConsumeItems:
          type: array
          description: 支持的分辨率和 Crun 积分消耗
          items:
            type: object
            properties:
              Resolution:
                type: string
                example: 720p
              Credit:
                type: number
                example: 355.2
        CoverAspectRatio:
          type: string
          description: 封面图片宽高比
          example: '9:16'
        SupportAspectRatio:
          type: string
          description: 逗号分隔的支持宽高比列表
          example: 9:16,1:1,16:9,4:3,3:4
  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 已泄露，请立即在管理页面重置

````