Human Portrait Assets

管理真人肖像素材，用于 Seedance 2.0 真人通道视频生成。human 通道需要通过 Asset API 上传的肖像素材。

概述

Human Portrait Asset API 允许你：

1. 上传素材 — 上传肖像图片或视频
2. 查询状态 — 等待素材处理完成
3. 用于生成 — 在视频生成请求中通过 asset:// URI 引用素材

认证

所有端点使用 API Key 认证。

Header	必填	说明
Authorization	是	Bearer YOUR_API_KEY
Content-Type	是	application/json

Base URL

https://api.get3w.com/v1/bytedance/assets

端点

上传素材

上传一张肖像图片或视频。

POST /v1/bytedance/assets

请求体：

字段	类型	必填	默认值	说明
url	string	是	—	肖像文件的公开 URL
asset_type	string	是	—	"Image" 或 "Video"
name	string	否	""	素材的显示名称

curl -X POST "https://api.get3w.com/v1/bytedance/assets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-cdn.com/portrait.jpg",
    "asset_type": "Image",
    "name": "My Portrait"
  }'

响应：

{
  "id": "asset-20260224200602-qn7wr"
}

获取素材状态

查询已上传素材的处理状态。

GET /v1/bytedance/assets/{asset_id}

curl -X GET "https://api.get3w.com/v1/bytedance/assets/asset-20260224200602-qn7wr" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应：

{
  "id": "asset-20260224200602-qn7wr",
  "status": "Active",
  "asset_type": "Image",
  "url": "asset://asset-20260224200602-qn7wr",
  "name": "My Portrait",
  "create_time": "2026-02-24T20:06:02Z",
  "update_time": "2026-02-24T20:06:10Z"
}

素材状态流转：Processing → Active | Failed

列出素材

查询账户下的素材列表。

POST /v1/bytedance/assets/list

请求体：

字段	类型	必填	默认值	说明
asset_type	string	否	—	按类型筛选（"Image" 或 "Video"）
statuses	string[]	否	—	按状态筛选（如 ["Active"]）
name	string	否	—	按名称筛选（模糊匹配）
page_number	int	否	1	页码
page_size	int	否	10	每页数量

curl -X POST "https://api.get3w.com/v1/bytedance/assets/list" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_type": "Image",
    "page_number": 1,
    "page_size": 10
  }'

响应：

{
  "items": [
    {
      "id": "asset-xxx",
      "status": "Active",
      "asset_type": "Image",
      "url": "asset://asset-xxx",
      "name": "My Portrait",
      "create_time": "2026-05-19T22:14:47Z",
      "update_time": "2026-05-19T22:15:00Z"
    }
  ],
  "total_count": 1
}

删除素材

DELETE /v1/bytedance/assets/{asset_id}

curl -X DELETE "https://api.get3w.com/v1/bytedance/assets/asset-xxx" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应：

{
  "success": true
}

在视频生成中使用素材

素材状态变为 Active 后，可以在 Seedance 2.0 的 human 通道请求中通过 asset:// URI 引用。

视频生成使用通用提交端点：

POST /v1/bytedance/seedance-2/reference-to-video

将 asset:// URI 放入 image_urls 参数，并设置 channel 为 "human"：

curl -X POST "https://api.get3w.com/v1/bytedance/seedance-2/reference-to-video" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A person walking in a park",
    "image_urls": ["asset://asset-20260224200602-qn7wr"],
    "channel": "human",
    "duration": 5,
    "resolution": "720p"
  }'

也支持 Seedance 2.0 Fast：

curl -X POST "https://api.get3w.com/v1/bytedance/seedance-2-fast/reference-to-video" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A person smiling at the camera",
    "image_urls": ["asset://asset-20260224200602-qn7wr"],
    "channel": "human",
    "duration": 5,
    "resolution": "720p"
  }'

注意事项

• 所有端点使用 API Key 认证（Bearer sk_xxx）
• 每个用户只能访问自己的素材
• 素材必须达到 Active 状态后才能用于视频生成
• asset:// URI 格式仅适用于 Seedance 2.0 和 Seedance 2.0 Fast 的 human 通道
• 素材分组由系统内部管理，用户无需创建或管理分组
• human 通道支持真人视频生成，standard 通道不支持真人