> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jiekou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Seedance

参数及使用方式已对齐官方，详细参数可直接参考官方文档。

## 一、概述

本文档整合了 Seedance 2.0 视频生成 API 及其配套的两种素材管理 API，为开发者提供一站式的协议参考。

三部分内容的关系如下：

* 视频生成 API：核心能力，使用官方模型名（doubao-seedance-2-0\* / dreamina-seedance-2-0\*，含 fast / mini 变体，doubao-seedance-2-5\* / dreamina-seedance-2-5\*）生成视频，按 token 用量计费。

* 虚拟人像素材 API：将图片、视频或音频创建为可被 Seedance 引用的素材，生成时使用 `asset://<Id>` 引用。

* 真人素材 API：用户完成 H5 真人验证后，将该真人的画像创建为可被 Seedance 引用的素材，同样使用 `asset://<Id>` 引用。

> \[!NOTE]
> 素材 API 创建的 asset 可被视频生成 API 引用，实现"先建素材 → 再生成视频"的完整流程。

## 二、视频生成 API

### 2.1 调用方式

创建任务：

```
POST https://{api_domain}/v3/bytedance/metered/contents/generations/tasks
```

查询任务：

```
GET https://{api_domain}/v3/bytedance/metered/contents/generations/tasks/{id}
```

取消或删除任务：

```
curl -X DELETE 'https://{api_domain}/v3/bytedance/metered/contents/generations/tasks/cgt-20260727130000-xxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <key>'
```

> \[!NOTE]
> DELETE 请求无需 body，{id} 使用创建任务返回的官方任务 id（cgt-\*）。

其中 {id} 为创建任务返回的官方任务 id（cgt-\*）。

SDK 兼容别名：以下路径与上述 metered 路由完全等价（模型名校验、计费行为一致）：

```
POST https://{api_domain}/v3/bytedance/api/v3/contents/generations/tasks
GET  https://{api_domain}/v3/bytedance/api/v3/contents/generations/tasks/{id}
```

> \[!NOTE]
> 该别名用于兼容以站点根为 base\_url、自行拼接 /api/v3/contents/generations/tasks 完整路径的官方 SDK：将 base\_url 设为 https\://{api_domain}/v3/bytedance 即可直接调用。

### 2.2 支持模型

| 模型（官方名称）                                                                    | 说明                 |
| --------------------------------------------------------------------------- | ------------------ |
| dreamina-seedance-2-0-`<version>`（如 dreamina-seedance-2-0-260128）           | 标准版                |
| dreamina-seedance-2-0-fast-`<version>`（如 dreamina-seedance-2-0-fast-260128） | 快速版                |
| dreamina-seedance-2-0-mini-`<version>`（如 dreamina-seedance-2-0-mini-260615） | 轻量版                |
| dreamina-seedance-2-5-`<version>`（如 dreamina-seedance-2-5-260628）           | 标准版                |
| dreamina-seedance-xx                                                        | doubao 系列官方名称会兼容转换 |

官方文档参考：[https://www.volcengine.com/docs/82379/1520757?lang=zh](https://www.volcengine.com/docs/82379/1520757?lang=zh)

官方模型列表：[https://docs.volcengine.com/docs/82379/1330310?lang=zh#7571da3f](https://docs.volcengine.com/docs/82379/1330310?lang=zh#7571da3f)

### 2.3 REST API 示例

#### 创建任务

```
curl -X POST 'https://{api_domain}/v3/bytedance/metered/contents/generations/tasks' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <key>' \
  -d @- << EOF
{
  "content": [
    {
      "text": "A cat walking through a sunny garden",
      "type": "text"
    }
  ],
  "duration": 5,
  "model": "doubao-seedance-2-0-260128",
  "resolution": "480p"
}
EOF
```

响应返回官方任务 id：

```
{"id": "cgt-20260727130000-xxxxx"}
```

#### 查询任务

```
curl -H 'Content-Type: application/json' -H 'Authorization: Bearer <key>' 'https://{api_domain}/v3/bytedance/metered/contents/generations/tasks/cgt-20260727130000-xxxxx'
```

成功响应（官方响应体原样返回，含 token 用量）：

```
{
  "id": "cgt-20260727130000-xxxxx",
  "model": "doubao-seedance-2-0-260128",
  "status": "succeeded",
  "content": {
    "video_url": "https://..."
  },
  "usage": {
    "completion_tokens": 108900,
    "total_tokens": 108900
  },
  "resolution": "480p",
  "duration": 5
}
```

#### 取消或删除任务

通过平台 API 取消排队中的视频生成任务，或删除视频生成任务记录。请求无需 body，鉴权方式与创建、查询任务一致。

```
curl -X DELETE 'https://{api_domain}/v3/bytedance/metered/contents/generations/tasks/cgt-20260727130000-xxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <key>'
```

| 调用时任务状态                  | DELETE 行为               | 后续查询               |
| ------------------------ | ----------------------- | ------------------ |
| queued                   | 取消排队，任务状态变更为 cancelled。 | 可查询到 cancelled 状态。 |
| running                  | 不支持取消                   | -                  |
| succeeded、expired、failed | 删除视频生成任务记录。             | 后续不支持查询该任务。        |

成功响应的 HTTP 状态码为 200，响应体为空对象 {}。任务 {id} 必须使用创建任务返回的官方任务 id（cgt-\*）。

> \[!NOTE]
> DELETE 请求成功返回 HTTP 200，响应体为空对象 {}。

### 2.4 SDK 示例

```
import os
import time
# Install SDK:  pip install 'volcengine-python-sdk[ark]'
from volcenginesdkarkruntime import Ark 

client = Ark(
    base_url='https://{api_domain}/v3/bytedance/metered',
    api_key=os.environ.get("YOUR_API_KEY"),
)

if __name__ == "__main__":
    print("----- create request -----")
    create_result = client.content_generation.tasks.create(
        model="doubao-seedance-2-0-fast-260128", 
        content=[
            {
                "type": "text",
                "text": "全程使用视频 1 的第一视角构图，全程使用音频 1 作为背景音乐。第一人称视角果茶宣传广告...",
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg"
                },
                "role": "reference_image",
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg"
                },
                "role": "reference_image",
            },
            {
                "type": "video_url",
                "video_url": {
                    "url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"
                },
                "role": "reference_video",
            },
            {
                "type": "audio_url",
                "audio_url": {
                    "url": "https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3"
                },
                "role": "reference_audio",
            },
        ],
        generate_audio=True,
        ratio="16:9",
        duration=11,
        watermark=True,
    )
    print(create_result)

    # Polling query section
    print("----- polling task status -----")
    task_id = create_result.id
    while True:
        get_result = client.content_generation.tasks.get(task_id=task_id)
        status = get_result.status
        if status == "succeeded":
            print("----- task succeeded -----")
            print(get_result)
            break
        elif status == "failed":
            print("----- task failed -----")
            print(f"Error: {get_result.error}")
            break
        else:
            print(f"Current status: {status}, Retrying after 30 seconds...")
            time.sleep(30)
```

> \[!NOTE]
> 上例中 Python Ark SDK 的 base\_url 需带 /metered 前缀。若所用 SDK 以站点根为 base\_url 并自行拼接 /api/v3/contents/generations/tasks 完整路径，则将 base\_url 设为 https\://{api_domain}/v3/bytedance（见 2.1 SDK 兼容别名）。

## 三、虚拟人像素材 API

### 3.1 适用范围

本接口用于将图片、视频或音频创建为 Seedance 可引用的虚拟人像素材。素材创建完成并返回 Active 后，使用 `asset://<Id>` 引用。

### 3.2 调用方式

统一入口：

```
POST https://{api_domain}/v3/synthetic/bytedance/ark?Action={Action}&Version=2024-01-01
Content-Type: application/json
```

### 3.3 鉴权

客户只需要传平台 API Key：Authorization: Bearer `<key>`

### 3.4 支持 Action

| Action      | 方法   | 说明                      |
| ----------- | ---- | ----------------------- |
| CreateAsset | POST | 创建虚拟人像素材，返回平台 asset id。 |
| GetAsset    | POST | 查询素材状态。                 |

### 3.5 通用响应结构

成功响应：

```
{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "CreateAsset",
    "Version": "2024-01-01"
  },
  "Result": {}
}
```

错误响应：

```
{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Error": {
      "Code": "InvalidParameter",
      "Message": "URL is required"
    }
  }
}
```

### 3.6 创建资产 (CreateAsset)

使用公网可下载的图片、视频或音频 URL 创建虚拟人像素材。CreateAsset 为异步处理，创建后建议调用 GetAsset 轮询状态。

#### Request

```
curl -X POST 'https://{api_domain}/v3/synthetic/bytedance/ark?Action=CreateAsset&Version=2024-01-01' \
  -H 'Authorization: Bearer <KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "URL": "https://your-cdn.example.com/assets/reference-image.png",
    "AssetType": "Image",
    "Name": "product_reference_image"
  }'
```

#### Request 字段

| 字段          | 类型     | 必填 | 说明                                                                             |
| ----------- | ------ | -- | ------------------------------------------------------------------------------ |
| URL         | string | 是  | 素材 URL，平台和上游服务必须能从公网下载。                                                        |
| GroupId     | string | 否  | 素材所属素材组 id（CreateAssetGroup 返回）；不传时自动归入账号默认组。传入不存在的组返回 404 NotFound.group\_id。 |
| AssetType   | string | 否  | 支持 Image、Video、Audio；不传时默认 Image。                                              |
| Name        | string | 否  | 客户侧素材名称，最长 64 个字符，用于区分、幂等匹配和 ListAssets 模糊搜索；不会被带入模型推理。                        |
| ProjectName | string | 否  | 可传但会被平台忽略，平台统一使用默认项目。                                                          |

#### 素材建议

| 类型 | 支持格式                                 | 规格要求                                                                                                                                        |
| -- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| 图片 | jpeg、png、webp、bmp、tiff、gif、heic、heif | 仅支持公网 URL，不支持 Base64；宽高比（宽/高）(0.4, 2.5)；宽、高均为 (300, 6000) px；单张小于 30 MB。                                                                    |
| 视频 | mp4、mov                              | 仅支持公网 URL；分辨率支持 480p、720p、1080p、4K；时长 \[2, 30] s；宽高比 \[0.4, 2.5]；宽、高均为 \[300, 6000] px；总像素数 \[409600, 2086876]；不超过 200 MB；帧率 \[24, 60] FPS。 |
| 音频 | wav、mp3                              | 仅支持公网 URL；时长 \[2, 30] s；不超过 15 MB。不同模型支持的输入音视频时长可能不同，建议上传前记录时长。                                                                             |

#### Response

```
{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20260701111803-yqveg"
  }
}
```

#### Response 字段

| 字段 | 说明                                                                                       |
| -- | ---------------------------------------------------------------------------------------- |
| Id | 平台 asset id，后续使用 `asset://<Id>` 引用。CreateAsset 仅返回 Id（素材为异步入库），状态、类型等字段通过 GetAsset 轮询获取。 |

#### 重复创建行为

同一账号下，CreateAsset 会在同一素材组 + 上游供应商绑定内按 GroupId + URL + AssetType + Name 精确幂等（同一 URL 传入不同素材组会创建两个素材）：

| 场景                                 | 行为                    |
| ---------------------------------- | --------------------- |
| 命中同一上游供应商，且 URL、AssetType、Name 均相同 | 返回已创建的同一个平台 asset id。 |
| URL、AssetType 或 Name 任一不同          | 按新的创建请求处理。            |

#### 常见错误

| HTTP | Code                | Message                                     | 说明                        |
| ---- | ------------------- | ------------------------------------------- | ------------------------- |
| 400  | InvalidParameter    | URL is required                             | 未传 URL。                   |
| 404  | InvalidAction       | Action is not supported for bytedance asset | Action 不在虚拟人像素材白名单内。      |
| 503  | NoProviderAvailable | no asset provider available                 | 当前没有可用素材供应商，请稍后重试或联系平台支持。 |

> \[!NOTE]
> 上游素材校验失败时，平台会透传上游错误。例如视频分辨率过低时，上游可能返回类似 InvalidParameter.HeightTooSmall 的错误。

### 3.7 查询资产状态 (GetAsset)

查询素材状态。建议创建后轮询到 Status=Active 再用于视频生成。GetAsset 返回平台资产视图；URL 为素材访问地址，通常有时效，请按需保存。

#### Request

```
POST https://{api_domain}/v3/synthetic/bytedance/ark?Action=GetAsset&Version=2024-01-01
Authorization: Bearer <KEY>
Content-Type: application/json

{ "Id": "asset-20260701111803-yqveg" }
```

#### Request 字段

| 字段          | 类型     | 必填 | 说明                          |
| ----------- | ------ | -- | --------------------------- |
| Id          | string | 是  | CreateAsset 返回的平台 asset id。 |
| ProjectName | string | 否  | 平台固定使用 default 项目；传入值会被忽略。  |

#### Response

```
{
  "ResponseMetadata": { "RequestId": "...", "Action": "GetAsset", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" },
  "Result": {
    "Id": "asset-20260701111803-yqveg",
    "Name": "demo-face",
    "URL": "https://example.com/portrait.png",
    "AssetType": "Image",
    "GroupId": "group-20260701111800-ab12c",
    "Status": "Active",
    "Moderation": { "Strategy": "Default" },
    "Error": { "Code": "", "Message": "" },
    "ProjectName": "default",
    "CreateTime": "2026-07-01T11:18:03+08:00",
    "UpdateTime": "2026-07-01T11:18:20+08:00",
    "LastInferenceTime": "2026-07-01T12:00:00+08:00"
  }
}
```

#### Response 字段

| 字段                                    | 说明                                                                                                                                                       |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Id / Name / URL / AssetType / GroupId | 平台素材标识、名称、访问地址、类型和所属组。                                                                                                                                   |
| Status                                | Processing 表示预处理中，Active 表示可用于 Seedance，Failed 表示处理失败。                                                                                                   |
| Moderation                            | 内容审核信息；当前 Strategy 固定为 Default。                                                                                                                          |
| Error                                 | 仅 Failed 状态承载失败原因；成功/处理中时 Code、Message 为空。常见 Code 包括 FaceMismatch、DownloadFailed、FormatUnsupported、DurationTooLong、FileSizeTooLarge、ContentRestricted 等。 |
| CreateTime / UpdateTime / ProjectName | 创建时间、更新时间和项目名；平台项目固定为 default。                                                                                                                           |
| LastInferenceTime                     | 最近一次提交视频生成任务的时间；未被调用时不返回。                                                                                                                                |

#### 失败状态示例

```
{
  "ResponseMetadata": { "...": "..." },
  "Result": {
    "Id": "asset-20260701111803-yqveg",
    "Name": "demo-face",
    "URL": "https://example.com/portrait.png",
    "AssetType": "Image",
    "GroupId": "group-20260701111800-ab12c",
    "Status": "Failed",
    "Error": { "Code": "DownloadFailed", "Message": "download asset from URL failed" },
    "ProjectName": "default"
  }
}
```

#### 常见错误

| HTTP | Code                     | 说明                     |
| ---- | ------------------------ | ---------------------- |
| 400  | MissingParameter.AssetID | 未传 Id。                 |
| 400  | InvalidParameter.AssetID | asset id 格式不正确。        |
| 404  | NotFound.asset\_id       | 素材不存在，或不属于当前账号。        |
| 409  | AssetUnavailable         | 素材绑定的上游命名空间不可用，需要重新创建。 |

### 3.8 素材组管理 (AssetGroup)

#### 创建素材组 (CreateAssetGroup)

```
curl -X POST 'https://{api_domain}/v3/synthetic/bytedance/ark?Action=CreateAssetGroup&Version=2024-01-01' \
  -H 'Authorization: Bearer <KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "Name": "product_group",
    "Description": "商品参考素材组"
  }'
```

| 字段          | 类型     | 必填 | 说明                          |
| ----------- | ------ | -- | --------------------------- |
| Name        | string | 是  | 素材组名称，上限 64 字符；缺失或超长返回 400。 |
| Description | string | 否  | 素材组描述，上限 300 字符。            |
| GroupType   | string | 否  | 仅支持 AIGC（默认）；传其他值返回 400。    |
| ProjectName | string | 否  | 可传但会被平台忽略，统一使用默认项目。         |

Response：

```
{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "group-20260701111700-ab12c"
  }
}
```

#### 查询素材组 (GetAssetGroup)

```
curl -X POST 'https://{api_domain}/v3/synthetic/bytedance/ark?Action=GetAssetGroup&Version=2024-01-01' \
  -H 'Authorization: Bearer <KEY>' \
  -H 'Content-Type: application/json' \
  -d '{ "Id": "group-20260701111700-ab12c" }'
```

Response：

```
{
  "ResponseMetadata": { "RequestId": "...", "Action": "GetAssetGroup", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" },
  "Result": {
    "Id": "group-20260701111700-ab12c",
    "Name": "product_group",
    "Description": "商品参考素材组",
    "GroupType": "AIGC",
    "ProjectName": "default",
    "CreateTime": "2026-07-01T11:17:00+08:00",
    "UpdateTime": "2026-07-01T11:17:00+08:00"
  }
}
```

#### 更新素材组 (UpdateAssetGroup)

仅支持更新 Name（上限 64 字符）与 Description（上限 300 字符），其余字段忽略。

```
curl -X POST 'https://{api_domain}/v3/synthetic/bytedance/ark?Action=UpdateAssetGroup&Version=2024-01-01' \
  -H 'Authorization: Bearer <KEY>' \
  -H 'Content-Type: application/json' \
  -d '{ "Id": "group-20260701111700-ab12c", "Name": "renamed_group" }'
```

Response 返回 Result.Id。

#### 查询素材组列表 (ListAssetGroups)

```
curl -X POST 'https://{api_domain}/v3/synthetic/bytedance/ark?Action=ListAssetGroups&Version=2024-01-01' \
  -H 'Authorization: Bearer <KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "Filter": { "Name": "product" },
    "PageNumber": 1,
    "PageSize": 10,
    "SortBy": "CreateTime",
    "SortOrder": "Desc"
  }'
```

| 字段               | 类型     | 必填 | 说明                                    |
| ---------------- | ------ | -- | ------------------------------------- |
| Filter.GroupIds  | array  | 否  | 按素材组 id 精确过滤。                         |
| Filter.GroupType | string | 否  | 仅支持 AIGC；传其他合法类型返回空列表，非法值返回 400。      |
| Filter.Name      | string | 否  | 按名称模糊搜索，上限 64 字符。                     |
| PageNumber       | int    | 否  | 从 1 开始，默认 1；传 0 或负数返回 400。            |
| PageSize         | int    | 否  | 默认 10，范围 \[1,100]；越界返回 400。           |
| SortBy           | string | 否  | CreateTime（默认）/ UpdateTime；其他值返回 400。 |
| SortOrder        | string | 否  | Desc（默认）/ Asc；其他值返回 400。              |

Response：Result 含 TotalCount、Items（条目字段同 GetAssetGroup，另含 Title，值与 Name 相同）、PageNumber、PageSize。

#### 删除素材组 (DeleteAssetGroup)

删除素材组会级联删除组内所有素材，操作不可逆；删除后组和素材立即不可查询、不可用于视频生成。默认组不可删除。

```
curl -X POST 'https://{api_domain}/v3/synthetic/bytedance/ark?Action=DeleteAssetGroup&Version=2024-01-01' \
  -H 'Authorization: Bearer <KEY>' \
  -H 'Content-Type: application/json' \
  -d '{ "Id": "group-20260701111700-ab12c" }'
```

Response：Result 为空对象 {}。

#### 素材组接口常见错误

| HTTP | Code                     | 说明                                                                |
| ---- | ------------------------ | ----------------------------------------------------------------- |
| 400  | InvalidParameter         | Name 缺失/超长、Description 超长、GroupType 非法、分页排序参数非法等。Message 会说明具体字段。 |
| 400  | MissingParameter.GroupID | 未传素材组 Id。                                                         |
| 400  | InvalidParameter.GroupID | 素材组 Id 格式不正确（平台组 id 均为 group- 前缀）。                                |
| 404  | NotFound.group\_id       | 素材组不存在，或不属于当前账号。                                                  |
| 400  | DefaultGroupUndeletable  | 默认组不可删除。                                                          |

### 3.9 素材列表与管理

#### 查询素材列表 (ListAssets)

```
curl -X POST 'https://{api_domain}/v3/synthetic/bytedance/ark?Action=ListAssets&Version=2024-01-01' \
  -H 'Authorization: Bearer <KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "Filter": {
      "GroupIds": ["group-20260701111700-ab12c"],
      "Statuses": ["Active"],
      "Name": "product"
    },
    "PageNumber": 1,
    "PageSize": 10
  }'
```

| 字段                    | 类型     | 必填 | 说明                                              |
| --------------------- | ------ | -- | ----------------------------------------------- |
| Filter.GroupIds       | array  | 否  | 按素材组 id 过滤。                                     |
| Filter.Statuses       | array  | 否  | 仅支持 Active / Processing / Failed；含非法值返回 400。    |
| Filter.Name           | string | 否  | 按素材名称模糊搜索，上限 64 字符。                             |
| PageNumber / PageSize | int    | 否  | 同 ListAssetGroups（严格校验，非法值 400）。                |
| SortBy                | string | 否  | CreateTime（默认）/ UpdateTime / GroupId；其他值返回 400。 |
| SortOrder             | string | 否  | Desc（默认）/ Asc。                                  |

Response：Result 含 TotalCount、Items（条目字段与 GetAsset 的 Result 完全一致）、PageNumber、PageSize。列表中的 Processing 状态可能滞后，以 GetAsset 轮询为准。

#### 更新素材 (UpdateAsset)

仅支持更新 Name（上限 64 字符），其余字段忽略。

```
curl -X POST 'https://{api_domain}/v3/synthetic/bytedance/ark?Action=UpdateAsset&Version=2024-01-01' \
  -H 'Authorization: Bearer <KEY>' \
  -H 'Content-Type: application/json' \
  -d '{ "Id": "asset-20260701111803-yqveg", "Name": "renamed_asset" }'
```

Response 返回 Result.Id。

#### 删除素材 (DeleteAsset)

删除后素材立即不可查询、不可用于视频生成，操作不可逆；删除后可用相同 URL 重新创建（视为新素材）。

```
curl -X POST 'https://{api_domain}/v3/synthetic/bytedance/ark?Action=DeleteAsset&Version=2024-01-01' \
  -H 'Authorization: Bearer <KEY>' \
  -H 'Content-Type: application/json' \
  -d '{ "Id": "asset-20260701111803-yqveg" }'
```

Response：Result 为空对象 {}。

#### 素材管理接口常见错误

| HTTP | Code                     | 说明                                 |
| ---- | ------------------------ | ---------------------------------- |
| 400  | MissingParameter.AssetID | 未传素材 Id。                           |
| 400  | InvalidParameter.AssetID | 素材 Id 格式不正确（平台素材 id 均为 asset- 前缀）。 |
| 404  | NotFound.asset\_id       | 素材不存在，或不属于当前账号。                    |
| 400  | InvalidParameter         | Name 超长、分页排序/过滤参数非法等。              |

### 3.10 Seedance 生成中引用虚拟人像素材

当 GetAsset 返回 Active 后，可在 Seedance 请求中使用。

#### 原厂协议支持字段

原厂协议请求中，content 内的图片、视频、音频 URL 也可使用 asset://：

```
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "Create a product video with a clean studio background."
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "asset://asset-20260701111803-yqveg"
      },
      "role": "reference_image"
    }
  ]
}
```

| 字段                        | 适用素材  |
| ------------------------- | ----- |
| content\[].image\_url.url | Image |
| content\[].video\_url.url | Video |
| content\[].audio\_url.url | Audio |

#### 生成侧常见错误

| HTTP | Code / reason          | Message / details                                                  | 说明                                     |
| ---- | ---------------------- | ------------------------------------------------------------------ | -------------------------------------- |
| 400  | INVALID\_REQUEST\_BODY | asset not found: `<asset_id>`                                      | asset 不存在，或不属于当前账号。                    |
| 400  | INVALID\_REQUEST\_BODY | asset not ready: `<asset_id>` (status=Processing)                  | asset 尚未 Active，需要继续轮询。                |
| 400  | INVALID\_REQUEST\_BODY | all assets in one request must belong to the same provider account | 同一请求中引用了不同供应商账号的 asset。                |
| 400  | INVALID\_REQUEST\_BODY | asset unavailable, please upload again: ...                        | asset 绑定的上游命名空间不可用，不会 fallback 到其他供应商。 |

### 3.11 排障清单

| 现象              | 优先检查                                                                |
| --------------- | ------------------------------------------------------------------- |
| InvalidAction   | 是否使用 /v3/synthetic/bytedance/ark，且 Action 为 CreateAsset 或 GetAsset。 |
| URL is required | CreateAsset 请求体是否传入 URL。                                            |
| 素材创建失败          | 素材 URL 是否公网可下载；格式、分辨率、时长是否满足上游要求；内容是否符合安全要求。                        |
| asset not found | API Key 是否属于创建该 asset 的同一账号；asset:// 后的 id 是否为 Result.Id。           |
| asset not ready | GetAsset 是否已经返回 Active。                                             |
| 多素材请求失败         | 同一个生成请求内是否混用了不同供应商账号创建的 asset。                                      |
| 带 asset 生成失败    | asset 是否属于当前账号且状态为 Active；若提示 asset unavailable，需要重新创建素材。           |

## 四、真人素材 API

### 4.1 适用范围

本接口用于用户完成 H5 真人验证后，将该同一真人的画像创建为 Seedance 可引用的真人素材。素材状态为 Active 后，使用 `asset://<Id>` 引用。

### 4.2 调用方式

统一入口：

```
POST https://{api_domain}/v3/bytedance/ark?Action={Action}&Version=2024-01-01
```

### 4.3 鉴权

客户只需要传平台 API Key：Authorization: Bearer `<key>`

### 4.4 支持 Action

| Action                      | 方法   | 说明                                   |
| --------------------------- | ---- | ------------------------------------ |
| CreateVisualValidateSession | POST | 创建 H5 真人验证会话，返回 H5Link 和 BytedToken。 |
| GetVisualValidateResult     | POST | 使用验证回调中的 BytedToken 换取真人素材组 GroupId。 |
| CreateAsset                 | POST | 在真人素材组下异步创建素材。                       |
| GetAsset                    | POST | 查询素材状态与详情。                           |
| ListAssets                  | POST | 按组、状态、名称查询真人素材列表，支持分页排序。             |
| UpdateAsset                 | POST | 更新素材名称（仅 Name）。                      |
| DeleteAsset                 | POST | 删除单个素材。                              |
| GetAssetGroup               | POST | 查询真人素材组信息。                           |
| UpdateAssetGroup            | POST | 更新素材组名称和描述（仅 Name/Description）。      |
| ListAssetGroups             | POST | 查询真人素材组列表，支持分页排序。                    |
| DeleteAssetGroup            | POST | 删除素材组并级联删除组内素材。                      |

### 4.5 通用响应结构

平台自实现的管理接口和上游透传接口统一使用 Ark 响应信封。平台管理接口固定返回 Service=ark、Region=cn-beijing；失败资产仍以 HTTP 200 返回时，应以 Result.Status=Failed 和 Result.Error 判断处理结果。

成功响应：

```
{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {}
}
```

错误响应：

```
{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing",
    "Error": {
      "Code": "InvalidParameter",
      "Message": "GroupId is required"
    }
  }
}
```

### 4.6 创建 H5 真人验证会话 (CreateVisualValidateSession)

创建一次性 H5 真人验证会话。平台会保存会话绑定的 provider/account，BytedToken 有效期按官方为 30 分钟，且仅支持认证一次；建议在用户完成 H5 后立即调用 GetVisualValidateResult。

#### Request

```
POST https://{api_domain}/v3/bytedance/ark?Action=CreateVisualValidateSession&Version=2024-01-01
Authorization: Bearer <KEY>
Content-Type: application/json

{ "CallbackURL": "https://your-app.example.com/liveness/done" }
```

#### Request 字段

| 字段          | 类型     | 必填 | 说明                         |
| ----------- | ------ | -- | -------------------------- |
| CallbackURL | string | 是  | 用户完成 H5 真人验证后跳转的客户侧公网 URL。 |
| ProjectName | string | 否  | 平台固定使用 default 项目；传入值会被忽略。 |

#### Response

```
{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "CreateVisualValidateSession",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "BytedToken": "xxx",
    "H5Link": "https://example.com/liveness?token=...",
    "CallbackURL": "https://your-app.example.com/liveness/done"
  }
}
```

#### Response 字段

| 字段          | 说明                                                                                                                      |
| ----------- | ----------------------------------------------------------------------------------------------------------------------- |
| BytedToken  | 真人认证唯一凭证，后续调用 GetVisualValidateResult 时传入；有效期 30 分钟，仅可认证一次。                                                             |
| H5Link      | 客户前端打开的 H5 地址，使用后失效；可在链接后缀增加 lng=zh、en 或 zh-Hant 指定语言。                                                                  |
| CallbackURL | 认证结束后的跳转地址。回调通常附带 bytedToken、resultCode、algorithmBaseRespCode、reqMeasureInfoValue、verify\_type；resultCode=10000 表示认证成功。 |

> \[!NOTE]
> 客户侧可以先解析 CallbackURL 判断 resultCode，但能否创建素材应以 GetVisualValidateResult 成功返回 GroupId 为最终依据。

### 4.7 获取验证结果 (GetVisualValidateResult)

仅在 CallbackURL 的 resultCode=10000 后，使用 BytedToken 查询真人验证结果，获取后续创建素材需要的 GroupId。BytedToken 有效期 30 分钟且仅可使用一次。

#### Request

```
curl -X POST 'https://{api_domain}/v3/bytedance/ark?Action=GetVisualValidateResult&Version=2024-01-01' \
  -H 'Authorization: Bearer <KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "BytedToken": "xxx"
  }'
```

#### Request 字段

| 字段         | 类型     | 必填 | 说明                                                       |
| ---------- | ------ | -- | -------------------------------------------------------- |
| BytedToken | string | 是  | CreateVisualValidateSession 返回的 token；有效期 30 分钟，仅支持认证一次。 |

#### Response

```
{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "GetVisualValidateResult",
    "Version": "2024-01-01"
  },
  "Result": {
    "GroupId": "group-xxx-xxx"
  }
}
```

#### Response 字段

| 字段      | 说明                       |
| ------- | ------------------------ |
| GroupId | 真人验证 group id，创建真人素材时传入。 |

#### 常见错误

| HTTP | Code             | Message                                     | 说明                          |
| ---- | ---------------- | ------------------------------------------- | --------------------------- |
| 400  | InvalidParameter | BytedToken is required                      | 未传 BytedToken。              |
| 404  | SessionNotFound  | liveness session not found                  | token 不存在或不属于当前账号。          |
| 410  | SessionExpired   | liveness session expired                    | token 已过期，需要重新创建 H5 真人验证会话。 |
| 409  | AssetUnavailable | asset unavailable, please upload again: ... | 当前素材会话不可用，需要重新发起认证。         |

### 4.8 创建资产 (CreateAsset)

使用真人素材组 GroupId 和公网可下载的素材 URL 创建资产。CreateAsset 为异步处理，创建后只返回平台 asset id；请调用 GetAsset 轮询到 Status=Active 后再用于视频生成。上传图像时系统会校验与真人认证基准人像的一致性。

#### Request

```
POST https://{api_domain}/v3/bytedance/ark?Action=CreateAsset&Version=2024-01-01
Authorization: Bearer <KEY>
Content-Type: application/json

{
  "GroupId": "group-xxx-xxx",
  "URL": "https://your-cdn.example.com/portraits/user123.jpg",
  "AssetType": "Image",
  "Name": "user_123_portrait"
}
```

#### Request 字段

| 字段          | 类型     | 必填 | 说明                                      |
| ----------- | ------ | -- | --------------------------------------- |
| GroupId     | string | 是  | GetVisualValidateResult 返回的真人素材组 id。    |
| URL         | string | 是  | 素材公网 URL，平台和上游必须能下载。                    |
| AssetType   | string | 否  | 支持 Image、Video、Audio；不传时默认 Image。       |
| Name        | string | 否  | 素材名称，最长 64 个字符，用于 ListAssets 模糊搜索和幂等匹配。 |
| ProjectName | string | 否  | 平台固定使用 default 项目；传入值会被忽略。              |

#### 素材建议

| 类型 | 规格要求                                                                                                             |
| -- | ---------------------------------------------------------------------------------------------------------------- |
| 图片 | jpeg、png、webp、bmp、tiff、gif、heic、heif；宽高比 (0.4, 2.5)；宽、高均为 (300, 6000) px；单张小于 30 MB。图像应为完成真人验证的同一真人。             |
| 视频 | mp4、mov；时长 \[2, 30] s；宽高比 \[0.4, 2.5]；宽、高均为 \[300, 6000] px；总像素数 \[409600, 2086876]；不超过 200 MB；帧率 \[24, 60] FPS。 |
| 音频 | wav、mp3；时长 \[2, 30] s；不超过 15 MB。不同模型支持的输入音视频时长可能不同。                                                              |

仅支持 URL，不支持 Base64。CreateAsset 命中同一账号、素材组、URL、AssetType、Name 时返回同一个平台 asset id；任一关键字段变化则按新请求处理，并继续进行真人一致性校验。

#### Response

```
{
  "ResponseMetadata": { "RequestId": "...", "Action": "CreateAsset", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" },
  "Result": { "Id": "asset-xxx-xxx" }
}
```

#### Response 字段

| 字段 | 说明                                                           |
| -- | ------------------------------------------------------------ |
| Id | 平台 asset id，后续使用 `asset://<Id>` 引用；状态、类型等字段通过 GetAsset 轮询获取。 |

### 4.9 查询资产状态 (GetAsset)

查询真人素材状态。建议创建后轮询到 Status=Active 再用于视频生成。失败素材可能仍返回 HTTP 200，必须以 Status=Failed 和 Error.Code/Error.Message 判断失败原因。

#### Request

```
POST https://{api_domain}/v3/bytedance/ark?Action=GetAsset&Version=2024-01-01
Authorization: Bearer <KEY>
Content-Type: application/json

{ "Id": "asset-xxx-yqveg" }
```

#### Request 字段

| 字段          | 类型     | 必填 | 说明                          |
| ----------- | ------ | -- | --------------------------- |
| Id          | string | 是  | CreateAsset 返回的平台 asset id。 |
| ProjectName | string | 否  | 平台固定使用 default 项目；传入值会被忽略。  |

#### Response

```
{
  "ResponseMetadata": { "RequestId": "...", "Action": "GetAsset", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" },
  "Result": {
    "Id": "asset-xxx-yqveg",
    "Name": "user_123_portrait",
    "URL": "https://example.com/portrait.jpg",
    "AssetType": "Image",
    "GroupId": "group-xxx-xxx",
    "Status": "Active",
    "Moderation": { "Strategy": "Default" },
    "Error": { "Code": "", "Message": "" },
    "ProjectName": "default",
    "CreateTime": "2026-07-01T11:18:03+08:00",
    "UpdateTime": "2026-07-01T11:18:20+08:00",
    "LastInferenceTime": "2026-07-01T12:00:00+08:00"
  }
}
```

#### Response 字段

| 字段                                    | 说明                                                                                                                                                       |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Id / Name / URL / AssetType / GroupId | 平台素材标识、名称、访问地址、类型和所属组。                                                                                                                                   |
| Status                                | Processing 表示处理中，Active 表示可用于 Seedance，Failed 表示处理失败。                                                                                                    |
| Moderation                            | 内容审核信息；当前 Strategy 固定为 Default。                                                                                                                          |
| Error                                 | 仅 Failed 状态承载失败原因；成功/处理中时 Code、Message 为空。常见 Code 包括 FaceMismatch、DownloadFailed、FormatUnsupported、DurationTooLong、FileSizeTooLarge、ContentRestricted 等。 |
| CreateTime / UpdateTime / ProjectName | 创建时间、更新时间和项目名；平台项目固定为 default。                                                                                                                           |
| LastInferenceTime                     | 最近一次提交视频生成任务的时间；未被调用时不返回。                                                                                                                                |

#### 失败状态示例

```
{
  "ResponseMetadata": { "...": "..." },
  "Result": {
    "Id": "asset-xxx-xxx",
    "Name": "user_123_portrait",
    "URL": "https://example.com/portrait.jpg",
    "AssetType": "Image",
    "GroupId": "group-xxx-xxx",
    "Status": "Failed",
    "Error": { "Code": "FaceMismatch", "Message": "face verification failed" },
    "ProjectName": "default"
  }
}
```

#### 常见错误

| HTTP | Code                     | 说明              |
| ---- | ------------------------ | --------------- |
| 400  | MissingParameter.AssetID | 未传 Id。          |
| 400  | InvalidParameter.AssetID | asset id 格式不正确。 |
| 404  | NotFound.asset\_id       | 素材不存在，或不属于当前账号。 |
| 409  | AssetUnavailable         | 素材当前不可用，需要重新创建。 |

### 4.10 真人素材组管理 (AssetGroup)

真人素材组由 GetVisualValidateResult 创建，平台侧不提供 CreateAssetGroup。组类型固定为 LivenessFace；同一素材组对应同一真人。管理接口只作用于当前 API Key/账号可见的素材组。

#### 查询素材组 (GetAssetGroup)

```
POST https://{api_domain}/v3/bytedance/ark?Action=GetAssetGroup&Version=2024-01-01

{ "Id": "group-xxx-xxx" }
```

必填 Id；返回 Id、Name、Description、GroupType=LivenessFace、ProjectName、CreateTime 和 UpdateTime。

#### 更新素材组 (UpdateAssetGroup)

必填 Id，仅支持更新 Name（最长 64 个字符）和 Description（最长 300 个字符），其他字段忽略；返回 Result.Id。

#### 查询素材组列表 (ListAssetGroups)

```
{
  "Filter": {
    "GroupIds": ["group-xxx-xxx"],
    "GroupType": "LivenessFace",
    "Name": "user"
  },
  "PageNumber": 1,
  "PageSize": 10,
  "SortBy": "CreateTime",
  "SortOrder": "Desc"
}
```

Filter.GroupIds、Filter.GroupType 和 Filter.Name 均可选；GroupType 只能为 AIGC 或 LivenessFace，传其他合法类型返回空列表，非法值返回 400。PageNumber 从 1 开始，PageSize 范围 \[1,100]，SortBy 支持 CreateTime/UpdateTime，SortOrder 支持 Desc/Asc。

Response.Result 含 TotalCount、Items、PageNumber、PageSize；Items 字段同 GetAssetGroup，并包含 Title（值与 Name 相同）。

#### 删除素材组 (DeleteAssetGroup)

必填 Id。删除会级联删除组内所有素材，操作不可恢复；

#### 素材组管理错误

| HTTP | Code                                                | 说明                                          |
| ---- | --------------------------------------------------- | ------------------------------------------- |
| 400  | MissingParameter.GroupID / InvalidParameter.GroupID | 未传组 Id 或组 Id 格式不正确。                         |
| 404  | NotFound.group\_id                                  | 素材组不存在，或不属于当前账号。                            |
| 400  | InvalidParameter                                    | Name/Description 超长、GroupType 非法、分页排序参数非法等。 |

### 4.11 真人素材列表与管理

#### 查询素材列表 (ListAssets)

```
{
  "Filter": {
    "GroupIds": ["group-xxx-xxx"],
    "GroupType": "LivenessFace",
    "Statuses": ["Active"],
    "Name": "portrait"
  },
  "PageNumber": 1,
  "PageSize": 10,
  "SortBy": "CreateTime",
  "SortOrder": "Desc"
}
```

#### 更新素材 (UpdateAsset)

必填 Id，仅支持更新 Name（最长 64 个字符），其他字段忽略；返回 Result.Id。

#### 删除素材 (DeleteAsset)

必填 Id。删除后素材立即不可查询，也不可用于视频生成；操作不可恢复。成功响应的 Result 为空对象。

#### 素材管理错误

| HTTP | Code                                                | 说明                     |
| ---- | --------------------------------------------------- | ---------------------- |
| 400  | MissingParameter.AssetID / InvalidParameter.AssetID | 未传素材 Id 或素材 Id 格式不正确。  |
| 404  | NotFound.asset\_id                                  | 素材不存在，或不属于当前账号。        |
| 400  | InvalidParameter                                    | Name 超长、分页/排序/过滤参数非法等。 |

### 4.12 Seedance 生成中引用真人素材

当 GetAsset 返回 Active 后，可以在 Seedance 请求中使用：

```
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "使用 @image1 中的真人资产生成一段视频。人物面向镜头自然微笑，保持人物身份、发型和服装一致。"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "asset://asset-xxx-xxx"
      },
      "role": "reference_image"
    }
  ]
}
```

平台会校验 asset 属于当前账号，且素材状态为 Active。

### 4.13 完整流程示例

```
export ASSET_ENDPOINT="https://{api_domain}/v3/bytedance/ark"
export PLATFORM_API_KEY="<KEY>"
export CALLBACK_URL="https://your-app.example.com/liveness/done"

# Step 1: create liveness session
curl -sS -X POST "${ASSET_ENDPOINT}?Action=CreateVisualValidateSession&Version=2024-01-01" \
  -H "Authorization: Bearer ${PLATFORM_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{
    \"CallbackURL\": \"${CALLBACK_URL}\"
  }"

# Step 2: open Result.H5Link in browser and finish liveness within 120 seconds.

# Step 3: exchange token for GroupId
curl -sS -X POST "${ASSET_ENDPOINT}?Action=GetVisualValidateResult&Version=2024-01-01" \
  -H "Authorization: Bearer ${PLATFORM_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "BytedToken": "<BYTED_TOKEN>"
  }'

# Step 4: create asset
curl -sS -X POST "${ASSET_ENDPOINT}?Action=CreateAsset&Version=2024-01-01" \
  -H "Authorization: Bearer ${PLATFORM_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId": "<GROUP_ID>",
    "URL": "https://your-cdn.example.com/portraits/user123.jpg",
    "AssetType": "Image",
    "Name": "user_123_portrait"
  }'

# Step 5: poll asset status
curl -sS -X POST "${ASSET_ENDPOINT}?Action=GetAsset&Version=2024-01-01" \
  -H "Authorization: Bearer ${PLATFORM_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "Id": "<ASSET_ID>"
  }'
```

### 4.14 排障清单

| 现象                 | 优先检查                                                                  |
| ------------------ | --------------------------------------------------------------------- |
| SessionExpired     | 用户是否在 30 分钟内完成 H5 真人验证并调用 GetVisualValidateResult；BytedToken 仅支持认证一次。 |
| SessionNotFound    | API Key 是否属于同一账号；BytedToken 是否复制正确。                                   |
| AssetGroupNotFound | GroupId 是否来自当前 API Key 的 GetVisualValidateResult 响应。                  |
| 图片上传失败             | 图片 URL 是否公网可下载；图片内容是否为完成真人验证的同一真人。                                    |
| asset not ready    | GetAsset 是否已经返回 Active。                                               |
| 带 asset 生成失败       | asset 是否属于当前账号，且状态是否为 Active。                                         |

## 五、素材引用总览

本章统一说明虚拟人像素材和真人素材如何在 Seedance 视频生成中使用 asset:// 引用，以及两种素材 API 在生成侧的共用信息。

### 5.1 素材引用方式

无论是虚拟人像素材还是真人素材，创建成功并返回 Active 后，均使用 `asset://<Id>` 在 Seedance 生成请求中引用。其中 `<Id>` 为 CreateAsset 返回的 Result.Id。

> \[!NOTE]
> 引用前必须确认 GetAsset 返回 Status=Active，否则生成请求会报 asset not ready 错误。

### 5.2 两种素材 API 对比

| 维度               | 虚拟人像素材 API                  | 真人素材 API                                            |
| ---------------- | --------------------------- | --------------------------------------------------- |
| 调用入口             | /v3/synthetic/bytedance/ark | /v3/bytedance/ark                                   |
| 前置条件             | 无，直接 CreateAsset            | 需先完成 H5 真人验证，获取 GroupId                             |
| 支持素材类型           | Image、Video、Audio           | 仅 Image                                             |
| CreateAsset 幂等维度 | URL + AssetType + Name      | GroupId + URL + AssetType + Name                    |
| CreateAsset 额外字段 | ProjectName（可选，忽略）          | GroupId（必填）                                         |
| 独有 Action        | 无                           | CreateVisualValidateSession、GetVisualValidateResult |
| 引用方式             | `asset://<Id>`              | `asset://<Id>`                                      |

### 5.3 GetAsset 通用说明

两种素材 API 均提供 GetAsset 接口，调用方式和响应结构一致：

* 请求字段：Id（必填，CreateAsset 返回的平台 asset id）

* 响应包含：Id、AssetType、Name、Status，失败时额外返回 ErrorMessage

通用 Status 值：

| Status     | 说明                          |
| ---------- | --------------------------- |
| Processing | 处理中，继续轮询。                   |
| Active     | 素材可用于 Seedance 视频生成。        |
| Failed     | 素材创建失败，响应可能包含 ErrorMessage。 |

通用错误：

| HTTP | Code             | Message                                     | 说明                 |
| ---- | ---------------- | ------------------------------------------- | ------------------ |
| 400  | InvalidParameter | Id is required                              | 未传 Id。             |
| 404  | AssetNotFound    | asset not found                             | asset 不存在或不属于当前账号。 |
| 409  | AssetUnavailable | asset unavailable, please upload again: ... | 当前素材不可用，需要重新创建。    |

### 5.4 Seedance 生成中引用素材的通用规则

#### 原厂协议支持字段

在原厂协议请求中，content 内的图片、视频、音频 URL 字段均支持 asset:// 引用：

| 字段                        | 适用素材类型 |
| ------------------------- | ------ |
| content\[].image\_url.url | Image  |
| content\[].video\_url.url | Video  |
| content\[].audio\_url.url | Audio  |

#### 生成侧通用错误

无论引用虚拟人像素材还是真人素材，生成请求侧的常见错误一致：

| HTTP | Code / reason          | Message / details                                                  | 说明                                     |
| ---- | ---------------------- | ------------------------------------------------------------------ | -------------------------------------- |
| 400  | INVALID\_REQUEST\_BODY | asset not found: `<asset_id>`                                      | asset 不存在，或不属于当前账号。                    |
| 400  | INVALID\_REQUEST\_BODY | asset not ready: `<asset_id>` (status=Processing)                  | asset 尚未 Active，需要继续轮询。                |
| 400  | INVALID\_REQUEST\_BODY | all assets in one request must belong to the same provider account | 同一请求中引用了不同供应商账号的 asset。                |
| 400  | INVALID\_REQUEST\_BODY | asset unavailable, please upload again: ...                        | asset 绑定的上游命名空间不可用，不会 fallback 到其他供应商。 |

### 5.5 完整流程对比

#### 虚拟人像素材流程

1. CreateAsset（传入 URL、AssetType、Name）

2. GetAsset 轮询至 Status=Active

3. 在 Seedance 生成请求中使用 `asset://<Id>` 引用

#### 真人素材流程

1. CreateVisualValidateSession（传入 CallbackURL）→ 获取 H5Link 和 BytedToken

2. 用户在 H5 页面完成真人验证（120 秒内）

3. GetVisualValidateResult（传入 BytedToken）→ 获取 GroupId

4. CreateAsset（传入 GroupId、URL、AssetType、Name）

5. GetAsset 轮询至 Status=Active

6. 在 Seedance 生成请求中使用 `asset://<Id>` 引用

### 5.6 统一排障清单

| 现象                   | 优先检查                                                      |
| -------------------- | --------------------------------------------------------- |
| asset not found      | API Key 是否属于创建该 asset 的同一账号；asset:// 后的 id 是否为 Result.Id。 |
| asset not ready      | GetAsset 是否已经返回 Active。                                   |
| 多素材请求失败              | 同一个生成请求内是否混用了不同供应商账号创建的 asset。                            |
| asset unavailable    | asset 绑定的上游命名空间不可用，需要重新创建素材。                              |
| SessionExpired（真人素材） | 用户是否在 120 秒内完成 H5 真人验证并调用 GetVisualValidateResult。        |
| 素材创建失败               | 素材 URL 是否公网可下载；格式、分辨率、时长是否满足上游要求；内容是否符合安全要求。              |