视频生成

视频生成接口为异步接口。提交任务后平台立即返回任务 ID，视频在后台生成完成后通过查询接口获取结果。支持文生视频、图生视频、首尾帧、多模态参考等多种输入组合。

整体调用流程

仅使用文本或公网 URL：

调用 POST /v1/videos/generations 提交任务。
保存响应中的 id。
轮询 GET /v1/videos/generations/{id} 查询任务状态（建议间隔 5–10 秒）。
status=succeeded 时，从 content.video_url 获取视频，请及时下载转存。

使用平台素材库（私域素材）：

调用 POST /v1/assets 提交公网 HTTPS 素材 URL，或使用 multipart/form-data 上传本地文件。
轮询 GET /v1/assets/{id}，等待 status=active。
在视频生成请求的 content[].*.url 中传入 asset://<asset_id>，必须保留 asset:// 前缀。

创建视频生成任务

POST /v1/videos/generations
Authorization: Bearer <API_KEY>
Content-Type: application/json

请求参数

参数	类型	必填	说明
`model`	string	是	平台开通的视频模型名称，例如 `seedance-2.0`、`seedance-2.0-fast`。实际可用名称以平台分配和 `/v1/models` 返回为准。
`content`	object[]	是	输入内容数组，至少包含一项。支持文本、图片、视频、音频的组合，见下方说明。
`generate_audio`	boolean	否	控制是否生成与画面同步的声音。`true`：输出有声视频（含人声、音效、背景音乐）；`false`：输出无声视频。未传时平台按 `true` 预估计费。
`resolution`	string	否	视频分辨率，枚举值：`480p`、`720p`、`1080p`。`seedance-2.0-fast` 不支持 `1080p`。未传时按 `720p` 预估计费。
`ratio`	string	否	生成视频宽高比。建议值：`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive`。`adaptive` 表示由模型根据输入内容自动选择最合适的宽高比。未传时按 `adaptive` 预估计费。
`duration`	integer	否	视频时长（秒，整数）。`seedance-2.0`、`seedance-2.0-fast` 支持 `[4, 15]` 或 `-1`（由模型自主选择最合适时长）。未传时按 `5` 秒预估计费。
`watermark`	boolean	否	是否在视频右下角添加 AI 生成水印。`false` 不含水印（默认），`true` 含水印。
`seed`	integer	否	随机种子，取值范围 `[-1, 2^32-1]`。相同请求传入相同 seed 会生成类似结果，但不保证完全一致。`-1` 表示使用随机数。
`safety_identifier`	string	否	终端用户唯一标识，建议使用用户 ID、邮箱的哈希值，不超过 64 个字符，用于协助内容安全检测。
`execution_expires_after`	integer	否	任务超时阈值（秒），从任务创建时间开始计算。默认 `172800`（48 小时），取值范围 `[3600, 259200]`。超过后任务自动终止并标记为 `expired`。
`service_tier`	string	否	服务等级，当前仅支持 `default`（在线推理）。传入 `flex` 会返回 400。
`callback_url`	string	否	任务状态回调地址。任务状态变化时平台会向该地址推送 POST 请求，内容结构与查询接口响应体一致。建议以查询接口为主要结果获取方式。
`return_last_frame`	boolean	否	是否返回生成视频的尾帧图像（PNG 格式，无水印）。可用于将上一个视频的尾帧作为下一个视频的首帧，生成连续视频。

以下字段当前不支持，传入会返回 400：frames、service_tier=flex、seedance-2.0-fast + resolution=1080p。请求体只需要传入文档列出的公开字段；额外字段可能会被忽略或返回参数错误。

content 输入对象

content 是数组，至少包含一项，支持以下四种类型混合传入。

文本 `type: text`

字段	类型	必填	说明
`type`	string	是	固定为 `text`。
`text`	string	是	文本提示词，描述期望生成的视频内容。

{
  "type": "text",
  "text": "生成一段城市夜景视频，镜头缓慢推进，霓虹灯反射在雨后的路面上"
}

图片 `type: image_url`

字段	类型	必填	说明
`type`	string	是	固定为 `image_url`。
`image_url.url`	string	是	图片公网 HTTPS URL、Base64，或平台素材 URI（格式 `asset://asset_xxx`）。
`role`	string	建议填	图片用途，建议值：`first_frame`（首帧）、`last_frame`（尾帧）、`reference_image`（参考图）。

{
  "type": "image_url",
  "image_url": { "url": "https://example.com/product.png" },
  "role": "first_frame"
}

视频 `type: video_url`

字段	类型	必填	说明
`type`	string	是	固定为 `video_url`。
`video_url.url`	string	是	视频公网 HTTPS URL 或平台素材 URI（格式 `asset://asset_xxx`）。
`role`	string	建议填	视频用途，建议值：`reference_video`（参考视频）。

{
  "type": "video_url",
  "video_url": { "url": "https://example.com/reference.mp4" },
  "role": "reference_video"
}

音频 `type: audio_url`

字段	类型	必填	说明
`type`	string	是	固定为 `audio_url`。
`audio_url.url`	string	是	音频公网 HTTPS URL、Base64，或平台素材 URI（格式 `asset://asset_xxx`）。
`role`	string	建议填	音频用途，建议值：`reference_audio`（参考音频）。

{
  "type": "audio_url",
  "audio_url": { "url": "https://example.com/bgm.mp3" },
  "role": "reference_audio"
}

支持的输入组合

组合	场景
文本	文生视频
文本（可选）+ 图片	图生视频，支持首帧、首尾帧、参考图
文本（可选）+ 视频	基于参考视频生成、编辑或延长视频
文本（可选）+ 图片 + 音频	基于图片和参考音频生成视频
文本（可选）+ 图片 + 视频	多模态参考生视频
文本（可选）+ 视频 + 音频	基于参考视频和音频生成视频
文本（可选）+ 图片 + 视频 + 音频	多模态全参考生视频

音频不建议单独输入，应至少搭配图片或视频。首尾帧场景请明确指定 role=first_frame 和 role=last_frame。

提示词中如何引用多个素材

当 content 中包含多个同类型素材时，在文本提示词里用”图片 1、图片 2、视频 1、音频 1”这类顺序编号指代素材。编号按请求体中同类型素材出现的顺序计算，文本对象不参与编号。示例：请求中依次放入 5 张 reference_image 和 1 段 reference_audio 时，提示词可以这样写：

清新奶油画风短剧，轻快吉他卡点快切。0-2 秒：图片 1 中的霸总不小心撞到穿着图片 2 的衣服的图片 3 中的女主；2-6 秒：两人在雨夜共撑一把黑伞，雨天背景参考图片 4，台词参考音频 1；6-8 秒：右下角出现图片 5 的文字部分。

素材格式建议

类型	建议
图片	`jpeg`、`png`、`webp`、`bmp`、`tiff`、`gif` 等常见格式；单张小于 30 MB；宽高比 (0.4, 2.5)；分辨率 300–6000 px
视频	`mp4`、`mov`；单个参考视频建议 2–15 秒，最多 3 个
音频	`wav`、`mp3`；单段参考音频建议 2–15 秒，最多 3 段
URL	使用公网 HTTPS URL，避免使用短期失效链接
Base64	大文件不建议使用 Base64，避免请求体过大

创建任务示例

文生视频

curl -X POST "https://{your-domain}/v1/videos/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "生成一段 5 秒的城市夜景视频，镜头缓慢推进，霓虹灯反射在雨后的路面上"
      }
    ],
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "generate_audio": true,
    "watermark": false
  }'

图生视频（首帧）

{
  "model": "seedance-2.0-fast",
  "content": [
    {
      "type": "text",
      "text": "让画面中的产品在干净的工作台上缓慢旋转，镜头轻微推进"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/product.png" },
      "role": "first_frame"
    }
  ],
  "duration": 5,
  "resolution": "720p",
  "ratio": "1:1",
  "watermark": false
}

多模态参考

{
  "model": "seedance-2.0",
  "content": [
    {
      "type": "text",
      "text": "参考视频的镜头运动，生成一段新品宣传短片，保持轻快节奏"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/reference-image.png" },
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": { "url": "https://example.com/reference.mp4" },
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": { "url": "https://example.com/bgm.mp3" },
      "role": "reference_audio"
    }
  ],
  "duration": 8,
  "resolution": "720p",
  "ratio": "16:9",
  "generate_audio": true,
  "watermark": false
}

使用平台素材库

asset://asset_xxx 替换为 POST /v1/assets 返回的 uri 字段值，素材状态必须为 active。

{
  "model": "seedance-2.0",
  "content": [
    {
      "type": "text",
      "text": "参考图片中的人物站在城市街道上，镜头缓慢推进，电影感"
    },
    {
      "type": "image_url",
      "image_url": { "url": "asset://asset_6f9a4c2b8d1e3a90" },
      "role": "reference_image"
    }
  ],
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9",
  "watermark": false
}

创建成功响应

HTTP 状态码：202 Accepted

{
  "id": "vidtask_3cb6299b32d24f93a82e8a74b3e06161",
  "object": "video.generation.task",
  "created": 1779782400,
  "model": "seedance-2.0",
  "status": "queued",
  "expires_at": 1779955200
}

字段	类型	说明
`id`	string	平台任务 ID，用于查询任务。
`object`	string	固定为 `video.generation.task`。
`created`	integer	任务创建时间，Unix 秒。
`model`	string	请求中的平台模型名称。
`status`	string	初始状态，通常为 `queued`。
`expires_at`	integer	任务过期时间估算，Unix 秒。

查询视频生成任务

GET /v1/videos/generations/{id}
Authorization: Bearer <API_KEY>

id 为创建接口返回的任务 ID，格式通常以 vidtask_ 开头。建议轮询间隔不少于 3 秒，生产环境建议 5–10 秒。

curl "https://{your-domain}/v1/videos/generations/vidtask_3cb6299b32d24f93a82e8a74b3e06161" \
  -H "Authorization: Bearer $API_KEY"

响应字段说明

字段	类型	说明
`id`	string	平台任务 ID。
`object`	string	固定为 `video.generation.task`。
`created`	integer	任务创建时间，Unix 秒。
`created_at`	integer	任务创建时间，Unix 秒（同 `created`）。
`updated_at`	integer	任务状态最后更新时间，Unix 秒。
`model`	string	平台模型名称。
`status`	string	任务状态，见下方状态说明。
`billing_status`	string	平台账务状态，见下方账务状态说明。
`content`	object	视频生成结果，任务成功且有视频地址时返回。
`content.video_url`	string	生成视频 URL，请及时下载和转存，URL 有有效期。
`content.video_url_expires_at`	string	视频 URL 过期时间，RFC3339 格式，平台可识别时返回。
`error`	object	失败任务的错误信息，`status=failed` 时返回。
`error.code`	string	错误码，例如 `OutputVideoSensitiveContentDetected`。
`error.message`	string	错误说明。
`usage`	object	Token 用量信息，任务完成后返回。
`usage.completion_tokens`	integer	输出 Token 数。
`usage.total_tokens`	integer	总 Token 数。
`seed`	integer	本次任务使用的随机种子，存在时返回。
`resolution`	string	实际生成视频的分辨率，存在时返回。
`ratio`	string	实际生成视频的宽高比，存在时返回。
`duration`	integer/string	实际生成视频时长（秒），存在时返回。
`frames`	integer	生成视频总帧数，存在时返回。
`framespersecond`	integer	生成视频帧率，存在时返回。
`generate_audio`	boolean	是否包含同步音频，存在时返回。
`service_tier`	string	任务服务等级，存在时返回。
`execution_expires_after`	integer	任务超时阈值（秒），存在时返回。
`priority`	string/integer	任务优先级，存在时返回。

任务状态

`status`	说明
`queued`	排队中，等待处理。
`running`	视频正在生成中。
`succeeded`	任务成功，`content.video_url` 可用。
`failed`	任务失败，`error` 字段包含错误信息。
`cancelled`	任务已取消。
`expired`	任务超时，已超过 `execution_expires_after` 设定的时间。

账务状态

`billing_status`	说明
`frozen`	已冻结预估费用，任务尚未最终结算。
`settling`	结算处理中。
`settled`	已成功结算。
`refunded`	任务失败、取消或超时后已退款。
`settle_failed`	结算失败，需联系平台处理。
`refund_failed`	退款失败，需联系平台处理。

查询响应示例

{
  "id": "vidtask_3cb6299b32d24f93a82e8a74b3e06161",
  "object": "video.generation.task",
  "created": 1779782400,
  "created_at": 1779782400,
  "updated_at": 1779782400,
  "model": "seedance-2.0",
  "status": "queued",
  "billing_status": "frozen"
}

{
  "id": "vidtask_3cb6299b32d24f93a82e8a74b3e06161",
  "object": "video.generation.task",
  "created": 1779782400,
  "created_at": 1779782400,
  "updated_at": 1779782488,
  "model": "seedance-2.0",
  "status": "succeeded",
  "billing_status": "settled",
  "seed": 123456,
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "framespersecond": 24,
  "generate_audio": true,
  "service_tier": "default",
  "content": {
    "video_url": "https://example.com/generated-video.mp4",
    "video_url_expires_at": "2026-05-27T12:00:00Z"
  },
  "usage": {
    "completion_tokens": 540900,
    "total_tokens": 540900
  }
}

{
  "id": "vidtask_3cb6299b32d24f93a82e8a74b3e06161",
  "object": "video.generation.task",
  "created": 1779782400,
  "created_at": 1779782400,
  "updated_at": 1779782488,
  "model": "seedance-2.0",
  "status": "failed",
  "billing_status": "refunded",
  "error": {
    "code": "OutputVideoSensitiveContentDetected",
    "message": "The request failed because the output video may contain sensitive information."
  }
}

素材库接口

平台支持私域素材库，接入方可提交公网 HTTPS 素材 URL，或直接上传本地文件。平台返回平台素材 ID（asset_xxx），后续视频生成时传入 asset://asset_xxx 使用。只有 status=active 的素材才可用于视频生成；素材仍在 processing 或已 failed 时，平台会拒绝创建视频任务，不冻结余额。创建素材时不需要传入 model 或模型 ID，平台会在内部按当前视频素材供应商配置完成路由。

创建素材

POST /v1/assets
Authorization: Bearer <API_KEY>
Content-Type: application/json

JSON URL 上传：

参数	类型	必填	说明
`asset_type`	string	是	素材类型：`image`、`video`、`audio`。
`source_url`	string	是	公网可访问 HTTPS URL，平台会下载校验并保存。图片小于 30 MB，视频小于 50 MB，音频小于 15 MB。
`name`	string	否	素材名称，只能包含中文、字母、数字、下划线和短横线。未传时平台使用默认名称。

curl -X POST "https://{your-domain}/v1/assets" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "avatar-reference",
    "asset_type": "image",
    "source_url": "https://example.com/avatar-reference.png"
  }'

文件上传：

curl -X POST "https://{your-domain}/v1/assets" \
  -H "Authorization: Bearer $API_KEY" \
  -F "asset_type=image" \
  -F "name=avatar-reference" \
  -F "file=@./avatar-reference.png"

参数	类型	必填	说明
`file`	file	是	要上传的图片、视频或音频文件。
`asset_type`	string	是	素材类型：`image`、`video`、`audio`。
`name`	string	否	素材名称，只能包含中文、字母、数字、下划线和短横线。未传时平台使用默认名称。

成功响应（202 Accepted）：

{
  "id": "asset_6f9a4c2b8d1e3a90",
  "uri": "asset://asset_6f9a4c2b8d1e3a90",
  "object": "asset",
  "asset_type": "image",
  "name": "avatar-reference",
  "status": "processing",
  "created_at": 1779782400,
  "updated_at": 1779782400
}

视频生成时使用 uri 字段的值（即 asset://asset_xxx），不要使用 id 字段。

查询素材详情

GET /v1/assets/{id}
Authorization: Bearer <API_KEY>

id 为创建素材返回的 asset_xxx，不要带 asset:// 前缀。

curl "https://{your-domain}/v1/assets/asset_6f9a4c2b8d1e3a90" \
  -H "Authorization: Bearer $API_KEY"

查询素材列表

GET /v1/assets
Authorization: Bearer <API_KEY>

查询参数：

参数	类型	说明
`status`	string	按状态过滤：`processing`、`active`、`failed`。
`asset_type`	string	按类型过滤：`image`、`video`、`audio`。
`name`	string	按名称模糊搜索。
`page`	integer	页码，默认 1。
`page_size`	integer	每页数量，默认 20，最大 100。
`include_resource_url`	integer/string	可选。传入 `1` 时，图片和视频素材会额外返回平台素材 URL；默认不返回。

curl "https://{your-domain}/v1/assets?asset_type=image&status=active&include_resource_url=1" \
  -H "Authorization: Bearer $API_KEY"

resource_url 是平台保存后的素材访问地址，通常为平台 CDN 地址；它不是视频生成请求使用的 asset:// URI。该字段仅在传入 include_resource_url=1 且素材类型为 image 或 video 时返回。

素材状态

状态	说明	可用于生成
`processing`	平台已受理，正在保存或等待处理。	否
`active`	素材可用。	是
`failed`	素材处理失败。	否
`disabled`	素材已被平台禁用。	否

错误码

HTTP 状态码	`error.type`	场景
400	`invalid_request_error`	缺少 `model` 或 `content`、`duration` 超范围、传入 `frames`、传入 `service_tier=flex` 等。
400	`invalid_model`	模型名格式非法。
400	`endpoint_not_configured`	模型视频生成能力未启用。
400	`model_endpoint_mismatch`	模型不能通过视频生成接口调用。
402	`insufficient_balance`	余额不足，无法创建任务。
403	`model_not_allowed`	API Key 白名单未包含该模型。
403	`model_not_visible`	当前域名不可见或未开通该模型。
404	`model_not_found`	模型不存在或未启用。
404	`task_not_found`	任务不存在，或任务不属于当前 API Key。
400	`invalid_asset_type`	`asset_type` 不是 `image`、`video` 或 `audio`。
400	`invalid_asset_url`	`source_url` 非 HTTPS、公网不可访问或格式不合法。
404	`asset_not_found`	素材不存在、不属于当前用户/域名，或传入了无效素材 ID。
409	`asset_not_ready`	素材仍在处理中，不能用于视频生成。
409	`asset_failed`	素材处理失败，不能用于视频生成。
429	`quota_exceeded`	API Key 配额不足。

注意事项

创建任务成功（202）只表示平台已受理，不代表视频已生成完成。
客户端应保存 id 并通过查询接口获取最终状态。
建议查询间隔不少于 3 秒，生产环境建议 5–10 秒。
视频 URL 有有效期，任务成功后请及时下载和转存。
seedance-2.0-fast 不支持 1080p 分辨率。
使用素材库时，只有 status=active 的素材可用于视频生成；在 content[].*.url 中传入 asset://asset_xxx，不要省略 asset:// 前缀。
请求体只需要传入文档列出的公开字段；额外字段可能会被忽略或返回参数错误。

如果只需要简单的文生视频或图生视频，不需要素材库；直接在 content 里传公网 HTTPS URL 或 Base64 即可。

开始使用

API 参考

模型与计费

指南

参考

整体调用流程

创建视频生成任务

请求参数

content 输入对象

文本 `type: text`

图片 `type: image_url`

视频 `type: video_url`

音频 `type: audio_url`

支持的输入组合

提示词中如何引用多个素材

素材格式建议

创建任务示例

文生视频

图生视频（首帧）

多模态参考

使用平台素材库

创建成功响应

查询视频生成任务

响应字段说明

任务状态

账务状态

查询响应示例

素材库接口

创建素材

查询素材详情

查询素材列表

素材状态

错误码

注意事项

​整体调用流程

​创建视频生成任务

​请求参数

​content 输入对象

​文本 type: text

​图片 type: image_url

​视频 type: video_url

​音频 type: audio_url

​支持的输入组合

​提示词中如何引用多个素材

​素材格式建议

​创建任务示例

​文生视频

​图生视频（首帧）

​多模态参考

​使用平台素材库

​创建成功响应

​查询视频生成任务

​响应字段说明

​任务状态

​账务状态

​查询响应示例

​素材库接口

​创建素材

​查询素材详情

​查询素材列表

​素材状态

​错误码

​注意事项

整体调用流程

创建视频生成任务

请求参数

content 输入对象

文本 `type: text`

图片 `type: image_url`

视频 `type: video_url`

音频 `type: audio_url`

支持的输入组合

提示词中如何引用多个素材

素材格式建议

创建任务示例

文生视频

图生视频（首帧）

多模态参考

使用平台素材库

创建成功响应

查询视频生成任务

响应字段说明

任务状态

账务状态

查询响应示例

素材库接口

创建素材

查询素材详情

查询素材列表

素材状态

错误码

注意事项