Skip to Content
视频生成Seedance

Seedance

Video Tasks
创建任务POST /ark/api/v3/contents/generations/tasks
查询任务GET /ark/api/v3/contents/generations/tasks/{task_id}
doubao-seedance-2-5doubao-seedance-2-5-flash
doubao-seedance-2-0doubao-seedance-2-0-minidoubao-seedance-2-0-fast
dreamina-seedance-2-5dreamina-seedance-2-0

火山方舟 Ark 协议

创建视频生成任务

POST /ark/api/v3/contents/generations/tasks

请求参数

参数类型说明
modelstring模型名,见上方模型列表。
contentarray多模态输入数组,至少包含一个输入项;type、内容字段和 role 见下表。
generate_audioboolean是否生成音频,默认 true,以模型实际能力为准。
ratiostring16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9 / adaptive。Seedance 2.5 的首帧、首尾帧、视频编辑和视频延长任务不得指定具体比例,见下方任务类型限制。
durationinteger视频时长,单位秒;取值范围和默认值因模型与任务类型而异,见下表。
resolutionstring480p / 720p / 1080p,以模型实际能力为准。开启样片模式时只能使用 480p。
draftbooleanSeedance 2.5 样片模式开关,默认 false;设为 true 时生成 480p 预览视频。
omni_reference_task_typestring仅适用于 Seedance 2.5 全模态参考生视频任务;可选值为 auto / reference / edit / extend,默认 auto。
output_formatstring仅适用于 Seedance 2.5;mp4 / mov,默认 mp4。mov 适合专业后期处理,但部分播放器可能不兼容。

duration 模型差异

模型 / 任务类型固定时长-1 智能时长
Seedance 2.5 普通生成任务4 至 30 秒支持,且为默认值;模型在有效范围内自主选择整数秒时长。
Seedance 2.5 视频编辑任务不支持指定固定输出时长必须设置为 -1;待编辑视频时长必须为 4 至 30 秒,输出时长与输入视频基本一致。
Seedance 2.0 系列4 至 15 秒支持,模型在有效范围内智能选择时长。

Seedance 2.5 任务类型限制

任务omni_reference_task_type输入与参数限制
自动判定auto,或省略模型根据输入素材和提示词判定任务类型;参数与实际任务类型不兼容时,任务创建后可能以 InvalidParameter.TaskTypeConstraint 失败。
全模态参考生视频reference使用参考图片、参考视频或参考音频生成新视频;ratio 和 duration 遵循通用限制。
视频编辑editcontent 至少包含一个 4 至 30 秒的 reference_video;ratio 必须为 adaptive,duration 必须为 -1。
视频延长extendcontent 至少包含一个 reference_video;ratio 必须为 adaptive。
首帧和首尾帧任务:省略 ratio(默认 adaptive)或传入 adaptive,不得传入具体比例。输出视频比例跟随 first_frame;传入 16:9 等具体比例会返回 InvalidParameter.TaskTypeConstraint。

显式指定任务类型后,提示词意图仍须与该类型一致,否则任务创建后可能以 InvalidParameter.TaskTypeMismatch 失败。

content 输入项

用途type内容字段role
提示词texttext不需要
首帧图片image_urlimage_url.urlfirst_frame
尾帧图片image_urlimage_url.urllast_frame
参考图片image_urlimage_url.urlreference_image
参考视频video_urlvideo_url.urlreference_video
参考音频audio_urlaudio_url.urlreference_audio
样片任务draft_taskdraft_task.id不需要
  • 素材可使用公网可访问的文件直链。素材状态为 Active 后,也可使用 asset://{asset_id}。
  • 音频不能作为唯一参考素材;使用参考音频时,需同时提供图片或视频素材。
  • 提示词中可按素材顺序使用“图片1”等方式指代,顺序对应 content 数组中的素材顺序。

样片模式

Seedance 2.5 可先生成样片,确认场景结构、镜头调度、主体动作与提示词意图。创建样片时设置 draft: true 和 resolution: "480p";使用其他分辨率会报错。draft 默认为 false,用于正常生成视频。

样片符合预期后,在正式视频请求的 content 数组中传入 { "type": "draft_task", "draft_task": { "id": "<DRAFT_TASK_ID>" } }。id 使用创建样片时返回的任务 ID,并先查询确认样片任务已成功。该输入类型仅适用于 Seedance 2.5。

官方参考:视频生成完整参数视频生成完整参数

调用示例

curl -X POST "https://api.example.com/ark/api/v3/contents/generations/tasks" \ -H "Authorization: Bearer <YOUR_API_KEY>" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "model": "doubao-seedance-2-5", "content": [ { "type": "text", "text": "写实汽车广告风格,一辆深银色概念跑车为全片唯一主体。0-5秒:16:9大全景,清晨薄雾中的山间公路,镜头贴近路面缓慢前移,车辆从弯道驶入画面;5-10秒:低机位侧向跟拍,车身反射自然晨光,轮胎与路面运动符合真实物理规律,背景产生克制的速度感;10-15秒:镜头平滑切换至前方四分之三英雄视角,车辆在观景台稳稳停下,最后两秒定格。全程主体外观和色彩一致,运镜连续,画面无跳变、无字幕、无水印。生成与画面同步的引擎声、轮胎摩擦声和自然环境声,禁止旁白。" } ], "generate_audio": true, "ratio": "16:9", "duration": 15, "resolution": "720p", "output_format": "mp4" }'
curl -X POST "https://api.example.com/ark/api/v3/contents/generations/tasks" \ -H "Authorization: Bearer <YOUR_API_KEY>" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "model": "dreamina-seedance-2-5", "content": [ { "type": "text", "text": "写实汽车广告风格,一辆深银色概念跑车为全片唯一主体。0-5秒:16:9大全景,清晨薄雾中的山间公路,镜头贴近路面缓慢前移,车辆从弯道驶入画面;5-10秒:低机位侧向跟拍,车身反射自然晨光,轮胎与路面运动符合真实物理规律,背景产生克制的速度感;10-15秒:镜头平滑切换至前方四分之三英雄视角,车辆在观景台稳稳停下,最后两秒定格。全程主体外观和色彩一致,运镜连续,画面无跳变、无字幕、无水印。生成与画面同步的引擎声、轮胎摩擦声和自然环境声,禁止旁白。" } ], "generate_audio": true, "ratio": "16:9", "duration": 15, "resolution": "720p", "output_format": "mp4" }'

创建成功后保存响应中的 id,用于后续查询任务。

查询视频生成任务

GET /ark/api/v3/contents/generations/tasks/{task_id}

curl "https://api.example.com/ark/api/v3/contents/generations/tasks/<task_id>" \ -H "Authorization: Bearer <YOUR_API_KEY>" \ -H "Accept: application/json"
{ "id": "cgt-20260730175939-nbf6p", "model": "doubao-seedance-2-5", "status": "succeeded", "content": { "video_url": "https://example.com/generated-video.mp4" }, "usage": { "completion_tokens": 110000, "total_tokens": 110000 }, "error": null, "created_at": 1779381684, "updated_at": 1779381744, "seed": 10270, "resolution": "720p", "ratio": "16:9", "duration": 15, "framespersecond": 24, "service_tier": "default", "execution_expires_after": 172800, "generate_audio": true, "draft": false, "priority": 0 }
{ "id": "cgt-20260730175939-nbf6p", "model": "dreamina-seedance-2-5", "status": "succeeded", "content": { "video_url": "https://example.com/generated-video.mp4" }, "usage": { "completion_tokens": 110000, "total_tokens": 110000 }, "error": null, "created_at": 1779381684, "updated_at": 1779381744, "seed": 10270, "resolution": "720p", "ratio": "16:9", "duration": 15, "framespersecond": 24, "service_tier": "default", "execution_expires_after": 172800, "generate_audio": true, "draft": false, "priority": 0 }

任务状态包括 queued、running、succeeded、failed、cancelled 与 expired。建议每 3 至 5 秒轮询一次,对 HTTP 429 和 5xx 使用指数退避。任务成功后读取 content.video_url,失败后读取 error;根据样片生成的任务还可从 draft_task_id 读取样片任务 ID。

删除视频生成任务

DELETE /ark/api/v3/contents/generations/tasks/{task_id}

curl -X DELETE "https://api.example.com/ark/api/v3/contents/generations/tasks/<task_id>" \ -H "Authorization: Bearer <YOUR_API_KEY>" \ -H "Accept: application/json"
参数类型必填说明
task_idstring是创建任务时返回的任务 ID。
HTTP 状态码错误码说明
204-删除成功,无响应体。
409InvalidAction.RunningTaskDeletion当前任务状态不支持删除。
404ResourceNotFound任务不存在或已删除。

仅支持删除状态为 succeeded、failed 或 expired 的任务。删除后无法再查询该任务,重复删除返回 HTTP 404。

素材资产库

素材资产库支持 Bearer API-Key 和 AK/SK 签名两种鉴权方式。常规调用推荐使用 Bearer API-Key,本文示例均采用该方式。AK/SK 签名用于兼容火山方舟 Ark 签名规范。

接口索引

接口名称Action说明
创建素材资产CreateAsset创建素材并关联素材组。
查询素材资产详情GetAsset查询指定素材的详情和处理状态。
查询素材资产列表ListAssets分页查询素材列表。
更新素材资产UpdateAsset更新指定素材的名称。
删除素材资产DeleteAsset删除指定素材。
创建素材资产组CreateAssetGroup创建素材组,用于归类素材。
查询素材资产组详情GetAssetGroup查询指定素材组的详情。
查询素材资产组列表ListAssetGroups分页查询素材组列表。
更新素材资产组UpdateAssetGroup更新指定素材组的名称和描述。
删除素材资产组DeleteAssetGroup删除指定素材组及组内素材。
拉起真人人像认证 H5CreateVisualValidateSession创建真人人像认证会话。
获取真人人像 Asset Group IDGetVisualValidateResult查询真人人像认证结果。
  • 素材和可选素材组接口使用以下 Action 格式:POST /api/v3/?Action={Action}&Version=2024-01-01。
  • 字段名区分大小写。
  • 即使没有筛选条件,也要发送空 JSON 对象 {}。

官方参考:素材库接口素材库接口

AK/SK 签名鉴权(可选)

前往 API 密钥,在目标 API Key 的扩展菜单中选择 Ark AK/SK 并生成凭证。

  • 每个 API Key 仅保留一组有效的 Ark AK/SK。
  • Secret Key 仅在生成或重新生成时展示一次,请立即妥善保存。
  • 重新生成后,原 AK/SK 立即失效。

Ark AK/SK 调用素材资产库的 Action 接口:POST /api/v3/?Action={Action}&Version=2024-01-01。请求使用 Ark 标准 HMAC-SHA256 签名:

签名项值
算法HMAC-SHA256
Credential ScopeYYYYMMDD/cn-beijing/ark/request
Signed Headerscontent-type;host;x-content-sha256;x-date
X-DateUTC 时间,格式为 YYYYMMDDTHHmmssZ;与服务端时间偏差不得超过 15 分钟。
X-Content-Sha256请求体的 SHA-256 十六进制摘要。
POST /api/v3/?Action=ListAssets&Version=2024-01-01 Authorization: HMAC-SHA256 Credential=<ARK_ACCESS_KEY>/<YYYYMMDD>/cn-beijing/ark/request, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature=<SIGNATURE> Content-Type: application/json Host: <API_HOST> X-Content-Sha256: <PAYLOAD_SHA256> X-Date: <UTC_TIMESTAMP> {}

素材资产

创建素材资产

POST /api/v3/?Action=CreateAsset&Version=2024-01-01

字段类型必填默认值说明
URLstring是-服务端可访问的公网 HTTP 或 HTTPS 素材地址,最多 8192 字节。
GroupIdstring是-素材组 ID。
Namestring否reference素材名称,最多 64 个字符。
AssetTypestring否ImageImage / Video / Audio
curl -X POST "https://api.example.com/api/v3/?Action=CreateAsset&Version=2024-01-01" \ -H "Authorization: Bearer <YOUR_API_KEY>" \ -H "Idempotency-Key: <UNIQUE_REQUEST_ID>" \ -H "Content-Type: application/json" \ -d '{ "GroupId": "group-xxxxxxxx", "Name": "first-frame", "URL": "https://example.com/first-frame.jpg", "AssetType": "Image" }' # 响应示例 { "ResponseMetadata": { "RequestId": "req-xxxxxxxx", "Action": "CreateAsset", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" }, "Result": { "Id": "asset-xxxxxxxx" } }

创建成功表示素材已受理。继续调用 GetAsset 查询处理状态。

查询素材资产详情

POST /api/v3/?Action=GetAsset&Version=2024-01-01

字段类型必填说明
Idstring是素材 ID。
curl -X POST "https://api.example.com/api/v3/?Action=GetAsset&Version=2024-01-01" \ -H "Authorization: Bearer <YOUR_API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "Id": "asset-xxxxxxxx" }' # 响应示例 { "ResponseMetadata": { "RequestId": "req-xxxxxxxx", "Action": "GetAsset", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" }, "Result": { "Id": "asset-xxxxxxxx", "Name": "first-frame", "URL": "https://example.com/asset-url", "AssetType": "Image", "Status": "Active", "Moderation": { "Strategy": "Default" }, "Error": { "Code": "", "Message": "" }, "CreateTime": "2026-07-20T04:00:00Z", "UpdateTime": "2026-07-20T04:00:03Z" } }
状态说明
Processing素材正在处理,继续轮询。
Active素材可用于创建视频任务。
Failed素材处理失败或已经失效,读取 Error 后重新上传。

查询素材资产列表

POST /api/v3/?Action=ListAssets&Version=2024-01-01

字段类型必填默认值说明
Filter.GroupIdsarray否-素材组 ID 列表,最多 100 项;省略时查询当前 API Key 下的全部素材。
Filter.GroupTypestring否-素材组类型,可选 AIGC 或 LivenessFace。
Filter.Statusesarray否-Processing / Active / Failed
Filter.Namestring否-按素材名称关键字筛选。
PageNumberinteger否1页码,大于等于 1。
PageSizeinteger否10每页数量,1 至 100。
SortBystring否CreateTimeCreateTime / UpdateTime / GroupId
SortOrderstring否DescAsc / Desc
curl -X POST "https://api.example.com/api/v3/?Action=ListAssets&Version=2024-01-01" \ -H "Authorization: Bearer <YOUR_API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "Filter": { "Statuses": ["Active"] }, "PageNumber": 1, "PageSize": 20, "SortBy": "CreateTime", "SortOrder": "Desc" }' # 响应示例 { "ResponseMetadata": { "RequestId": "req-xxxxxxxx", "Action": "ListAssets", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" }, "Result": { "Items": [ { "Id": "asset-xxxxxxxx", "Name": "first-frame", "URL": "asset://asset-xxxxxxxx", "AssetType": "Image", "Status": "Active", "Moderation": { "Strategy": "Default" }, "Error": { "Code": "", "Message": "" }, "CreateTime": "2026-07-20T04:00:00Z", "UpdateTime": "2026-07-20T04:00:03Z" } ], "TotalCount": 1, "PageNumber": 1, "PageSize": 20 } }

更新素材资产

POST /api/v3/?Action=UpdateAsset&Version=2024-01-01

字段类型必填说明
Idstring是素材 ID。
Namestring是新的素材名称,最多 64 个字符。
curl -X POST "https://api.example.com/api/v3/?Action=UpdateAsset&Version=2024-01-01" \ -H "Authorization: Bearer <YOUR_API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "Id": "asset-xxxxxxxx", "Name": "first-frame-v2" }' # 响应示例 { "ResponseMetadata": { "RequestId": "req-xxxxxxxx", "Action": "UpdateAsset", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" }, "Result": { "Id": "asset-xxxxxxxx" } }

删除素材资产

POST /api/v3/?Action=DeleteAsset&Version=2024-01-01

字段类型必填说明
Idstring是待删除的素材 ID。
curl -X POST "https://api.example.com/api/v3/?Action=DeleteAsset&Version=2024-01-01" \ -H "Authorization: Bearer <YOUR_API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "Id": "asset-xxxxxxxx" }' # 响应示例 { "ResponseMetadata": { "RequestId": "req-xxxxxxxx", "Action": "DeleteAsset", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" }, "Result": {} }
  • 删除完成后再次删除同一素材按成功处理。
  • 素材仍在处理且暂时没有可删除资源时,接口可能返回 asset_not_ready,请稍后重试。

素材资产组

创建素材资产组

POST /api/v3/?Action=CreateAssetGroup&Version=2024-01-01

字段类型必填默认值说明
Namestring是-素材组名称,最多 64 个字符。
Descriptionstring否-素材组描述,最多 300 个字符。
GroupTypestring否AIGC素材组类型,仅支持 AIGC。
curl -X POST "https://api.example.com/api/v3/?Action=CreateAssetGroup&Version=2024-01-01" \ -H "Authorization: Bearer <YOUR_API_KEY>" \ -H "Idempotency-Key: <UNIQUE_REQUEST_ID>" \ -H "Content-Type: application/json" \ -d '{ "Name": "product-video", "Description": "product video assets", "GroupType": "AIGC" }' # 响应示例 { "ResponseMetadata": { "RequestId": "req-xxxxxxxx", "Action": "CreateAssetGroup", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" }, "Result": { "Id": "group-xxxxxxxx" } }

查询素材资产组详情

POST /api/v3/?Action=GetAssetGroup&Version=2024-01-01

字段类型必填说明
Idstring是素材组 ID。
curl -X POST "https://api.example.com/api/v3/?Action=GetAssetGroup&Version=2024-01-01" \ -H "Authorization: Bearer <YOUR_API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "Id": "group-xxxxxxxx" }' # 响应示例 { "ResponseMetadata": { "RequestId": "req-xxxxxxxx", "Action": "GetAssetGroup", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" }, "Result": { "Id": "group-xxxxxxxx", "Name": "product-video", "Description": "product video assets", "GroupType": "AIGC", "CreateTime": "2026-07-20T04:00:00Z", "UpdateTime": "2026-07-20T04:00:00Z" } }

查询素材资产组列表

POST /api/v3/?Action=ListAssetGroups&Version=2024-01-01

字段类型必填默认值说明
Filter.GroupIdsarray否-素材组 ID 列表,最多 100 项。
Filter.Namestring否-按素材组名称关键字筛选。
Filter.GroupTypestring否-素材组类型,可选 AIGC 或 LivenessFace。
PageNumberinteger否1页码,大于等于 1。
PageSizeinteger否10每页数量,1 至 100。
SortBystring否CreateTimeCreateTime / UpdateTime
SortOrderstring否DescAsc / Desc
curl -X POST "https://api.example.com/api/v3/?Action=ListAssetGroups&Version=2024-01-01" \ -H "Authorization: Bearer <YOUR_API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "PageNumber": 1, "PageSize": 20, "SortBy": "CreateTime", "SortOrder": "Desc" }' # 响应示例 { "ResponseMetadata": { "RequestId": "req-xxxxxxxx", "Action": "ListAssetGroups", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" }, "Result": { "Items": [ { "Id": "group-xxxxxxxx", "Name": "product-video", "Description": "product video assets", "GroupType": "AIGC", "CreateTime": "2026-07-20T04:00:00Z", "UpdateTime": "2026-07-20T04:00:00Z" } ], "TotalCount": 1, "PageNumber": 1, "PageSize": 20 } }

更新素材资产组

POST /api/v3/?Action=UpdateAssetGroup&Version=2024-01-01

字段类型必填说明
Idstring是素材组 ID。
Namestring否新的素材组名称,最多 64 个字符。
Descriptionstring否新的素材组描述,最多 300 个字符;可传空字符串清空描述。

Name 和 Description 至少传一个。

curl -X POST "https://api.example.com/api/v3/?Action=UpdateAssetGroup&Version=2024-01-01" \ -H "Authorization: Bearer <YOUR_API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "Id": "group-xxxxxxxx", "Name": "product-video-v2", "Description": "updated product video assets" }' # 响应示例 { "ResponseMetadata": { "RequestId": "req-xxxxxxxx", "Action": "UpdateAssetGroup", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" }, "Result": { "Id": "group-xxxxxxxx" } }

删除素材资产组

POST /api/v3/?Action=DeleteAssetGroup&Version=2024-01-01

字段类型必填说明
Idstring是待删除的素材组 ID。
curl -X POST "https://api.example.com/api/v3/?Action=DeleteAssetGroup&Version=2024-01-01" \ -H "Authorization: Bearer <YOUR_API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "Id": "group-xxxxxxxx" }' # 响应示例 { "ResponseMetadata": { "RequestId": "req-xxxxxxxx", "Action": "DeleteAssetGroup", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" }, "Result": {} }

真人人像认证

拉起真人人像认证 H5

POST /api/v3/?Action=CreateVisualValidateSession&Version=2024-01-01

字段类型必填默认值说明
CallbackURLstring是-公网可访问的 HTTPS 回调地址。
ProjectNamestring否default项目名称。
curl -X POST "https://api.example.com/api/v3/?Action=CreateVisualValidateSession&Version=2024-01-01" \ -H "Authorization: Bearer <YOUR_API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "CallbackURL": "https://example.com/verification/callback", "ProjectName": "default" }'

响应示例:

{ "ResponseMetadata": { "RequestId": "req-xxxxxxxx", "Action": "CreateVisualValidateSession", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" }, "Result": { "BytedToken": "vvs-xxxxxxxx", "H5Link": "https://example.com/visual-validation/xxxxxxxx", "CallbackURL": "https://example.com/verification/callback" } }

获取真人人像 Asset Group ID

POST /api/v3/?Action=GetVisualValidateResult&Version=2024-01-01

字段类型必填默认值说明
BytedTokenstring是-创建真人人像认证会话返回的认证令牌。
ProjectNamestring否default项目名称。
curl -X POST "https://api.example.com/api/v3/?Action=GetVisualValidateResult&Version=2024-01-01" \ -H "Authorization: Bearer <YOUR_API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "BytedToken": "vvs-xxxxxxxx", "ProjectName": "default" }'

响应示例:

{ "ResponseMetadata": { "RequestId": "req-xxxxxxxx", "Action": "GetVisualValidateResult", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" }, "Result": { "GroupId": "group-xxxxxxxx" } }

错误码

创建或查询视频任务时,如果 HTTP 状态码不是 2xx,响应使用以下结构。param 仅在能够定位到具体参数时返回。

{ "error": { "code": "InvalidParameter", "message": "One or more parameters specified in the request are not valid.", "param": "duration", "type": "BadRequest" } }
HTTP 状态码常见 error.code处理建议
400InvalidParameter
MissingParameter
各类 SensitiveContentDetected
检查必填参数、模型支持范围和素材格式;命中内容安全检查时更换输入。不要使用相同请求直接重试。
401AuthenticationError检查 Bearer API Key 是否缺失、错误或已失效;使用 AK/SK 签名时,检查 Access Key、签名和请求时间。
403AccessDenied
AccountOverdueError
OperationDenied.ServiceNotOpen
确认模型服务已开通、API Key 有访问权限且账户余额正常。
404NotFound.Resource
InvalidEndpointOrModel.NotFound
ModelNotOpen
检查任务、模型或资源 ID,并确认查询任务时使用创建任务的同一 API Key。
429ServerOverloaded
RateLimitExceeded.*
QuotaExceeded
降低请求频率和并发;限流或过载时使用带随机抖动的指数退避。额度耗尽时应先补充额度,不要盲目重试。
5xxInternalServiceError对临时服务异常使用带随机抖动的指数退避;持续失败时记录错误信息并联系技术支持。

HTTP 请求成功但任务状态变为 failed 时,请读取任务响应中的 error.code 和 error.message;任务运行失败与同步 HTTP 错误应分别处理。

官方参考:完整错误码

使用建议

  • 素材库仅用于临时认证及视频任务前置环节,不应作为永久素材存储。
  • 客户端应永久保存原始素材 URL;上传获得 asset_id 后应尽快创建视频任务。
  • asset_id 受官方账号容量限制,可能因容量清理或替换而失效;超过一天的素材在使用前必须重新确认状态。
  • 使用前调用 GetAsset 确认状态为 Active;素材不存在或已失效时,使用原始 URL 重新上传并获取新的 asset_id。
  • 非人脸素材可直接使用公网原始 URL 时,无需写入素材库。
  • 素材上传受 QPS 限制;对限流或临时失败采用指数退避重试,并复用原 Idempotency-Key。
  • 素材资产组、素材资产和视频任务均与 API Key 绑定。后续查询和调用应使用同一个 API Key;使用 AK/SK 签名时,应使用该 API Key 下生成的凭证。
  • 素材状态变为 Active 后,使用 GetAsset 返回的 URL(asset://...)创建视频任务。
Last updated on