豆包 Seedance 素材库

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

概述

Seedance 2.0 的素材库分两类：

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

整体流程：

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

前置条件（管理员配置）

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

常见报错 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

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": "示例" } }'

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" } }'

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" } }'

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（真人认证，见下）。上传成功返回：

{ "code": 0, "message": "ok", "data": { "Id": "asset-20260...-xxxx" } }

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

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

真人认证（简化）

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

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" } }'

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 生成动态表单：

{
  "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 的场景。

虚拟人像 / 普通素材流程

第一步：创建素材组

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"
  }'

响应：

{ "ResponseMetadata": { "RequestId": "..." }, "Result": { "Id": "group-20260318033332-xxxxx" } }

第二步：上传素材

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

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": "角色正面图"
  }'

响应：

{ "Result": { "Id": "asset-20260318071009-xxxxx" } }

第三步：轮询素材状态

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

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" }'

响应：

{ "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 活体认证）。

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

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 秒，仅一次性使用）：

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

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

第二步：用 BytedToken 换 GroupId

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_..." }'

{ "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：

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：

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 拒绝（防止盗用他人的真人/虚拟素材）。多个用户共用同一渠道（同一火山账号）时也互不可见。
若你在火山控制台 / 体验中心（而非经本网关）创建素材，网关没有该映射；这些素材对普通用户不可见 / 不可操作（隔离的预期行为）。多渠道（多账号）场景下请使用绑定到对应渠道的令牌（令牌固定渠道）来保证路由正确。

开始使用

模型与服务

使用指南

概述

前置条件（管理员配置）

鉴权

简化接口（推荐）

支持的 action

真人认证（简化）

在 Playground 使用

原生镜像接口

虚拟人像 / 普通素材流程

第一步：创建素材组

第二步：上传素材

第三步：轮询素材状态

其它管理接口

真人人像素材流程

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

第二步：用 BytedToken 换 GroupId

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

在视频生成中引用素材

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

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

注意事项

​概述

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

​鉴权

​简化接口（推荐）

​支持的 action

​真人认证（简化）

​在 Playground 使用

​原生镜像接口

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

​第一步：创建素材组

​第二步：上传素材

​第三步：轮询素材状态

​其它管理接口

​真人人像素材流程

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

​第二步：用 BytedToken 换 GroupId

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

​在视频生成中引用素材

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

​方式二：原生 /doubao 接口

​注意事项

概述

前置条件（管理员配置）

鉴权

简化接口（推荐）

支持的 action

真人认证（简化）

在 Playground 使用

原生镜像接口

虚拟人像 / 普通素材流程

第一步：创建素材组

第二步：上传素材

第三步：轮询素材状态

其它管理接口

真人人像素材流程

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

第二步：用 BytedToken 换 GroupId

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

在视频生成中引用素材

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

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

注意事项