API 参考

两个端点构成完整闭环：一个提交任务，一个查询结果。接口地址中的域名请替换为你实际使用的接入点。

方法	路径	用途
`POST`	`/v1/contents/generations/tasks`	创建视频生成任务，返回任务号
`GET`	`/v1/contents/generations/tasks/{task_id}`	查询任务状态与结果

认证

所有请求都必须携带 API Key，支持两种写法，二选一：

方式	请求头
标准写法（推荐）	`Authorization: Bearer <API Key>`
简写	`X-API-Key: <API Key>`

认证失败的响应：

json · 401

{
  "error": {
    "message": "Invalid API Key",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

创建任务

POST /v1/contents/generations/tasks

Content-Type: application/json

请求字段

字段	类型	必填	说明
`model`	string	必填	模型 ID。可选值见模型说明：`vipro-main` 或 `vipro-main2.5`。
`content`	array	必填	输入内容数组，可包含文本与素材。结构见下方 content 结构。
`duration`	integer	可选	期望的视频时长（秒）。不传则由上游按默认值处理。参考模式下语义会变化，见参考模式。
`resolution`	string	可选	分辨率：`480p` / `720p` / `1080p`。不传由上游决定；取值会参与计费倍率。
`ratio`	string	可选	画面宽高比，如 `16:9` / `9:16` / `1:1`。不传由上游决定。
`seed`	integer	可选	随机种子。相同 seed + 相同提示词可提高结果复现度。
`generate_audio`	boolean	可选	是否同步生成音频。
`watermark`	boolean	可选	是否在视频上带水印。
`return_last_frame`	boolean	可选	为 `true` 时额外返回尾帧图片，便于接续生成长视频。
`safety_identifier`	string	可选	终端用户唯一标识，用于内容安全追溯。多租户场景建议传。
`reference_mode`	string	可选	在 `vipro-main2.5` 上用来声明本次是生成 / 编辑 / 延长（`generate` / `edit` / `extend`）。编辑与延长本身两个模型都支持，此字段只是让 2.5 更早确定任务类型。详见参考模式。
`source_duration_seconds`	number	可选	在 `vipro-main2.5` 上声明待编辑 / 待延长源视频的时长（秒），影响计费。详见参考模式。

除上表外，上游模型支持的其他字段也会被原样透传。如遇到本文未列出的上游参数，可直接按上游文档传入。

content 结构

content 是一个数组，按顺序描述这次要生成什么。文本用 text 类型，素材用 image_url / video_url / audio_url 类型。

条目类型

type	取值字段	说明
`text`	`text`	提示词。建议放在数组第一位。
`image_url`	`image_url.url`	图片素材地址。
`video_url`	`video_url.url`	视频素材地址。
`audio_url`	`audio_url.url`	音频素材地址。

素材角色 role

素材条目可带 role 字段声明用途：

role	适用类型	说明
`reference_image`	image_url	参考图片。图生视频、多图参考都用它。
`reference_video`	video_url	参考视频。用于视频编辑、视频延长。
`reference_audio`	audio_url	参考音频。用于指定音色或对白。

完整示例

json

{
  "model": "vipro-main2.5",
  "content": [
    { "type": "text", "text": "@图1 的人物走进 @图2 的场景，自然转头看向镜头" },
    { "type": "image_url",
      "image_url": { "url": "https://your-cdn.com/person.jpg" },
      "role": "reference_image" },
    { "type": "image_url",
      "image_url": { "url": "https://your-cdn.com/scene.jpg" },
      "role": "reference_image" }
  ],
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9",
  "seed": 12345
}

素材引用语法：2.5 支持在提示词里用 @图1、@图2、@音频1 指代 content 中对应顺序的素材，模型会据此理解每个素材的角色。

创建响应

提交成功后返回 200，body 中只有任务标识：

json · 200 OK

{
  "id": "task_eGPN7DPXHZxymgJlf0TxYHbRZHDgdOCO",
  "upstream_id": "cgt-20261010080537-ckd7m"
}

字段	类型	说明
`id`	string	任务号，轮询时使用。请持久化保存。
`upstream_id`	string	上游侧的任务标识，排查问题时提供给技术支持可加快定位。

创建响应里不含视频地址。任务成功与否只能在轮询阶段得知——这是异步任务制的固有形态，不是接口缺陷。

查询任务

GET /v1/contents/generations/tasks/{task_id}

响应字段

字段	类型	说明
`id`	string	任务号，与创建时返回的一致。
`upstream_id`	string	上游侧任务标识。
`model`	string	实际执行的模型标识。
`status`	string	任务状态，取值见下方状态取值。
`created_at`	integer	任务创建时间（Unix 秒）。
`updated_at`	integer	状态最后更新时间（Unix 秒）。
`content.video_url`	string	成功时返回，生成的视频地址（临时签名链接）。
`error.code`	string	失败时返回，错误码，如 `OutputVideoSensitiveContentDetected`。
`error.message`	string	失败时返回，错误描述。
`seed`	integer	本次实际使用的随机种子。
`resolution`	string	实际生成分辨率。
`ratio`	string	实际画幅比例。
`duration`	integer	实际视频时长（秒）。
`framespersecond`	integer	帧率。
`generate_audio`	boolean	是否生成了音频。
`output_format`	string	输出容器格式，通常为 `mp4`。
`usage.completion_tokens`	integer	本次任务的上游用量，可用于对账。

成功响应示例：

json · succeeded

{
  "id": "task_eGPN7DPXHZxymgJlf0TxYHbRZHDgdOCO",
  "upstream_id": "cgt-20261010080537-ckd7m",
  "model": "doubao-seedance-2-0-fast-260128",
  "status": "succeeded",
  "created_at": 1791590737,
  "updated_at": 1791591000,
  "content": {
    "video_url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/....mp4?X-Tos-Expires=86400&..."
  },
  "seed": 23751,
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 15,
  "framespersecond": 24,
  "generate_audio": true,
  "output_format": "mp4",
  "draft": false,
  "service_tier": "default",
  "execution_expires_after": 172800,
  "usage": {
    "completion_tokens": 324900,
    "total_tokens": 324900
  }
}

失败响应示例：

json · failed

{
  "id": "task_xxxx",
  "model": "doubao-seedance-2-0-260128",
  "status": "failed",
  "error": {
    "code": "OutputVideoSensitiveContentDetected",
    "message": "The request failed because the output video may contain sensitive information. Request id: 02179160179632000000000000000000000ffffac190631189091"
  },
  "created_at": 1791601796,
  "updated_at": 1791602115,
  "usage": {}
}

失败会自动退款。轮询到 failed 时系统自动退回本次已扣积分，不需要调用方申请。详见计费与错误码。

响应中会附带一个 _proxy_model 字段，是网关内部的路由标识，可直接忽略，不参与业务逻辑。

状态取值

status	是否终态	说明
queued	否	任务已受理，排队等待执行。
running	否	正在生成中。
succeeded	是	生成成功，`content.video_url` 可下载。
failed	是	生成失败，`error` 中有原因，自动退款。
expired	是	任务超时未完成，自动退款。
cancelled	是	任务被取消。

素材要求

图片：传公网可访问的 URL，或 data:image/...;base64,... 形式的 data URL。base64 会在转发前落盘转为公网地址。
视频 / 音频：必须是公网可直连的 URL，不支持本地路径。带视频输入时请阅读参考模式。
真人素材审核：2.5 带人物素材时会先走真人素材入库与审核，这一步是自动的，但需要上游能够抓取到你给的 URL——用内网地址或需要鉴权的链接会失败。
视频素材时长：在 vipro-main2.5 上用 source_duration_seconds 声明源视频时长时，要求在 4~30 秒之间，超出会在提交阶段直接拒绝。

限制

项目	限制
请求体大小	200 MB
素材数量	由上游模型能力决定，建议参考图不超过 10 张
任务号保留	7 天（过期后查询返回 404）
结果视频链接有效期	约 24 小时，请及时转存
失败退款窗口	任务提交后 24 小时内

注意事项

GET /v1/videos/{task_id} 这个路径不存在。 部分早期资料里写过它，但本服务未提供该路由。轮询请一律使用 GET /v1/contents/generations/tasks/{task_id}。

不要把结果链接直接下发给终端用户：它是带签名的临时地址，24 小时后失效，且暴露了存储路径。请转存到你自己的 CDN 后再分发。
任务号要存下来：进程重启、网络抖动都可能让你丢失上下文，任务号是唯一的找回凭据。
同一个任务号重复轮询是安全的，不会重复扣费或重复退款。
创建阶段的失败返回 4xx/5xx 且不扣费（余额不足除外，它在扣费前就被拦下）。生成阶段的失败通过轮询的 status: "failed" 表达，会自动退款。