Seedance
火山方舟 Ark 协议
创建视频生成任务
POST /ark/api/v3/contents/generations/tasks
请求参数
| 参数 | 类型 | 说明 |
|---|---|---|
model | string | 模型名,见上方模型列表。 |
content | array | 多模态输入数组,至少包含一个输入项;type、内容字段和 role 见下表。 |
generate_audio | boolean | 是否生成音频,默认 true,以模型实际能力为准。 |
ratio | string | 16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9 / adaptive。Seedance 2.5 的首帧、首尾帧、视频编辑和视频延长任务不得指定具体比例,见下方任务类型限制。 |
duration | integer | 视频时长,单位秒;取值范围和默认值因模型与任务类型而异,见下表。 |
resolution | string | 480p / 720p / 1080p,以模型实际能力为准。开启样片模式时只能使用 480p。 |
draft | boolean | Seedance 2.5 样片模式开关,默认 false;设为 true 时生成 480p 预览视频。 |
omni_reference_task_type | string | 仅适用于 Seedance 2.5 全模态参考生视频任务;可选值为 auto / reference / edit / extend,默认 auto。 |
output_format | string | 仅适用于 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 遵循通用限制。 |
| 视频编辑 | edit | content 至少包含一个 4 至 30 秒的 reference_video;ratio 必须为 adaptive,duration 必须为 -1。 |
| 视频延长 | extend | content 至少包含一个 reference_video;ratio 必须为 adaptive。 |
ratio(默认 adaptive)或传入 adaptive,不得传入具体比例。输出视频比例跟随 first_frame;传入 16:9 等具体比例会返回 InvalidParameter.TaskTypeConstraint。显式指定任务类型后,提示词意图仍须与该类型一致,否则任务创建后可能以 InvalidParameter.TaskTypeMismatch 失败。
content 输入项
| 用途 | type | 内容字段 | role |
|---|---|---|---|
| 提示词 | text | text | 不需要 |
| 首帧图片 | image_url | image_url.url | first_frame |
| 尾帧图片 | image_url | image_url.url | last_frame |
| 参考图片 | image_url | image_url.url | reference_image |
| 参考视频 | video_url | video_url.url | reference_video |
| 参考音频 | audio_url | audio_url.url | reference_audio |
| 样片任务 | draft_task | draft_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_id | string | 是 | 创建任务时返回的任务 ID。 |
| HTTP 状态码 | 错误码 | 说明 |
|---|---|---|
204 | - | 删除成功,无响应体。 |
409 | InvalidAction.RunningTaskDeletion | 当前任务状态不支持删除。 |
404 | ResourceNotFound | 任务不存在或已删除。 |
仅支持删除状态为 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 | 删除指定素材组及组内素材。 |
| 拉起真人人像认证 H5 | CreateVisualValidateSession | 创建真人人像认证会话。 |
| 获取真人人像 Asset Group ID | GetVisualValidateResult | 查询真人人像认证结果。 |
- 素材和可选素材组接口使用以下 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 Scope | YYYYMMDD/cn-beijing/ark/request |
| Signed Headers | content-type;host;x-content-sha256;x-date |
X-Date | UTC 时间,格式为 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
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
URL | string | 是 | - | 服务端可访问的公网 HTTP 或 HTTPS 素材地址,最多 8192 字节。 |
GroupId | string | 是 | - | 素材组 ID。 |
Name | string | 否 | reference | 素材名称,最多 64 个字符。 |
AssetType | string | 否 | Image | Image / 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
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
Id | string | 是 | 素材 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.GroupIds | array | 否 | - | 素材组 ID 列表,最多 100 项;省略时查询当前 API Key 下的全部素材。 |
Filter.GroupType | string | 否 | - | 素材组类型,可选 AIGC 或 LivenessFace。 |
Filter.Statuses | array | 否 | - | Processing / Active / Failed |
Filter.Name | string | 否 | - | 按素材名称关键字筛选。 |
PageNumber | integer | 否 | 1 | 页码,大于等于 1。 |
PageSize | integer | 否 | 10 | 每页数量,1 至 100。 |
SortBy | string | 否 | CreateTime | CreateTime / UpdateTime / GroupId |
SortOrder | string | 否 | Desc | Asc / 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
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
Id | string | 是 | 素材 ID。 |
Name | string | 是 | 新的素材名称,最多 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
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
Id | string | 是 | 待删除的素材 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
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
Name | string | 是 | - | 素材组名称,最多 64 个字符。 |
Description | string | 否 | - | 素材组描述,最多 300 个字符。 |
GroupType | string | 否 | 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
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
Id | string | 是 | 素材组 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.GroupIds | array | 否 | - | 素材组 ID 列表,最多 100 项。 |
Filter.Name | string | 否 | - | 按素材组名称关键字筛选。 |
Filter.GroupType | string | 否 | - | 素材组类型,可选 AIGC 或 LivenessFace。 |
PageNumber | integer | 否 | 1 | 页码,大于等于 1。 |
PageSize | integer | 否 | 10 | 每页数量,1 至 100。 |
SortBy | string | 否 | CreateTime | CreateTime / UpdateTime |
SortOrder | string | 否 | Desc | Asc / 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
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
Id | string | 是 | 素材组 ID。 |
Name | string | 否 | 新的素材组名称,最多 64 个字符。 |
Description | string | 否 | 新的素材组描述,最多 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
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
Id | string | 是 | 待删除的素材组 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
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
CallbackURL | string | 是 | - | 公网可访问的 HTTPS 回调地址。 |
ProjectName | string | 否 | 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
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
BytedToken | string | 是 | - | 创建真人人像认证会话返回的认证令牌。 |
ProjectName | string | 否 | 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 | 处理建议 |
|---|---|---|
400 | InvalidParameterMissingParameter各类 SensitiveContentDetected | 检查必填参数、模型支持范围和素材格式;命中内容安全检查时更换输入。不要使用相同请求直接重试。 |
401 | AuthenticationError | 检查 Bearer API Key 是否缺失、错误或已失效;使用 AK/SK 签名时,检查 Access Key、签名和请求时间。 |
403 | AccessDeniedAccountOverdueErrorOperationDenied.ServiceNotOpen | 确认模型服务已开通、API Key 有访问权限且账户余额正常。 |
404 | NotFound.ResourceInvalidEndpointOrModel.NotFoundModelNotOpen | 检查任务、模型或资源 ID,并确认查询任务时使用创建任务的同一 API Key。 |
429 | ServerOverloadedRateLimitExceeded.*QuotaExceeded | 降低请求频率和并发;限流或过载时使用带随机抖动的指数退避。额度耗尽时应先补充额度,不要盲目重试。 |
5xx | InternalServiceError | 对临时服务异常使用带随机抖动的指数退避;持续失败时记录错误信息并联系技术支持。 |
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://...)创建视频任务。