easyai-ai-gateway/docs/seedance-portrait-assets.md

Seedance 真人资产（Volces）

网关会把真人源文件保存到既有文件存储，并在 Volces 平台的火山 Assets 库创建绑定。生成时只能引用已经对当前用户、当前平台激活的资产，最终发送给火山的视频内容 URL 为 asset://<remote_asset_id>。

平台配置

在 integration_platforms.config 为对应的 volces 平台添加：

{
  "seedancePrivateAsset": {
    "enabled": true,
    "accessKey": "AK...",
    "secretKey": "SK...",
    "projectName": "default",
    "assetGroupId": "asset-group-id",
    "assetEndpoint": "https://ark.cn-beijing.volcengineapi.com"
  }
}

assetEndpoint 可省略。源文件 URL 必须是火山可访问的绝对 http(s) 地址；同步时会拒绝本地路径、file:// 与相对 URL。因此生产环境应配置带公网 URL 的文件存储或 PublicBaseURL。

Desktop / server-main 兼容路由

• GET /api/v1/resource/material/seedance-portrait-assets/capability
• GET /api/v1/resource/material/user/materials?category=seedance_portrait_asset
• POST /api/v1/resource/material（multipart：file、data）
• POST /api/v1/resource/material/seedance-portrait-assets/sync
• POST /api/v1/video/generations 与 GET /api/v1/ai/result/{taskID}

创建真人资产要求 private_avatar_eligible: true。同步接口可重复调用；资产在火山返回 Active 前，视频提交会返回 portrait_asset_processing，而不会把原始人像媒体当成普通参考图发送。

火山任务兼容路由

• POST /api/v3/contents/generations/tasks
• GET /api/v3/contents/generations/tasks
• GET /api/v3/contents/generations/tasks/{taskID}
• DELETE /api/v3/contents/generations/tasks/{taskID}

列表接口兼容火山的 page_num、page_size、filter.status、filter.task_ids（可重复）和 filter.model，并返回官方 items、total 字段；data、page 是保留的网关附加字段。

公开 id 是网关任务 ID，原始火山任务 ID 保留在 upstream_task_id。响应保留火山的 content、usage、seed、resolution 等字段，并额外保留网关账单字段。