虚拟人像素材入库
seedance2-private-avatar：POST /v1/seedance2/private-avatar 虚拟人像素材异步入库，GET 查询审核结果，免费
仅支持虚拟人像 / AIGC 生成人像素材，不支持真人照片认证。上传真人照片可能审核不通过，或在后续更新中被拒绝入库。本页仅覆盖入库与查询；asset:// 在 Seedance 2.0 生成请求中的传参方式尚未在文档中开放。
为 Seedance 2.0 的"人物一致性"生成能力准备可复用的人像素材：提交图片素材后平台异步审核，审核通过的素材返回 asset:// 引用，可用于保持同一人物形象。
| 项 | 值 |
|---|---|
| 模型 | seedance2-private-avatar |
| 模式 | 异步（提交入库任务 → 轮询 GET /v1/seedance2/private-avatar/{task_id}，建议间隔 5-10 秒） |
| 计费 | 素材入库对用户免费，见计费 |
| 鉴权 | Authorization: Bearer $LOOPTOKEN_API_KEY、Content-Type: application/json |
快速开始
curl https://api.vibelab.me/v1/seedance2/private-avatar \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"group": {"name": "my-virtual-character"},
"assets": [
{"url": "https://example.com/avatar-front.jpg", "name": "front"},
{"url": "https://example.com/avatar-side.jpg", "name": "side"}
]
}'提交成功返回 HTTP 202：
{
"code": 200,
"data": {
"id": "avatar_xxx",
"object": "seedance.avatar.asset.task",
"status": "processing",
"progress": 0
}
}请求参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
group | object | 否 | - | 新建素材组，{name, description}；与 group_id 二选一，两者同传返回 400 |
group_id | string | 否 | - | 已有素材组 ID，向该组追加素材；只能传本账号历史任务成功创建过的 group_id，传他人或不存在的 group_id 返回 404 |
project_name | string | 否 | default | 素材所属项目名 |
asset_type | string | 否 | Image | Image、Video、Audio 之一 |
assets | array | 是 | - | 待入库素材数组，元素为 {url, name}，最多 20 个；url 必须为非空 http(s) 地址，name 必须非空 |
group 与 group_id 必须传且只能传一个：完全不传或两者同传都返回 400。首次入库传 group 新建素材组；后续向同一素材组追加素材传 group_id。
单素材场景支持兼容写法：直接在请求顶层传 url、name，无需包裹成 assets 数组，平台会自动归一化为单元素的 assets 数组。
请求示例
完整请求示例：
{
"group": {
"name": "my-virtual-character",
"description": "虚拟主播形象素材"
},
"project_name": "default",
"asset_type": "Image",
"assets": [
{
"url": "https://example.com/avatar-front.jpg",
"name": "front"
},
{
"url": "https://example.com/avatar-side.jpg",
"name": "side"
}
]
}单素材兼容写法：
{
"group": { "name": "my-virtual-character" },
"url": "https://example.com/avatar-front.jpg",
"name": "front"
}响应
提交响应
| 字段 | 类型 | 说明 |
|---|---|---|
data.id | string | 平台任务 ID，格式 avatar_ + UUID，用于后续查询 |
data.object | string | 固定为 seedance.avatar.asset.task |
data.status | string | 提交确认状态，此时任务已受理但尚无审核结果；任务实际状态以查询接口返回的 status 为准 |
data.progress | integer | 审核进度百分比，提交时为 0 |
查询审核结果
GET /v1/seedance2/private-avatar/{task_id}，路径参数 task_id 为提交接口返回的 avatar_... ID。
任务状态
| status | 说明 |
|---|---|
pending | 排队中，尚未开始审核 |
running | 审核中 |
succeeded | 全部素材审核通过 |
failed | 任务未完全成功；批量提交时任一素材审核失败，整单即判定为 failed |
pending/running 状态下 result 字段不出现或为空，轮询直至进入 succeeded 或 failed 终态。
批量入库的部分失败语义：只要 assets 中有一个素材未通过审核，整个任务的 status 就是 failed，而不是部分成功状态。但这不代表全部素材都不可用——已通过审核的素材仍出现在 result.usable_assets 中，可以正常使用 asset:// 引用。请按 result.usable_assets 而不是顶层 status 判断单个素材是否可用。
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
data.id | string | 平台任务 ID |
data.status | string | pending / running / succeeded / failed |
data.progress | integer | 审核进度百分比，0-100 |
data.result.assets | array | 本次任务涉及的全部素材，元素含 asset_id、asset_url（asset:// 引用） |
data.result.usable_assets | array | 审核通过、可直接使用的素材子集，元素结构同 assets |
data.result.failed_assets | array | 审核未通过的素材，含失败原因；任务全部成功时为空数组 |
成功示例：
{
"code": 200,
"data": {
"id": "avatar_xxx",
"status": "succeeded",
"progress": 100,
"result": {
"assets": [
{
"asset_id": "asset-xxx",
"asset_url": "asset://asset-xxx"
},
{
"asset_id": "asset-yyy",
"asset_url": "asset://asset-yyy"
}
],
"usable_assets": [
{
"asset_id": "asset-xxx",
"asset_url": "asset://asset-xxx"
},
{
"asset_id": "asset-yyy",
"asset_url": "asset://asset-yyy"
}
],
"failed_assets": []
}
}
}部分失败示例（整单 status 为 failed，但仍有可用素材）：
{
"code": 200,
"data": {
"id": "avatar_xxx",
"status": "failed",
"progress": 100,
"result": {
"assets": [
{
"asset_id": "asset-xxx",
"asset_url": "asset://asset-xxx"
}
],
"usable_assets": [
{
"asset_id": "asset-xxx",
"asset_url": "asset://asset-xxx"
}
],
"failed_assets": [
{
"name": "side",
"reason": "人脸识别失败"
}
]
}
}
}计费
素材入库对用户免费。
错误
| HTTP | code | 触发场景 | 处理 |
|---|---|---|---|
| 400 | invalid_request_error | group 与 group_id 同传或都不传、assets 为空或超过 20 个、asset_type 不在 Image / Video / Audio、url 非法或缺失、name 缺失等参数错误；message 为具体原因 | 按 message 修正请求 |
| 404 | task_not_found | 查询任务时 task_id 不存在或不属于当前账户 | 使用提交响应中的 data.id |
| 404 | group_not_found | group_id 不存在，或不属于当前账户 | 只传本账号历史任务成功创建过的 group_id，或改传 group 新建 |
| 422 | invalid_request_error | 提交时上游同步拒绝（message 为 content moderation rejected）；多数审核结果异步产出，见部分失败语义 | 更换素材 |
| 502 | upstream_error | 入库任务提交失败 | 短暂等待后有限次数重试 |
| 503 | no_available_channel | 当前没有可用渠道 | 指数退避后重试 |
错误体为 {"error":{"code":"...","message":"..."}}，统一格式见错误码。
注意事项
asset://引用 → 素材归属提交它的账号；当前仅供本平台 Seedance 2.0 系列生成使用，不是通用可下载的文件地址。group_id→ 只能传本账号历史任务中成功创建过的素材组 ID；传其他账号的group_id返回 404，不区分"不存在"与"无权限"。- 批量入库任一素材审核失败 → 整单
status为failed；已通过的素材仍在result.usable_assets中，按它判断单个素材是否可用。