POST/volc/v1/contents/generations/tasks

创建豆包统一视频任务

用文字、首帧图片或多模态参考创建 Seedance 视频任务。统一格式的创建入口是 /v1/videos，成功后返回任务 ID。

API Key application/json

功能说明

文生视频描述主体、动作、镜头和声音；图生视频用图片确定首帧或首尾帧；2.0、2.5 可用参考图、视频和音频生成新内容。首次接入建议运行下面的 5 秒文生示例。模型范围见协议选择与模型。

第一步：鉴权

在控制台 API 密钥取得青云 API Key。每次创建、查询和下载请求都发送以下请求头：

Authorization: Bearer YOUR_API_KEY

将 YOUR_API_KEY 替换为自己的 Key，保留 Bearer 和其后一个空格。无需先请求登录接口。

第二步：调用模型生成

POST https://top.qingyuntop.ai/v1/videos，请求体使用 application/json。保存响应 id，再按查询和下载处理异步结果。

Request

请求

/volc/v1/contents/generations/tasks

Body

必填

Bodyobject

modelstring必填

doubao-seedance-1-5-pro-251215 支持：文生、首帧、首尾帧 doubao-seedance-1-0-pro-250528 支持：文生、首帧、首尾帧 doubao-seedance-1-0-pro-fast-251015 支持：文生、首帧 doubao-seedance-1-0-lite-t2v-250428 支持：文生 doubao-seedance-1-0-lite-i2v-250428 支持：首帧、首尾帧、参考图（1-4）

contentarray<object>必填

输入给模型，生成视频的信息，支持文本信息和图片信息。

元素object

typestring必填

输入内容的类型： - text 表示文本 - image_url 表示图片

textstring必填

输入给模型的文本内容，描述期望生成的视频，包括：文本提示词（必填）：支持中英文。建议不超过500字。字数过多信息容易分散，模型可能因此忽略细节，只关注重点，造成视频缺失部分元素。

image_urlobject

输入给模型的图片对象。

urlstring

图片信息，这里为图片url 或 Base64 编码。

rolestring

图片用途： - reference_image 表示参考图 - first_frame 表示首帧只为首帧的时候该参数可不填 - last_frame 表示尾帧

generate_audioboolean

控制生成的视频是否包含与画面同步的声音。 - true：模型输出的视频包含同步音频。Seedance 1.5 pro 能够基于文本提示词与视觉内容，自动生成与之匹配的人声、音效及背景音乐。建议将对话部分置于双引号内，以优化音频生成效果。例如：男人叫住女人说：“你记住，以后不可以用手指指月亮。” - false：模型输出的视频为无声视频。注意：该参数只支持 Seedance 1.5 pro 模型默认值：true

-- 参数object

以下参数需要添加到提示词后面通过 -- 形式追加，参考示例

resolutionstring

视频分辨率，枚举值： - 480p - 720p - 1080p：参考图场景不支持 Seedance 1.5 pro、Seedance 1.0 lite 默认值：720p Seedance 1.0 pro & pro-fast 默认值：1080p

ratiostring

生成视频的宽高比例： - 16:9 - 4:3 - 1:1 - 3:4 - 9:16 - 21:9 文生视频：默认值 16:9（ Seedance 1.5 Pro 默认为自适应）图生视频：默认自适应（参考图生视频场景默认值为 16:9）

durationinteger

生成视频时长，单位：秒。支持 2-12 秒 Seedance 1.5 pro 只支持 4-12 秒默认值 5

camera_fixedstring

是否固定摄像头。枚举值： - true：固定摄像头。平台会在用户提示词中追加固定摄像头，实际效果不保证。 - false：不固定摄像头。注意：参考图场景不支默认值 false

watermarkstring

生成视频是否包含水印。枚举值： - false：不含水印。 - true：含有水印。默认值 false

seedinteger

种子整数，用于控制生成内容的随机性。取值范围：[-1, 2^32-1]之间的整数。注意： - 相同的请求下，模型收到不同的seed值，如：不指定seed值或令seed取值为-1（会使用随机数替代）、或手动变更seed值，将生成不同的结果。 - 相同的请求下，模型收到相同的seed值，会生成类似的结果，但不保证完全一致。默认值 -1 传入时不能输入 -1

路径、查询与 Header 参数

参数	位置	类型	必填	说明	示例
`Content-Type`	Header	string	否	-	application/json
`Accept`	Header	string	否	-	application/json
`Authorization`	Header	string	是	必填。使用青云TOP API 的 API Key，保留 Bearer 后的空格。	Bearer YOUR_API_KEY

请求示例application/json

curl --fail-with-body "https://top.qingyuntop.ai/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "doubao-seedance-2-5-260628",
  "prompt": "一只橙色的猫走过雨后屋顶，镜头缓慢推进，柔和的傍晚光线，伴随轻微雨声。",
  "seconds": 5,
  "metadata": {
    "resolution": "720p",
    "ratio": "16:9",
    "generate_audio": true
  }
}'

Response

返回响应 `200`

HTTP 响应

响应 200object

字段位置与限制

JSON 请求用 seconds；不要使用顶层 duration 代替 seconds。
清晰度和宽高比明确写 metadata.resolution、metadata.ratio。顶层 size、resolution、ratio 不应代替这些字段。
JSON 的 image、input_reference 不会被映射成参考内容；使用 metadata.content。multipart 上传文件会报错。
metadata.content 中的 text 项会被 prompt 重建。不要把唯一提示词放在 metadata.content。
2.5 视频编辑需省略 seconds，在 metadata 中使用 duration: -1、ratio: adaptive、omni_reference_task_type: edit，并提供 reference_video。负数 seconds 会被统一协议拒绝。
draft_task 是“样片转正式视频”，请使用豆包原生样片示例；它不等于视频延长。

文生视频代码

cURL 使用 Bash 语法；Python 先安装 requests；Node.js 使用 22+ 并保存为 .mjs。示例中的 Key、素材 URL 和任务 ID 都需要替换。

curl --fail-with-body "https://top.qingyuntop.ai/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "doubao-seedance-2-5-260628",
  "prompt": "一只橙色的猫走过雨后屋顶，镜头缓慢推进，柔和的傍晚光线，伴随轻微雨声。",
  "seconds": 5,
  "metadata": {
    "resolution": "720p",
    "ratio": "16:9",
    "generate_audio": true
  }
}'

图生视频与参考素材

以下是同一 POST 接口的完整 JSON 请求体。example.com 为占位素材地址，换成可直接读取的 HTTPS 文件；图片也可以使用完整 data URL：data:image/png;base64,…，不要只传裸 Base64。

{
  "model": "doubao-seedance-2-5-260628",
  "prompt": "保持图片中产品外观，让镜头缓慢推进。",
  "seconds": 5,
  "metadata": {
    "resolution": "720p",
    "ratio": "adaptive",
    "content": [
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/first.png"
        },
        "role": "first_frame"
      }
    ]
  }
}

首尾帧：在 content 再加入 role 为 last_frame 的 image_url，并保留 first_frame。2.5 必须 ratio: adaptive。

多模态参考：使用 reference_image、reference_video、reference_audio；不要把首尾帧角色和参考模式混在同一示例中。具体素材限制和视频编辑见豆包原生创建参数。

成功响应

结构示例，真实 ID 和时间以响应为准：

{
  "id": "task_doubao_example",
  "object": "video",
  "model": "doubao-seedance-2-5-260628",
  "status": "queued",
  "progress": 0
}

HTTP 成功表示任务已接收；完成后状态变为 completed。查询对象不保证返回视频 URL，请走 content 下载接口。请求超时又未取得 ID 时先查看任务日志，避免重复提交计费。