model 选择;支持本协议的模型共用创建、查询、下载流程。支持本协议的模型统一使用平台地址和公开模型名;调用时使用已获目标模型授权的 API Key,具体权限按所选分组和 Key 设置确定。artsdance-2-0-pro、doubao-seedance-2.5 的基础示例保留供理解协议;同名模型也可能因接入方案 而有不同参数要求,不能仅凭名称照搬素材开关或能力。模型是否开放,以 GET /v1/models 和账号授权为准;具体可选参数、默认值及素材能力以你收到的对应接入指南为准。https://zhuanqicloud.com。| 功能 | 方法与路径 | 当前状态 |
|---|---|---|
| 查看本 Key 可用模型 | GET /v1/models | 已核验 |
| 创建视频任务 | POST /v1/video/generations | 两个模型均有成功记录 |
| 查询单个任务 | GET /v1/video/generations/{task_id} | 两个模型均已只读核验 |
| 下载视频 | GET /v1/videos/{task_id}/content | 两个模型均有下载成功记录 |
| 其他服务协议的原生任务路径 | — | 不属于本页通用协议,不能直接套用其他服务的任务 SDK |
| 参考素材自动处理 | 随 POST /v1/video/generations 提交 | doubao-seedance-2.5 支持图片、视频和音频参考;平台随任务自动处理,客户无需单独执行入库操作,详见第 5 节 |
| 任务取消/删除、生成回调、幂等键、批量任务列表 | — | 不在本页保证范围内 |
model 选择模型。只有同一个 Key 实际具备多个模型的调用权限时,才能共用该 Key;模型分属不同分组且当前 Key 未覆盖目标模型时,应使用对应分组的 Key,不能仅修改 model 跨分组调用。调用前以该 Key 的 GET /v1/models 返回核对可用模型。/v1/video/generations/{task_id} 与 /v1/videos/{task_id} 的查询响应解析方式。本页统一使用前者查询、后者的 /content 子路径下载。Content-Type: application/json。Key 在客户自己的服务端配置,不放进前端网页、公开仓库或第三方视频下载请求。ZHUANQI_API_KEY 由客户自行设置。{
"model": "artsdance-2-0-pro",
"prompt": "清晨的海边,波浪轻柔拍打沙滩,写实电影感,无字幕。",
"duration": 5,
"metadata": {
"resolution": "720p",
"ratio": "16:9",
"generate_audio": false
}
}doubao-seedance-2.5 时,将 model 设为该名称,并使用其所属分组下具备该模型权限的 Key。本例基础参数可沿用;其他模型应按各自参数要求填写。model 指定:| 字段 | 类型 | 要求与含义 |
|---|---|---|
model | string | 必填;当前 Key 可用且兼容本协议的公开模型名 |
prompt | string | 简单文生视频的非空提示词;使用 content 时,可由其中的文本项提供 |
content | array | 参考素材请求放在顶层;至少含一项非空文本。不要只传媒体、不传文字 |
duration | integer | 推荐显式填写方案允许的正整数秒,基础推荐值 5。本文 Artsdance 方案省略时采用10秒;其他方案的默认值与范围按对应指南,不把某一模型范围推广到全部模型 |
return_last_frame | boolean | 在已开通尾帧能力的方案中,true请求输出生成视频的尾帧。本文 Artsdance 方案与既有2.5示例均已接入;可放顶层或metadata,顶层优先,必须是JSON布尔值。不同查询响应的读取方式见第7.1节 |
resolution | string | 是否可省略及默认档位按对应接入方案;本文 Artsdance 方案与既有2.5示例均可省略并默认720p。可放顶层或metadata.resolution,顶层优先;显式空值不等于省略,无效档位会报错。不将该默认值推广到其他模型 |
ratio | string | 画面比例,可放顶层或 metadata.ratio;推荐明确填写 16:9 |
generate_audio | boolean | 是否生成音轨,可放顶层或 metadata.generate_audio;文生视频验收基线为 false,有声参考场景见第 5 节 |
metadata | object | 兼容容器,支持字段按接入方案。本文 Artsdance 方案包含duration、resolution、ratio、seed、watermark、generate_audio、return_last_frame;相同字段顶层优先,保留显式false和seed:0。不能据此假定其他方案兼容全部字段 |
asset | boolean | doubao-seedance-2.5 的媒体处理开关,媒体示例为 true;保持顶层。它不是素材 ID,也不代表已完成真人授权 |
width / height | integer | 兼容字段会被忽略;实际尺寸由分辨率、比例及编码对齐决定 |
content 时,提示词取自其中的文本项;不要只保留媒体项,再期待顶层 prompt 自动补入。建议只选择一种提示词写法,避免相互冲突。| 模型 | 当前接入认可的分辨率档位 | 已验证推荐基线 |
|---|---|---|
artsdance-2-0-pro | 480p、720p、1080p、4k | 5 秒、720p、16:9、无音轨 |
doubao-seedance-2.5 | 480p、720p、1080p | 5 秒、720p、16:9、无音轨;另有 4 秒/480p 成功记录 |
| 能力 | artsdance-2-0-pro | doubao-seedance-2.5 |
|---|---|---|
| 文生视频、查询、下载 | 已验证 | 已验证 |
| 参考图片 | 尚未完成本页生成验收 | 已验证:4秒 / 480p,完成生成、查询和下载 |
| 参考视频 | 尚未完成本页生成验收 | 已验证:4秒 / 480p,完成生成、查询和下载 |
| 参考音频 | 尚未完成本页生成验收 | 已验证:4秒 / 480p,完成生成、查询和下载;成片已检出音轨 |
asset 开关 | 不沿用另一模型的媒体开关 | 参考素材显式传 true,省略按 false |
| 提示词 | prompt 或含非空文本项的顶层 content | 同左;有 content 时以其中的文本为准 |
自动时长 duration:-1 | 当前不支持 | 当前不支持 |
| 首尾帧输入、编辑、延长 | 本页未完成验收 | 本页未完成验收,不能套用参考素材示例直接承诺可用 |
duration:-1(自动时长),接入校验会拒绝。不要将其他协议的 seconds、size 或 multipart 上传示例套入本接口。doubao-seedance-2.5 时,将可直接读取的 HTTPS 图片、视频或音频链接放入生成请求,平台自动完成本次任务所需的素材处理,客户无需先单独上传入库或取得素材 ID。重复使用同一素材时,在新任务中再次提交有效链接即可;请自行保存原文件,并确保链接在素材读取期间可访问。其他模型按各自已说明的参考素材能力使用。doubao-seedance-2.5 的图片、视频或音频参考时,在请求最外层明确填写 asset:true,并在 content 中提供文字和素材链接,具体写法见以下示例。该字段开启本次任务的素材处理,不是素材 ID 或真人授权凭证;跨任务复用请继续提供原素材的有效链接。| 用途 | type | 文件链接字段 | role |
|---|---|---|---|
| 参考图片 | image_url | image_url.url | reference_image |
| 参考视频 | video_url | video_url.url | reference_video |
| 参考音频 | audio_url | audio_url.url | reference_audio |
| 首帧图片(未验收) | image_url | image_url.url | first_frame |
| 尾帧图片(未验收) | image_url | image_url.url | last_frame |
content 中必须保留非空 text 项;顶层 prompt 不会自动补进已有的 content。不要混合首尾帧角色与 reference_* 角色。单次生成的具体多素材组合仍需单独验收。POST https://zhuanqicloud.com/v1/video/generations,使用第 2 节的平台鉴权。{
"model": "doubao-seedance-2.5",
"asset": true,
"content": [
{
"type": "text",
"text": "Use the reference image to show a bumblebee gently moving on a flower. Natural daylight, no text."
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/reference.png"
},
"role": "reference_image"
}
],
"duration": 4,
"resolution": "480p",
"ratio": "16:9",
"generate_audio": false
}POST https://zhuanqicloud.com/v1/video/generations,使用第 2 节的平台鉴权。{
"model": "doubao-seedance-2.5",
"asset": true,
"content": [
{
"type": "text",
"text": "Create a new peaceful nature shot inspired by the reference video scenery and camera movement. No text."
},
{
"type": "video_url",
"video_url": {
"url": "https://example.com/reference.mp4"
},
"role": "reference_video"
}
],
"duration": 4,
"resolution": "480p",
"ratio": "16:9",
"generate_audio": false
}POST https://zhuanqicloud.com/v1/video/generations,使用第 2 节的平台鉴权。{
"model": "doubao-seedance-2.5",
"asset": true,
"content": [
{
"type": "text",
"text": "Create a colorful abstract animation synchronized to the rhythm of the reference music. No people or text."
},
{
"type": "audio_url",
"audio_url": {
"url": "https://example.com/reference.mp3"
},
"role": "reference_audio"
}
],
"duration": 4,
"resolution": "480p",
"ratio": "16:9",
"generate_audio": true
}generate_audio:false;有声生成不能只根据上传了音频就推断成功,应检查成片是否含音轨。doubao-seedance-2.5 媒体输入的文档约束,数量和大小上限尚未逐项做边界生成测试;首次接入从单份素材开始。| 素材 | 格式及限制 |
|---|---|
| 图片 | JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC、HEIF;单张小于30MB;单边300~6000像素,宽高比0.4~2.5;参考模式最多30张 |
| 视频 | MP4/MOV;单份不超过200MB;24~60fps;单边300~6000像素,宽高比0.4~2.5,总像素407696~8295044;单段2~30秒、合计不超过30秒;最多10份 |
| 音频 | WAV/MP3;单份不超过15MB;单段2~30秒、合计不超过30秒;最多10份 |
asset:// ID 尚未纳入本页稳定示例;视频不要使用 Base64。ratio:adaptive,尚未完成本页验收。视频编辑需要的自动时长 duration:-1 当前会被平台拒绝,因此本页不把编辑、延长和完整官方协议列为已开放功能。asset:true 不表示免审核,也不保证任意真人照片可直接生成。asset:// 标识。{
"id": "task_EXAMPLE",
"task_id": "task_EXAMPLE",
"object": "video",
"model": "artsdance-2-0-pro",
"status": "queued",
"progress": 0,
"created_at": 1789530000
}task_id,缺失时兼容读取 id。不要使用后续查询响应里的数字 data.id,也不要改用嵌套的其他任务标识。{
"code": "success",
"message": "",
"data": {
"task_id": "task_EXAMPLE",
"status": "SUCCESS",
"progress": "100%",
"fail_reason": "",
"result_url": "https://example.com/result.mp4",
"submit_time": 1789530000,
"start_time": 1789530020,
"finish_time": 1789530300,
"data": {
"usage": {
"completion_tokens": 108900,
"total_tokens": 108900
}
}
}
}| 字段 | 客户端处理 |
|---|---|
顶层 code | success 表示查询操作成功,不能据此判断视频成功 |
data.status | 业务状态判断依据,使用下表 |
data.progress | 百分比字符串;不能当作准确剩余时间 |
data.fail_reason | 任务失败原因 |
data.result_url | 成功时可能返回的成片地址;优先使用平台下载接口 |
data.submit_time / start_time / finish_time | Unix 秒时间戳;未发生的阶段可能是 0,不把尚未生成的时间误算为耗时 |
data.data.usage.completion_tokens | 完成后实际返回的输出 Tokens 整数 |
data.data.usage.total_tokens | 完成后实际返回的总 Tokens 整数 |
data.data 的其他字段可能随模型不同而变化。2.5 可能包含 content.video_url,Artsdance 可能使用其他嵌套结构;不要把其中一种结构套给另一个模型。108900 或 108,900。未提供的用量字段显示“未提供”,不能用价格反推、不能补成 0、不能把视频 Tokens 当作提示词字数。短时间内完成状态与最终账单可能存在结算先后,以最终使用记录为准。GET /v1/video/generations/{task_id}:读取 data.data.content.last_frame_url。GET /v1/videos/{task_id}:读取 metadata.last_frame_url。Content-Type 为准,不要固定按PNG解析;2026-09-21实测返回JPEG,1280×720,与视频尺寸一致。未返回链接时表示当前响应未提供尾帧,不能拿视频地址代替。{
"model": "doubao-seedance-2.5",
"prompt": "一只纸船在平静的湖面缓缓漂动,固定镜头。",
"duration": 4,
"ratio": "16:9",
"generate_audio": false,
"return_last_frame": true
}data.status | 处理 |
|---|---|
NOT_START、QUEUED、SUBMITTED | 等待并继续查询 |
IN_PROGRESS | 生成中,继续查询 |
SUCCESS | 停止轮询,下载视频 |
FAILURE | 停止轮询,读取失败原因和最终使用记录 |
| 其他值或缺失 | 保存本地诊断信息,停止自动处理并联系支持 |
Retry-After;401/403 应先处理 Key/分组权限。任何查询错误都不应 该触发重新创建任务。SUCCESS 后:{"code":"invalid_resolution","message":"unsupported resolution for model","data":null}{"error":{"code":"...","message":"..."}};客户端应同时处理 HTTP 状态和两种错误包装,不依赖固定中文文案。| 情况 | 处理 |
|---|---|
| 401 / Key 无效 | 检查 Key 是否有效、是否正确携带 Bearer |
| 403 / 分组、模型权限或余额问题 | 根据实际错误检查账户、Key、允许模型和可用余额 |
invalid_duration | 时长错误;本页当前版本不要传 -1;明确未创建时再修正提交 |
invalid_resolution | 检查显式分辨率是否为空或不被方案接受;本文Artsdance方案与既有2.5示例省略时默认720p,其他方案按对应指南。不要把显式空值当省略 |
invalid_content | 检查非空文本是否在正确位置、content 是否为数组 |
task_not_exist | 检查平台任务 ID 和查询账号是否正确;不要用数字记录 ID |
| 429 | 请求受限;保留任务 ID,按返回信息延迟查询;不能推断是生成失败 |
| 5xx、断线、超时、无法解析创建响应 | 任务可能已接受;先查任务记录,禁止自动重发创建 |
data.status;成功后下载;读取实际 usage;超时后续查同一任务。正式使用参考素材前单独完成场景验收。service@zhuanqicloud.com。排查请提供模型、任务 ID、请求时间及脱敏错误;不要提交完整 Key 或公开带签名的成片 URL。