虚拟人像素材入库

虚拟人像素材入库用于为 Seedance 2.0 的"人物一致性"生成能力准备可复用的人像素材：提交图片素材后平台异步审核，审核通过的素材会返回 asset:// 引用，之后可在 Seedance 2.0 生成请求中引用该素材来保持同一人物形象的一致性（生成侧接入即将上线，本页仅覆盖入库与查询）。

仅支持虚拟人像 / AIGC 生成人像素材，不支持真人照片认证。上传真人照片可能审核不通过，或在后续更新中被拒绝入库。

素材入库对用户免费（不计费）。接口采用异步任务模式：先提交入库任务，再轮询查询接口获取审核结果。

鉴权

与其他接口一致，使用平台 API Key：

Header	必填	说明
`Authorization`	是	`Bearer <your-api-key>`
`Content-Type`	是	固定为 `application/json`

提交入库任务

POST /v1/seedance2/private-avatar

请求参数

参数	类型	必填	默认值	说明
`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"
}

cURL 示例

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
  }
}

字段	类型	说明
`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`	string	提交接口返回的 `avatar_...` ID

任务状态机

status	说明
`pending`	排队中，尚未开始审核
`running`	审核中
`succeeded`	全部素材审核通过
`failed`	任务未完全成功；批量提交时任一素材审核失败，整单即判定为 `failed`

批量入库时的部分失败语义：只要提交的 assets 中有一个素材未通过审核，整个任务的 status 就会是 failed，而不是部分成功状态。但这不代表全部素材都不可用——已通过审核的素材仍会出现在 result.usable_assets 中，可以正常拿到 asset:// 引用使用；请按 result.usable_assets 而不是顶层 status 判断单个素材是否可用。

响应示例

{
  "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": "人脸识别失败"
        }
      ]
    }
  }
}

响应字段

字段	类型	说明
`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	审核未通过的素材，含失败原因；任务全部成功时为空数组

pending/running 状态下 result 字段不出现或为空，建议轮询间隔 5-10 秒，直至进入 succeeded 或 failed 终态。

asset:// 的用途

审核通过的素材会拿到形如 asset://asset-xxx 的引用。该引用用于 Seedance 2.0 视频生成时指定人物一致性素材，让多次生成保持同一人物形象（生成侧接入即将上线，届时会在 Seedance 系列文档中说明具体传参方式）。

素材归属提交它的账号，group_id 只能传本账号历史任务中成功创建过的素材组 ID；传其他账号的 group_id 返回 404，不区分"不存在"与"无权限"。
asset:// 引用当前仅供本平台 Seedance 2.0 系列生成使用，不是通用可下载的文件地址。

错误

HTTP 状态码	code	说明
400	`invalid_request_error`	`group` 与 `group_id` 同传、`assets` 超过 20 个、`url` 非法或缺失、`name` 缺失等参数错误
404	`task_not_found`	查询任务时 `task_id` 不存在或不属于当前账户
404	`group_not_found`	`group_id` 不存在，或不属于当前账户
422	`invalid_request_error`	提交时上游同步拒绝（内容审核不通过）；多数审核结果异步产出，见上方部分失败语义
502	`upstream_error`	入库任务提交失败
503	`no_available_channel`	当前没有可用渠道

统一错误体格式见错误码。

虚拟人像素材入库

本页内容