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

# 豆包 Seedance 素材库

> Seedance 2.0 私域素材库：上传虚拟人像/真人素材，并在视频生成中通过 asset:// 引用。

豆包 Seedance 2.0 支持把素材（图片/视频/音频）入库，生成视频时用 `asset://<asset_id>` 引用，无需每次传公网 URL。网关 1:1 镜像火山官方素材库接口（`/doubao/?Action=...`）。

## 概述

Seedance 2.0 的素材库分两类：

* **虚拟人像 / 普通素材**：你拥有可商用的素材，直接创建素材组 → 上传 → 轮询 → 使用。
* **真人人像素材**：需先完成真人认证（H5 活体认证），认证通过后再上传该真人的素材。官方禁止直接上传含真人人脸的参考图，真人素材必须走此流程。

整体流程：

```mermaid theme={null}
sequenceDiagram
    participant 客户端
    participant 网关 as API 网关
    participant 火山 as 火山方舟
    客户端->>网关: POST /doubao/?Action=CreateAsset
    网关->>火山: AK/SK V4 签名转发
    火山-->>网关: { Result: { Id: "asset-..." } }
    网关-->>客户端: 返回 asset_id（并记录 asset→渠道映射）
    loop 轮询直到 Active
        客户端->>网关: POST /doubao/?Action=GetAsset
        网关-->>客户端: { Result: { Status: "Processing" } }
    end
    客户端->>网关: POST /v1/task/submit （reference_images: ["asset://asset-..."]）
    网关-->>客户端: 生成视频，自动路由回创建素材的渠道
```

**账号绑定（重要）**：`asset_id` 与火山账号强绑定。素材在哪个账号下创建，就只能被同一账号生成视频时引用。网关会自动记录"素材 → 渠道"映射，生成请求引用 `asset://` 时会被锁定路由回创建它的渠道，无需你手动指定。

***

## 前置条件（管理员配置）

1. 在该 VolcEngine（豆包）渠道的"高级设置"中填写 **素材库 Access Key (AK)** 与 **Secret Key (SK)**。
   * 视频生成仍使用渠道的 `ark-` API Key（Bearer），二者独立。
   * **AK/SK 必须与该 `ark-` Key 属于同一火山账号**，否则生成时引用 `asset://` 会报"素材不存在"。
   * 若渠道 Key 本身就是 `ak\|sk` 格式，可不单独填 AK/SK，网关会自动复用。
2. （推荐）在渠道高级设置填写 **素材库项目 (ProjectName)**。`ProjectName` 是火山 IAM 的项目（资源范围），必须是该 AK/SK **有权限**的项目。配置后网关会**强制覆盖**用户请求体里的 `ProjectName`，由渠道统一控制——这样终端用户**无需也不要**自己传 `ProjectName`，避免传错导致 `AccessDenied`，也保证"建组 / 传素材 / 查询"用同一项目。留空则透传用户传的值（火山默认 `default`）。
3. 把哨兵模型 **`doubao-asset`** 加入该渠道的模型列表（用于把素材管理请求路由到此渠道）。
4. 素材管理调用本身**免费**，不计费。

常见报错 `AccessDenied: User is not authorized to perform: ark:CreateAsset on resource: trn:iam::<账号>:project/<项目>` —— 这是火山 IAM 权限问题（不是网关问题）：该 AK/SK（多为子账号）在对应项目下没有 `ark:CreateAsset` 等权限。解决：用主账号 AK/SK，或在火山访问控制里给该子账号授予 Ark 素材相关权限并覆盖对应项目范围；同时建议用渠道的"素材库项目"统一指定 `ProjectName`。

***

## 鉴权

所有请求使用网关令牌：

```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

素材库统一端点（镜像官方）：`POST /doubao/?Action=<Action>&Version=2024-01-01`

***

## 简化接口（推荐）

除了镜像官方的 `/doubao/?Action=...`，网关还提供一套**统一的简化接口**：复用平台通用的 `POST /v1/task/submit` 入口和 `{model, input}` 风格，隐藏火山的 Action / GroupId / ProjectName / 签名等复杂度——**大多数场景推荐使用**。

* 入口固定 `POST /v1/task/submit`，`model` 固定为 `doubao-asset`，用 `input.action` 区分操作。
* **同步返回**：素材操作很快，提交即返回结果（`asset_id` 等），无需轮询。
* **自动托管素材组**：`upload` 不传 `group_id` 时，网关自动为你创建并复用一个**用户专属素材组**；与原生 `/doubao` 接口落到**同一个组**，两种方式上传的素材互通。
* 统一响应：`{ "code": 0, "message": "ok", "data": {...} }`（`code != 0` 表示错误）。

### 支持的 action

```bash 上传素材 theme={null} theme={null}
curl -X POST "https://api.ephone.ai/v1/task/submit" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{ "model": "doubao-asset", "input": { "action": "upload", "url": "https://example.com/a.png", "asset_type": "Image", "name": "示例" } }'
```

```bash 查询素材 theme={null} theme={null}
curl -X POST "https://api.ephone.ai/v1/task/submit" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{ "model": "doubao-asset", "input": { "action": "query", "asset_id": "asset-xxx" } }'
```

```bash 列出本人素材 theme={null} theme={null}
curl -X POST "https://api.ephone.ai/v1/task/submit" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{ "model": "doubao-asset", "input": { "action": "list" } }'
```

```bash 删除素材 theme={null} theme={null}
curl -X POST "https://api.ephone.ai/v1/task/submit" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{ "model": "doubao-asset", "input": { "action": "delete", "asset_id": "asset-xxx" } }'
```

`action` 取值：`upload`（上传，需 `url`+`asset_type`，可选 `name`/`group_id`）、`query`（查询，需 `asset_id`）、`list`（列出本人素材）、`delete`（删除，需 `asset_id`）、`create_validate_session` / `get_validate_result`（真人认证，见下）。

上传成功返回：

```json theme={null}
{ "code": 0, "message": "ok", "data": { "Id": "asset-20260...-xxxx" } }
```

素材处理完成后（`query` 返回 `Status: "Active"`）即可在视频生成里用 `asset://<asset_id>` 引用。

**资源隔离 + 互通**：每个用户的素材进各自专属素材组，彼此隔离；同一用户无论用简化接口还是原生 `/doubao` 接口创建的素材，都在同一组、可互相引用。

### 真人认证（简化）

真人认证需要演员在手机上完成扫脸活体认证，这一步发生在"演员浏览器 ↔ 火山"之间，网关无法代办——你仍需准备一个 `callback_url` 接收火山扫脸完成后的回跳。简化接口只统一了入口与字段：

```bash 1. 创建认证会话 theme={null} theme={null}
curl -X POST "https://api.ephone.ai/v1/task/submit" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{ "model": "doubao-asset", "input": { "action": "create_validate_session", "callback_url": "https://your.app/cb" } }'
```

```bash 2. 用 byted_token 换 group theme={null} theme={null}
curl -X POST "https://api.ephone.ai/v1/task/submit" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{ "model": "doubao-asset", "input": { "action": "get_validate_result", "byted_token": "byted_token_..." } }'
```

拿到认证后的 `group_id` 后，用 `upload` 并显式传 `group_id` 把该真人素材传入对应组。

### 在 Playground 使用

管理员给 `doubao-asset` 模型配置 `playground_mode=task` 和如下 `task_input_schema`（JSON Schema），即可在 Playground 生成动态表单：

```json theme={null}
{
  "type": "object",
  "properties": {
    "action": { "type": "string", "enum": ["upload", "query", "list", "delete", "create_validate_session", "get_validate_result"], "title": "操作" },
    "url": { "type": "string", "title": "素材 URL（upload）" },
    "asset_type": { "type": "string", "enum": ["Image", "Video", "Audio"], "title": "素材类型（upload）" },
    "name": { "type": "string", "title": "名称（可选）" },
    "group_id": { "type": "string", "title": "素材组 ID（可选/真人素材）" },
    "asset_id": { "type": "string", "title": "素材 ID（query/delete）" },
    "callback_url": { "type": "string", "title": "回调地址（真人认证）" },
    "byted_token": { "type": "string", "title": "BytedToken（真人认证）" }
  },
  "required": ["action"]
}
```

***

## 原生镜像接口

以下是 1:1 镜像火山官方的底层接口（`/doubao/?Action=...`）。如果你已使用上面的简化接口，通常无需直接调用这些；它们用于需要精确控制 `GroupId`、或直接对接火山官方 SDK 的场景。

## 虚拟人像 / 普通素材流程

### 第一步：创建素材组

```bash cURL theme={null} theme={null}
curl -X POST "https://api.ephone.ai/doubao/?Action=CreateAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "我的角色组",
    "Description": "用于 Seedance 视频生成",
    "GroupType": "AIGC"
  }'
```

响应：

```json theme={null}
{ "ResponseMetadata": { "RequestId": "..." }, "Result": { "Id": "group-20260318033332-xxxxx" } }
```

### 第二步：上传素材

每次上传一个素材，`AssetType` 可为 `Image` / `Video` / `Audio`，`URL` 必须是公网可访问地址。

```bash cURL theme={null} theme={null}
curl -X POST "https://api.ephone.ai/doubao/?Action=CreateAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId": "group-20260318033332-xxxxx",
    "URL": "https://example.com/character.png",
    "AssetType": "Image",
    "Name": "角色正面图"
  }'
```

响应：

```json theme={null}
{ "Result": { "Id": "asset-20260318071009-xxxxx" } }
```

### 第三步：轮询素材状态

上传是异步处理，需轮询直到 `Status` 变为 `Active` 才能用于生成（`Failed` 表示处理失败）。

```bash cURL theme={null} theme={null}
curl -X POST "https://api.ephone.ai/doubao/?Action=GetAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "Id": "asset-20260318071009-xxxxx" }'
```

响应：

```json theme={null}
{ "Result": { "Id": "asset-20260318071009-xxxxx", "Status": "Active", "AssetType": "Image", "URL": "https://...(12h 有效)" } }
```

### 其它管理接口

`ListAssetGroups` / `ListAssets` / `GetAssetGroup` / `UpdateAssetGroup` / `UpdateAsset` / `DeleteAsset` / `DeleteAssetGroup`，用法相同：`POST /doubao/?Action=<Action>&Version=2024-01-01` + 对应 JSON body。

***

## 真人人像素材流程

真人素材需先完成真人认证（H5 活体认证）。

```mermaid theme={null}
flowchart LR
    A["1. CreateVisualValidateSession 拿 H5Link + BytedToken"] --> B["2. 演员打开 H5Link 完成认证<br/>火山回跳到你的 CallbackURL"]
    B --> C["3. GetVisualValidateResult 用 BytedToken 换 GroupId"]
    C --> D["4. CreateAsset 上传素材"]
    D --> E["5. GetAsset 轮询直到 Active"]
```

### 第一步：创建真人认证会话

```bash cURL theme={null} theme={null}
curl -X POST "https://api.ephone.ai/doubao/?Action=CreateVisualValidateSession&Version=2024-01-01" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "CallbackURL": "https://your-callback.com/done" }'
```

响应包含 `H5Link`（演员打开完成认证）和 `BytedToken`（有效期 120 秒，仅一次性使用）：

```json theme={null}
{ "Result": { "H5Link": "https://...volccdn.com/verify?token=...", "BytedToken": "byted_token_..." } }
```

演员在移动端打开 `H5Link` 完成活体认证后，火山会重定向回你的 `CallbackURL`，并带上 `resultCode`（`10000` 表示成功）等参数。

### 第二步：用 BytedToken 换 GroupId

```bash cURL theme={null} theme={null}
curl -X POST "https://api.ephone.ai/doubao/?Action=GetVisualValidateResult&Version=2024-01-01" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "BytedToken": "byted_token_..." }'
```

```json theme={null}
{ "Result": { "GroupId": "group-..." } }
```

> 认证未完成时可能返回 `ValidatePending`，稍后重试即可。

### 第三、四步：上传素材 + 轮询

拿到 `GroupId` 后，调用 `CreateAsset`（同虚拟人像第二步）上传该真人的素材，再用 `GetAsset` 轮询到 `Active`。同一真人的不同妆造可放在同一 `GroupId` 下。

***

## 在视频生成中引用素材

素材 `Status=Active` 后，把它写成 `asset://<asset_id>` 即可在生成请求中引用。

### 方式一：统一异步任务接口 `/v1/task/submit`

把 `asset://...` 放进 `reference_images` / `first_frame` / `reference_videos` / `reference_audio`：

```bash cURL theme={null} theme={null}
curl -X POST "https://api.ephone.ai/v1/task/submit" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "input": {
      "prompt": "让图中的角色站在落地窗前缓慢转身，镜头轻微推进",
      "reference_images": ["asset://asset-20260318071009-xxxxx"]
    }
  }'
```

### 方式二：原生 `/doubao` 接口

把 `asset://...` 放进 `content` 数组的 `image_url` / `video_url` / `audio_url`：

```bash cURL theme={null} theme={null}
curl -X POST "https://api.ephone.ai/doubao/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      { "type": "text", "text": "让角色在城市夜景中缓慢转身" },
      { "type": "image_url", "image_url": { "url": "asset://asset-20260318071009-xxxxx" }, "role": "reference_image" }
    ]
  }'
```

***

## 注意事项

* 上传成功不等于可立即使用，必须等到 `Status=Active`。
* 素材 URL 需保持公网可访问，否则处理会失败。
* 一个素材组建议只放同一角色 / 同一真人的素材。
* `asset_id` 账号级绑定：跨账号无法引用。网关在素材创建时记录"素材 → 渠道"映射，生成时自动锁定回该渠道。
* **用户级隔离**：每个令牌（用户）只能查询 / 修改 / 删除**自己经网关创建**的素材；`ListAssets` / `ListAssetGroups` 只返回本人素材；用他人的 `asset_id` 调 `GetAsset` / `DeleteAsset` 等会被网关以 `403 AssetNotOwned` 拒绝；**生成视频时引用他人的 `asset://` 同样会被 403 拒绝**（防止盗用他人的真人/虚拟素材）。多个用户共用同一渠道（同一火山账号）时也互不可见。
* 若你在火山控制台 / 体验中心（而非经本网关）创建素材，网关没有该映射；这些素材**对普通用户不可见 / 不可操作**（隔离的预期行为）。多渠道（多账号）场景下请使用绑定到对应渠道的令牌（令牌固定渠道）来保证路由正确。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.