Seedance 2.0 素材库接口说明

本文档说明在本网关中 Seedance 2.0 视频生成 与 方舟 / BytePlus 素材资产库（OpenAPI） 的配合方式：素材上传与管理走素材接口；生成任务通过 metadata 引用 asset:// 素材 ID；网关会做 用户归属校验

请求体字段级说明以火山方舟 / BytePlus 官方「素材 Universal OpenAPI」「视频生成 API」文档为准；下文侧重 网关 URL、鉴权、Action 列表与 Seedance 2.0 模型名。

一、前置条件

3. 调用方指定「素材所用渠道」

OpenAPI 调用素材接口时，必须指明与视频任务一致的渠道：

Query：channel_id=<数字渠道ID>

或 Header：X-Ark-Channel-Id: <数字渠道ID>

该渠道须：已启用、对用户令牌分组可见

二、Seedance 2.0 视频生成（引用素材）

1. 路由与鉴权

方法	路径	鉴权
`POST`	`/v1/video/generations`	API Token（`Authorization: Bearer <sk>`）+ 分发中间件
`GET`	`/v1/video/generations/:task_id`	同上

（兼容路径另有 /v1/videos 等，以 router/video-router.go 为准。）

2. 支持的 Seedance 2.0 模型名（示例）

网关侧任务白名单包含（与上游方舟模型 ID 一致，含国际 dreamina）：

doubao-seedance-2-0-260128

doubao-seedance-2-0-fast-260128

dreamina-seedance-2-0-260128

dreamina-seedance-2-0-fast-260128

3. 请求体要点（与素材结合）

提交 JSON 与 OpenAI 风格任务请求对齐，核心字段包括：

model：上述 Seedance 2.0 模型名之一

prompt：文本提示

size：如 1280x720（可选，会映射为上游 resolution / ratio）

metadata：可选；其中 content 数组可包含图片/视频/音频引用

在 metadata.content 中，若某条目的 image_url / video_url / audio_url 下 url 为 asset://<素材资源ID>，网关会在提交前校验：当前用户在该 channel_id 下是否拥有该素材绑定。未绑定或无权限将返回 403（错误类型 ark_asset_forbidden）。

asset:// 示例（节选）：

{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "基于参考图生成短片",
  "size": "1280x720",
  "metadata": {
    "resolution": "720p",
    "content": [
      {
        "type": "image_url",
        "image_url": { "url": "asset://asset-20260318071009-abc" }
      }
    ]
  }
}

视频参考同理可使用 type: "video_url" 与 video_url.url: "asset://..."。

三、素材库 OpenAPI（网关代理）

网关将客户端请求 原样 JSON Body 转发至上游 Universal OpenAPI：POST {BaseURL}/?Action={Action}&Version={Version}，其中 Version 固定为 2024-01-01（与代码 pkg/arkassets.DefaultAPIVersion 一致），由渠道配置的 AK/SK 完成签名。

1. 用户 OpenAPI（推荐对接第三方）

方法	路径	鉴权
`POST`	`/v1/ark/assets/:action`	API Token

:action 为下游 Action 名（见下表），大小写敏感。

必须带 channel_id 或 X-Ark-Channel-Id。

响应 透传上游 的 HTTP 状态码与 Content-Type（多为 application/json）。

业务错误时网关可能包装为 JSON：{ "error": { "message": "...", "type": "invalid_request_error" } }。

用户隔离策略简述：

创建素材组 / 素材成功后，网关会登记 用户 + 渠道 + 资源 ID 绑定。

Get / Update / Delete 仅允许操作已绑定资源。

ListAssets / ListAssetGroups 会自动将列表过滤到当前用户可见范围

2. 控制台 Session（浏览器 / 管理端调试）

方法	路径	鉴权
`POST`	`/api/user/ark-assets/:action`	用户 Session（与控制台一致）

同样需 channel_id 或 X-Ark-Channel-Id，行为与 OpenAPI 用户隔离一致，响应为控制台常用 { success, message, data? } 风格；成功时代理体仍可能为 二进制或 JSON，以实际 Content-Type 为准。

3. 列出当前用户可用素材渠道（控制台）

方法	路径	鉴权
`GET`	`/api/user/ark-channels`	用户 Session

返回分组下可见渠道列表；每项含 ark_ready（是否已配置素材 AK/SK）等字段，便于前端引导用户选择 channel_id。

四、允许的 Action 列表

与 pkg/arkassets.AllowedActions 一致：

Action	说明
`CreateAssetGroup`	创建素材组
`CreateAsset`	创建素材（需合法 `GroupId`）
`ListAssetGroups`	列举素材组
`ListAssets`	列举素材
`GetAsset`	查询素材详情（Body 含 `Id`）
`GetAssetGroup`	查询素材组详情（Body 含 `Id`）
`UpdateAssetGroup`	更新素材组
`UpdateAsset`	更新素材
`DeleteAsset`	删除素材
`DeleteAssetGroup`	删除素材组
`CreateVisualValidateSession`	真人 H5 活体会话创建（须 Ark 区域 Host）
`GetVisualValidateResult`	活体结果查询（同上）

未列入的 Action 网关会直接 400（unsupported ark asset action）。

各 Action 的 JSON 字段名、嵌套结构、分页 Filter 等须查阅火山 / BytePlus 当前版本文档（与官方控制台「素材」OpenAPI 示例保持一致即可）。

五、调用示例（curl 骨架）

将 BASE、SK、CH 替换为实际网关地址、令牌与渠道 ID：

body.json 中 metadata.content 使用上一节 asset:// 形式即可；视频任务走推理渠道，不要求在 URL 上带 channel_id（由网关分发逻辑选择渠道）；素材引用校验使用任务实际落到的渠道与用户 ID。

六、错误与排障

现象	可能原因
`channel not found` / 无法解析渠道	`channel_id` 无效或未传
`channel does not belong to the current user group`	令牌分组无权使用该渠道
`无权访问该素材资源` / 403	`asset://` 对应素材未在该用户+渠道下登记
活体相关 400	`ark_asset_openapi_host` 不是 `ark..volcengineapi.com` 或 `ark..byteplusapi.com`
`unsupported ark asset action`	Action 拼写错误或不在白名单

七、官方文档建议（外链）

请在对接时同时打开供应商文档核对字段与限额（链接随官方更新可能变化）：

火山方舟：视频生成（Seedance）、素材资产库 Universal API、活体核验等说明。

BytePlus：国际区 Ark 终端、素材与视频计费说明。

以上文档为网关行为说明，不替代上游 API 的完整参数规范。

Seedance 2.0 素材库接口说明

一、前置条件#

3. 调用方指定「素材所用渠道」#

二、Seedance 2.0 视频生成（引用素材）#

1. 路由与鉴权#

2. 支持的 Seedance 2.0 模型名（示例）#

3. 请求体要点（与素材结合）#

三、素材库 OpenAPI（网关代理）#

1. 用户 OpenAPI（推荐对接第三方）#

2. 控制台 Session（浏览器 / 管理端调试）#

3. 列出当前用户可用素材渠道（控制台）#

四、允许的 Action 列表#

五、调用示例（curl 骨架）#

六、错误与排障#

七、官方文档建议（外链）#