Seedance 虚拟人像素材

素材库接口采用火山方舟原生 Action 协议:所有操作都是 POST 到根路径,通过查询参数 Action 与 Version 指定操作,请求体为 JSON(字段名为大驼峰 PascalCase),鉴权只需你的 MaiToken API Key——平台会代你完成上游签名。

你可以用这组接口完成三件事:

• 创建素材组(Asset Group),管理同一角色的素材
• 提交图片 / 视频 / 音频素材(传公网 URL,非文件上传)
• 查询素材处理状态,在生成接口中引用

在开始接入前,你需要准备:

• 可正常访问的公网素材 URL
• 你的 MaiToken API Key

Authorizations

Authorization: Bearer YOUR_API_KEY

端点形态

所有素材接口共用同一入口:

POST /?Action={操作名}&Version=2024-01-01Content-Type: application/json

虚拟人像相关的 Action 全集:

白名单外的 Action 返回 404 unsupported_endpoint。

接入流程

sequenceDiagram    participant Client as 调用方    participant MaiToken as MaiToken     Client->>MaiToken: 1. CreateAssetGroup    MaiToken-->>Client: Result.Id (group-*)     Client->>MaiToken: 2. CreateAsset (GroupId + 素材 URL)    MaiToken-->>Client: Result.Id (asset-*)     loop 直到素材可用      Client->>MaiToken: 3. GetAsset (Id)      MaiToken-->>Client: Result.Status (Processing / Active / Failed)    end

第一步:创建素材组

同一虚拟角色的素材放入同一素材组管理。

请求体字段:

• Name(可选):素材组名称
• Description(可选):素材组描述
• GroupType(可选):素材组类型,官方当前仅支持 AIGC(虚拟人像)

第二步:提交素材

向素材组提交素材。每次请求提交一个素材,素材以公网 URL 传入(不支持文件直传 / Base64)。

请求体字段:

• GroupId(必填):素材组 Id
• URL(必填):素材公网可访问地址
• AssetType(必填):Image / Video / Audio
• Name(可选):素材名称,仅用于 ListAssets 模糊搜索

第三步:轮询素材状态

素材提交后进入异步审核与处理,需轮询 GetAsset 直到 Status 变为 Active。查询同样是 POST,素材 Id 放在请求体中。

状态说明

• Processing — 素材已提交,正在审核和处理,暂时不能用于生成。
• Active — 素材已可用,可以在视频生成接口中引用。
• Failed — 素材处理失败。建议检查素材内容、清晰度、URL 是否可访问后重新提交。

素材要求与最佳实践

• 图片:jpeg / png / webp / bmp / tiff / gif / heic,单张 < 30MB,宽高比 (0.4, 2.5),边长 (300, 6000) px
• 视频:mp4 / mov,时长 2–15s,单个 ≤ 200MB
• 音频:wav / mp3,时长 2–15s,单个 ≤ 15MB
• 使用稳定可访问的公网 URL,不要使用临时链接
• 同一角色的素材放同一素材组;优先准备竖版全身图与面部特写图

数据隔离与项目名

• 素材归属于你的账号:只能访问经本平台创建的素材,访问他人或平台外创建的资产一律返回 404 asset_not_found;ListAssets / ListAssetGroups 也只会返回你名下的素材组。
• 请求体中的 ProjectName 为可选;若平台侧已为渠道统一配置项目名,你请求中的 ProjectName 会被覆盖为平台配置值——通常无需自行传入。

在视频生成中的使用方式

素材 Status=Active 后,在 Seedance 视频生成 的 content 数组中以 asset://<ASSET_ID> 引用,提示词中用「图片1」等指代:

{  "model": "doubao-seedance-2-0",  "content": [    { "type": "text", "text": "让图片1中的角色站在城市夜景中缓慢转身,镜头轻微推进" },    {      "type": "image_url",      "image_url": { "url": "asset://asset-20260716071009-*****" },      "role": "reference_image"    }  ]}

常见注意事项

• 提交成功不等于可立即使用,必须等到 Status=Active
• 素材 URL 需保持可访问,否则会处理失败
• 真人人像素材需先完成真人认证,见 真人人像素材