> ## 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 2.0 原厂协议

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

三部分内容的关系如下：

* **视频生成 API**：核心能力，通过 Seedance 2.0 / Seedance 2.0-fast 模型生成视频。
* **虚拟人像素材 API**：将图片、视频或音频创建为可被 Seedance 引用的素材，生成时使用 `asset://<Id>` 引用。
* **真人素材 API**：用户完成 H5 真人验证后，将该真人的画像创建为可被 Seedance 引用的素材，同样使用 `asset://<Id>` 引用。

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

***

## 一、视频生成 API

### 1.1 调用方式

**创建任务：**

```
POST https://api.highwayapi.ai/v3/bytedance/contents/generations/tasks
```

**查询任务：**

```
GET https://api.highwayapi.ai/v3/bytedance/contents/generations/tasks/{id}
```

### 1.2 支持模型

| 模型                | 说明  |
| ----------------- | --- |
| seedance-2.0      | 标准版 |
| seedance-2.0-fast | 快速版 |

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

### 1.3 请求头

<ParamField header="Content-Type" type="string" required={true}>
  枚举值: `application/json`
</ParamField>

<ParamField header="Authorization" type="string" required={true}>
  Bearer 身份验证格式: Bearer \{\{API 密钥}}。
</ParamField>

### 1.4 请求体

<ParamField body="model" type="string" required={true}>
  模型名称。可选值：`seedance-2.0`、`seedance-2.0-fast`
</ParamField>

<ParamField body="content" type="array" required={true}>
  多模态内容数组，支持文本、图片、视频、音频等类型。每项包含 `type` 字段和对应内容。

  支持的类型：

  * `text`：文本提示词，包含 `text` 字段
  * `image_url`：图片输入，包含 `image_url.url` 字段，可选 `role` 字段（如 `reference_image`）
  * `video_url`：视频输入，包含 `video_url.url` 字段，可选 `role` 字段（如 `reference_video`）
  * `audio_url`：音频输入，包含 `audio_url.url` 字段，可选 `role` 字段（如 `reference_audio`）

  URL 字段也支持 `asset://<Id>` 格式引用已创建的素材。
</ParamField>

<ParamField body="duration" type="integer" default={5}>
  生成视频时长（秒）。范围 \[4, 15]
</ParamField>

<ParamField body="resolution" type="string" default="720p">
  视频分辨率。1080p 仅支持标准版。

  可选值：`480p`, `720p`, `1080p`
</ParamField>

<ParamField body="ratio" type="string" default="adaptive">
  生成视频的宽高比。

  可选值：`16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`, `adaptive`
</ParamField>

<ParamField body="generate_audio" type="boolean" default={true}>
  是否生成与画面同步的声音。true 时模型基于文本与视觉内容自动生成匹配的人声、音效及背景音乐。
</ParamField>

<ParamField body="watermark" type="boolean" default={false}>
  生成视频是否包含水印。
</ParamField>

### 1.5 REST API 示例

**创建任务：**

```bash theme={null}
curl -X POST 'https://api.highwayapi.ai/v3/bytedance/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": "seedance-2.0",
  "resolution": "480p"
}
EOF
```

**查询任务：**

```bash theme={null}
curl -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <key>' \
  'https://api.highwayapi.ai/v3/bytedance/contents/generations/tasks/975de73b-85ff-47f1-b199-737b72fe92da'
```

### 1.6 SDK 示例

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

client = Ark(
    base_url='https://api.highwayapi.ai/v3/bytedance',
    api_key=os.environ.get("YOUR_API_KEY"),
)

if __name__ == "__main__":
    print("----- create request -----")
    create_result = client.content_generation.tasks.create(
        model="seedance-2.0-fast",
        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)
```

***

## 二、虚拟人像素材 API

### 2.1 适用范围

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

### 2.2 调用方式

统一入口：

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

### 2.3 鉴权

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

### 2.4 支持 Action

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

### 2.5 通用响应结构

**成功响应：**

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

**错误响应：**

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

### 2.6 创建资产 (CreateAsset)

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

**Request：**

```bash theme={null}
curl -X POST 'https://api.highwayapi.ai/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，平台和上游服务必须能从公网下载。           |
| AssetType   | string | 否  | 支持 Image、Video、Audio；不传时默认 Image。 |
| Name        | string | 否  | 客户侧素材名称，用于区分和幂等匹配。                |
| ProjectName | string | 否  | 可传但会被平台忽略，平台统一使用默认项目。             |

**素材建议：**

| 类型 | 建议                                      |
| -- | --------------------------------------- |
| 图片 | JPG / PNG；URL 可公网下载；内容应符合平台和上游内容安全要求。   |
| 视频 | MP4 等常见格式；分辨率、时长和编码需满足上游 Seedance 资产要求。 |
| 音频 | MP3 / WAV 等常见格式；URL 可公网下载。              |

**Response：**

```json theme={null}
{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "CreateAsset",
    "Version": "2024-01-01"
  },
  "Result": {
    "Id": "asset-20260701111803-yqveg",
    "AssetType": "Image",
    "Name": "product_reference_image",
    "Status": "Processing"
  }
}
```

**Response 字段：**

| 字段        | 说明                                  |
| --------- | ----------------------------------- |
| Id        | 平台 asset id，后续使用 `asset://<Id>` 引用。 |
| Status    | 素材状态，初始通常为 Processing。              |
| AssetType | 素材类型。                               |
| Name      | 创建时传入的素材名称。                         |

**重复创建行为：**

同一账号下，CreateAsset 会在同一上游供应商绑定内按 URL + AssetType + Name 精确幂等：

| 场景                                 | 行为                    |
| ---------------------------------- | --------------------- |
| 命中同一上游供应商，且 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                 | 当前没有可用素材供应商，请稍后重试或联系平台支持。 |

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

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

查询素材状态。建议创建后轮询到 Status=Active 再用于视频生成。

**Request：**

```bash theme={null}
curl -X POST 'https://api.highwayapi.ai/v3/synthetic/bytedance/ark?Action=GetAsset&Version=2024-01-01' \
  -H 'Authorization: Bearer <KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "Id": "asset-20260701111803-yqveg"
  }'
```

**Request 字段：**

| 字段 | 类型     | 必填 | 说明                          |
| -- | ------ | -- | --------------------------- |
| Id | string | 是  | CreateAsset 返回的平台 asset id。 |

**Response：**

```json theme={null}
{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "GetAsset",
    "Version": "2024-01-01"
  },
  "Result": {
    "Id": "asset-20260701111803-yqveg",
    "AssetType": "Image",
    "Name": "product_reference_image",
    "Status": "Active"
  }
}
```

**失败状态示例：**

```json theme={null}
{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "GetAsset",
    "Version": "2024-01-01"
  },
  "Result": {
    "Id": "asset-20260701111803-yqveg",
    "AssetType": "Video",
    "Name": "product_reference_video",
    "Status": "Failed",
    "ErrorMessage": "asset validation failed"
  }
}
```

**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: ... | 当前素材绑定的上游命名空间不可用，需要重新创建素材。 |

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

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

```json theme={null}
{
  "model": "seedance-2.0",
  "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 到其他供应商。 |

### 2.9 排障清单

| 现象              | 优先检查                                                                |
| --------------- | ------------------------------------------------------------------- |
| 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

### 3.1 适用范围

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

### 3.2 调用方式

统一入口：

```
POST https://api.highwayapi.ai/v3/bytedance/ark?Action={Action}&Version=2024-01-01
```

### 3.3 鉴权

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

### 3.4 支持 Action

| Action                      | 方法   | 说明                                          |
| --------------------------- | ---- | ------------------------------------------- |
| CreateVisualValidateSession | POST | 创建 H5 真人验证会话，返回 H5Link。                     |
| GetVisualValidateResult     | POST | 使用 H5 回调中的 BytedToken 换取验证结果和 AssetGroupID。 |
| CreateAsset                 | POST | 在资产组下创建资产。                                  |
| GetAsset                    | POST | 查询资产状态。                                     |

### 3.5 通用响应结构

**成功响应：**

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

**错误响应：**

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

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

**Request：**

```bash theme={null}
curl -X POST 'https://api.highwayapi.ai/v3/bytedance/ark?Action=CreateVisualValidateSession&Version=2024-01-01' \
  -H 'Authorization: Bearer <KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "CallbackURL": "https://your-app.example.com/liveness/done"
  }'
```

**Request 字段：**

| 字段          | 类型     | 必填 | 说明                     |
| ----------- | ------ | -- | ---------------------- |
| CallbackURL | string | 是  | 用户完成 H5 真人验证后跳转回客户侧页面。 |

**Response：**

```json theme={null}
{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "CreateVisualValidateSession",
    "Version": "2024-01-01"
  },
  "Result": {
    "H5Link": "https://example.com/liveness?token=...",
    "BytedToken": "xxx",
    "ExpiresInSec": 120,
    "ExpiresAt": "xxx"
  }
}
```

**Response 字段：**

| 字段           | 说明                                             |
| ------------ | ---------------------------------------------- |
| H5Link       | 客户前端打开该链接，让用户完成真人验证。                           |
| BytedToken   | 真人验证会话 token，后续调用 GetVisualValidateResult 时传入。 |
| ExpiresInSec | 有效期秒数，通常为 120 秒。                               |
| ExpiresAt    | 过期时间戳。                                         |

> 用户完成 H5 真人验证：客户前端打开 H5Link 后，用户按页面引导完成真人验证。H5 页面完成后会跳转到创建会话时传入的 CallbackURL。建议客户侧仍以 GetVisualValidateResult 的结果作为真人验证是否可用于创建素材的最终依据。

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

使用 BytedToken 查询真人验证结果，获取后续创建素材需要的 GroupId。

**Request：**

```bash theme={null}
curl -X POST 'https://api.highwayapi.ai/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。 |

**Response：**

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

**常见错误：**

| 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: ... | 当前素材会话不可用，需要重新发起认证。         |

### 3.8 创建资产 (CreateAsset)

使用 GroupId 和真人画像 URL 创建素材。CreateAsset 是异步处理，创建后建议调用 GetAsset 轮询素材状态。

**Request：**

```bash theme={null}
curl -X POST 'https://api.highwayapi.ai/v3/bytedance/ark?Action=CreateAsset&Version=2024-01-01' \
  -H 'Authorization: Bearer <KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "GroupId": "group-xxx-xxx",
    "URL": "https://your-cdn.example.com/portraits/user123.jpg",
    "AssetType": "Image",
    "Name": "user_123_portrait"
  }'
```

**Request 字段：**

| 字段        | 类型     | 必填 | 说明                                   |
| --------- | ------ | -- | ------------------------------------ |
| GroupId   | string | 是  | GetVisualValidateResult 返回的 GroupId。 |
| URL       | string | 是  | 真人画像图片 URL，平台必须能公网下载。                |
| AssetType | string | 否  | 素材类型，当前仅支持 Image；不传时默认 Image。        |
| Name      | string | 否  | 素材名称。                                |

**图片建议：**

| 项    | 建议                 |
| ---- | ------------------ |
| 格式   | JPG / PNG          |
| 可访问性 | 公网可下载，不能依赖客户内网鉴权。  |
| 内容   | 应为完成 H5 真人验证的同一真人。 |

**Response：**

```json theme={null}
{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "CreateAsset",
    "Version": "2024-01-01"
  },
  "Result": {
    "Id": "asset-xxx-xxx",
    "AssetType": "Image",
    "Name": "user_123_portrait",
    "Status": "Processing"
  }
}
```

**重复创建行为：**

同一账号下，CreateAsset 会按 GroupId + URL + AssetType + Name 精确幂等：

| 场景                             | 行为                      |
| ------------------------------ | ----------------------- |
| GroupId、URL、AssetType、Name 均相同 | 返回已创建的同一个平台 asset id。   |
| URL、AssetType 或 Name 任一不同      | 按新的创建请求处理，并继续进行真人一致性校验。 |

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

查询素材状态。建议创建后轮询到 Status=Active 再用于视频生成。

**Request：**

```bash theme={null}
curl -X POST 'https://api.highwayapi.ai/v3/bytedance/ark?Action=GetAsset&Version=2024-01-01' \
  -H 'Authorization: Bearer <KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "Id": "asset-xxx-yqveg"
  }'
```

**Response：**

```json theme={null}
{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "GetAsset",
    "Version": "2024-01-01"
  },
  "Result": {
    "Id": "asset-xxx-yqveg",
    "AssetType": "Image",
    "Name": "user_123_portrait",
    "Status": "Active"
  }
}
```

**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: ... | 当前素材不可用，需要重新创建。    |

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

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

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

### 3.11 完整流程示例

```bash theme={null}
export ASSET_ENDPOINT="https://api.highwayapi.ai/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>"
  }'
```

### 3.12 排障清单

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

***

## 四、素材引用总览

### 4.1 两种素材 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>                                       |

### 4.2 完整流程对比

**虚拟人像素材流程：**

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>` 引用