通用 · 视频

提交视频生成任务，支持文生视频和图生视频。

返回任务 ID，可通过 GET 接口查询任务状态。

请求使用本站 API Key 鉴权，不需要传任何上游账号或签名字段。

图片参考支持两种方式：metadata.content[].image_url.url 传公网 HTTP(S) 图片 URL，或传已创建素材的 asset:// 引用。

asset:// 引用的两类语义：

平台素材（asset://nxt-asset-xxx）：宁享Token 素材库中的素材，提交时本地预检存在性，不存在立即返回 asset_reference_invalid 错误。
厂商原生素材（如 asset://asset-xxx）：直接透传给模型服务，本地不预检（本地库无此 ID）；若素材不存在，任务会进入 failed 状态，错误信息在任务的 error 字段返回（原始错误，如 InvalidParameter: asset not found）。

创建视频生成任务

POST/v1/video/generations

提交视频生成任务，返回任务 ID。

Bearer Token

提交视频生成任务，支持文生视频和图生视频。返回任务 ID，可通过 GET 接口查询任务状态。请求使用本站 API Key 鉴权，不需要传任何上游账号或签名字段。图片参考支持两种方式：metadata.content[].image_url.url 传公网 HTTP(S) 图片 URL，或传已创建素材的 asset:// 引用（平台素材用 asset://nxt-asset-xxx，见下方两类语义说明）。

请求参数

application/json

请求参数

参数	类型	必填	说明
model	string	是	模型 ID（见模型调用 ID 对照表）
prompt	string	是	文本描述提示词
image	string	否	单张参考图片 URL（公网 HTTP(S) URL，不支持 Base64）
images	string[]	否	多张参考图片 URL（公网 HTTP(S) URL，不支持 Base64）
input_reference	string	否	参考图片 URL 别名，会按 image/images 统一处理
size	string	否	尺寸或 provider-specific 画幅参数，具体取值由模型决定
resolution	string	否	输出分辨率（`720p` / `1080p` / `4k`）
ratio	string	否	输出比例（`16:9` / `9:16` / `1:1`）
aspect_ratio	string	否	输出比例别名
duration	integer	否	视频时长（秒）。部分模型优先使用 seconds 或 metadata.duration
seconds	string	否	视频时长别名（秒），部分模型使用该字段
return_last_frame	boolean	否	是否返回生成视频的末帧图片；在支持该能力的模型中生效
metadata	object	否	模型扩展参数。Seedance 随机种子请传 `metadata.seed`；参考视频/音频等 provider-specific content 请传 `metadata.content`

请求示例

bash

curl -X POST /v1/video/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0",
    "prompt": "一只小猫在窗台上看日落，慢动作，电影质感",
    "size": "1920x1080",
    "duration": 5
  }'

响应

200 / 400 / 401 / 402 / 403 / 404 / 429 / 500

任务提交响应

参数	类型	说明
id	string	任务 ID
object	string	固定为 `video`
created_at	integer	任务创建时间（Unix 秒）
model	string	实际使用的模型
status	string	任务状态：`queued` / `in_progress` / `completed` / `failed` / `cancelled`（排队中删除取消的终态）
progress	number	进度百分比 0~100，部分模型提供
error	object	失败时的错误信息，含 `code` / `message`

json

{
  "id": "cgt-20260805190000-xxxx",
  "object": "video",
  "created_at": 1754389200,
  "model": "doubao-seedance-2-0",
  "status": "queued",
  "progress": 0
}

获取视频生成任务状态

GET/v1/video/generations/{task_id}

查询视频生成任务的当前状态、进度与结果。

Bearer Token

通过返回的 id 获取任务状态。任务完成后，生成结果在 metadata.url 字段（视频 URL）。

请求参数

路径参数

参数	类型	必填	说明
task_id	string	是	任务 ID

请求示例

bash

curl /v1/video/generations/cgt-20260805190000-xxxx \
  -H "Authorization: Bearer YOUR_API_KEY"

响应

200 / 401 / 404

任务详情响应

参数	类型	说明
id	string	任务 ID
object	string	固定为 `video`
created_at	integer	任务创建时间（Unix 秒）
completed_at	integer	完成时间（仅 `completed` 状态返回）
model	string	实际使用的模型
status	string	任务状态：`queued` / `in_progress` / `completed` / `failed` / `cancelled`（排队中删除取消的终态）
progress	number	进度百分比 0~100
metadata.url	string	生成视频 URL（完成后提供，有效期 24 小时，每次查询重新签名）
usage	object	用量（`completion_tokens` / `total_tokens`，视频按秒折算 token）
error	object	失败时的错误信息，含 `code` / `message`

json

{
  "id": "cgt-20260805190000-xxxx",
  "object": "video",
  "created_at": 1754389200,
  "completed_at": 1754389320,
  "model": "doubao-seedance-2-0",
  "status": "completed",
  "progress": 100,
  "metadata": {
    "url": "https://cdn.example.com/video.mp4?expires=86400&..."
  },
  "usage": {
    "completion_tokens": 108900,
    "total_tokens": 108900
  }
}

URL 有效期：视频 URL 为对象存储签名链接，有效期 24 小时（签名参数 X-Tos-Expires=86400）。每次查询会重新签名生成新 URL，请及时下载或转存，不要把 URL 当作长期固定地址。
usage 语义：视频任务按生成时长（秒）折算 token 计费，completion_tokens 为折算后的 token 数。

状态码说明

状态码

状态码	含义
200	请求成功
400	请求参数错误（如必填字段缺失、模型不支持）
401	API Key 无效或缺失
402	余额不足
403	当前 Key 无权访问该模型（不在模型白名单内）
404	任务 ID 不存在
429	请求频率超限
500	服务暂不可用，可稍后重试

轮询建议：任务完成后会保持 completed 状态 24~48 小时，请及时保存结果 URL。建议轮询间隔 3~5 秒，超时上限 600 秒。

通用 · 视频 ​

创建视频生成任务 ​

请求参数 ​

请求示例 ​

响应 ​

获取视频生成任务状态 ​

请求参数 ​

请求示例 ​

响应 ​

状态码说明 ​

通用 · 视频

创建视频生成任务

请求参数

请求示例

响应

获取视频生成任务状态

请求参数

请求示例

响应

状态码说明