跳转到主要内容
POST
/
v1
/
videos
/
doubao-seedance-2-0
/
private-avatar
/
groups
curl --request POST \
  --url https://toapis.com/v1/videos/doubao-seedance-2-0/private-avatar/groups \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "brand-avatar-group",
    "description": "品牌虚拟人像素材组"
  }'

{
  "success": true,
  "message": "",
  "data": {
    "group_id": "group-20260318033332-*****",
    "name": "brand-avatar-group",
    "description": "品牌虚拟人像素材组"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.toapis.com/llms.txt

Use this file to discover all available pages before exploring further.

虚拟人像素材接口适用于你已经拥有可商用的虚拟角色素材，希望将这些素材提交到平台进行审核和处理，后续在 Seedance 2 视频生成中稳定复用的场景。 你可以用这组接口完成三件事：
  • 创建虚拟人像素材组
  • 上传图片、视频或音频素材
  • 查询素材处理状态，并在生成接口中引用
在开始接入前，你需要准备：
  • 可正常访问的公网素材 URL
  • 你的 ToAPIs API Key
  • 用于后续生成的视频提示词和素材引用方式

​
Authorizations

​
Authorization
string
必填
所有请求均需要使用 Bearer Token 进行认证。获取 API Key：访问 API Key 管理页面
Authorization: Bearer YOUR_API_KEY

​
接入流程

​
第一步：创建素材组

当你准备上传一组属于同一虚拟角色的素材时，先创建一个素材组。后续你可以把同一角色的不同素材放到同一个组里管理。 调用接口：
  • POST /v1/videos/doubao-seedance-2-0/private-avatar/groups
这个接口的作用：
  • 创建一个新的虚拟人像素材组
  • 返回后续上传素材要使用的 group_id
curl --request POST \
  --url https://toapis.com/v1/videos/doubao-seedance-2-0/private-avatar/groups \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "brand-avatar-group",
    "description": "品牌虚拟人像素材组"
  }'

{
  "success": true,
  "message": "",
  "data": {
    "group_id": "group-20260318033332-*****",
    "name": "brand-avatar-group",
    "description": "品牌虚拟人像素材组"
  }
}

​
第二步：上传素材

创建好素材组后，你就可以向该组提交素材。每次请求上传一个素材。 调用接口：
  • POST /v1/videos/doubao-seedance-2-0/private-avatar/assets
这个接口的作用：
  • 向指定的素材组提交一个素材
  • 返回 asset_id
  • 素材会进入异步处理流程
支持的 asset_type：
  • image
  • video
  • audio
客户真正需要关心的字段只有这些：
  • group_id：素材组 ID
  • asset_type：素材类型
  • source_url：素材公网 URL
  • name：素材名称，可选
curl --request POST \
  --url https://toapis.com/v1/videos/doubao-seedance-2-0/private-avatar/assets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "group_id": "group-20260318033332-*****",
    "asset_type": "image",
    "source_url": "https://files.example.com/avatar-full-body.jpg",
    "name": "full-body"
  }'

{
  "success": true,
  "message": "",
  "data": {
    "asset_id": "asset-20260318071009-*****",
    "group_id": "group-20260318033332-*****",
    "asset_type": "image",
    "source_url": "https://files.example.com/avatar-full-body.jpg",
    "status": "processing"
  }
}

​
第三步：查询素材状态

素材提交后不会立刻可用。你需要轮询查询素材状态，直到它变成 active。 调用接口：
  • GET /v1/videos/doubao-seedance-2-0/private-avatar/assets/{asset_id}
这个接口的作用：
  • 查询指定素材当前状态
  • 判断该素材是否已经可以在视频生成中使用
curl --request GET \
  --url https://toapis.com/v1/videos/doubao-seedance-2-0/private-avatar/assets/asset-20260318071009-***** \
  --header 'Authorization: Bearer <token>'

{
  "success": true,
  "message": "",
  "data": {
    "asset_id": "asset-20260318071009-*****",
    "group_id": "group-20260318033332-*****",
    "asset_type": "image",
    "source_url": "https://media.example.com/processed/avatar.jpg",
    "status": "active"
  }
}

​
素材要求与最佳实践

为了提高审核通过率和后续生成效果，建议你优先准备高质量、无遮挡、主体明确的素材。 推荐做法：
  • 使用稳定可访问的公网 URL，不要使用临时链接
  • 同一虚拟角色的素材尽量放在同一素材组中
  • 优先准备全身图和面部特写图，方便后续生成时保持形象一致
  • 尽量避免模糊、强遮挡、多人同框、强压缩素材

​
状态说明

​
processing
string
素材已提交，平台正在审核和处理，暂时还不能用于生成。
​
active
string
素材已可用，可以在视频生成接口中引用。
​
failed
string
素材处理失败。建议检查素材内容、清晰度、访问 URL 是否有效，然后重新提交。

​
在视频生成中的使用方式

当素材状态变为 active 后，你可以在视频生成接口中使用 asset://<ASSET_ID> 来引用它。 调用接口：
  • POST /v1/videos/generations
在生成请求里，把已经可用的素材写成 asset://<ASSET_ID> 即可。 
{
  "model": "doubao-seedance-2-0",
  "prompt": "让图片1中的角色站在城市夜景中缓慢转身，镜头轻微推进",
  "image_with_roles": [
    {
      "url": "asset://asset-20260318071009-*****",
      "role": "reference_image"
    }
  ]
}

​
常见注意事项

  • 上传成功不等于素材可立即使用，必须等到 status=active
  • 一个素材组适合同一虚拟角色，不建议把多个无关角色混在同一组
  • 素材 URL 需要保持可访问，否则会导致处理失败
  • 如果你只拿到了 group_id，还没有拿到 asset_id，说明你还没完成“上传素材”这一步