BitCloud 素材库与真人认证 API 接入文档

1. 概述

素材库用于把图片、视频和音频保存为可复用的生成素材。素材准备完成后，可直接在视频生成请求中引用，无需每次重复传入原始文件地址。

使用流程：

1. 选择要用于视频生成的模型。
2. 虚拟人像素材：创建 AIGC 分组后，通过可公开访问的媒体 URL 导入素材。
3. 真人出镜素材：先创建并完成真人认证会话，再从认证结果中取得可用分组。
4. 等待素材状态变为 Active，再在视频请求中使用返回的 asset://ast_...。

真人出镜相关场景可先创建认证会话，再将用户跳转到返回的认证链接完成认证。

选择模型

先调用 GET /v1/models，从返回列表中选择一个用于视频生成的模型 ID。下文的 YOUR_VIDEO_MODEL_ID 是占位符，必须替换为该 API Key 实际可用的模型 ID。

同一套素材建议从创建分组、真人认证、导入、查询到视频生成始终使用同一个 model。这样素材才能在后续视频请求中被正确识别和使用。客户端只需保存本文接口返回的 id 和 uri，无需传递或维护任何额外的路由、账户或服务信息。

模型能力

素材库能力由所选 model 决定；不支持的操作会返回 400 invalid_request。请以接口响应为准，不要假定每个模型都支持所有素材、分组、上传或真人认证操作。

2. 快速开始

bashcurl -X POST "https://edge.bitcloud.com.cn/v1/assets/groups.create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_VIDEO_MODEL_ID",
    "name": "虚拟人物素材",
    "description": "用于视频生成的 AIGC 虚拟人像素材",
    "project_name": "default",
    "group_type": "AIGC"
  }'

响应：

json{
  "object": "asset_operation",
  "operation": "groups.create",
  "data": [
    {
      "id": "ast_6d693e9bc8e047c4af672a95d8992519",
      "type": "group",
      "resource_url": "/v1/assets/ast_6d693e9bc8e047c4af672a95d8992519",
      "name": "虚拟人物素材",
      "status": "Active"
    }
  ]
}

3. 鉴权与端点

除认证页面外，所有素材库请求均需携带 API Key：

httpAuthorization: Bearer YOUR_API_KEY
Content-Type: application/json

认证会话返回 verification_url 后，将待认证用户跳转到该地址即可完成认证。该链接由 BitCloud 生成，并会将浏览器带到认证页面；不要修改此地址中的任何内容。

verification_url 是短期有效的敏感链接（默认 30 分钟）。不要把它写入日志、前端埋点、工单、公开页面或群聊；只应定向交给待认证本人。认证结束后，请继续调用结果接口确认状态。

4. 资源与响应格式

4.1 资源字段

所有资源 ID 均以 ast_ 开头。

素材库操作中使用 id，视频生成中使用 uri：

textgroup_id: ast_6d693e9bc8e047c4af672a95d8992519
素材 URI: asset://ast_6d693e9bc8e047c4af672a95d8992519

请直接保存接口返回的 id 和 uri，不要自行拼接或修改它们。

4.2 POST 响应

所有 POST /v1/assets/:operation 操作返回统一信封：

json{
  "object": "asset_operation",
  "operation": "assets.create",
  "data": [
    {
      "id": "ast_6d693e9bc8e047c4af672a95d8992519",
      "type": "asset",
      "uri": "asset://ast_6d693e9bc8e047c4af672a95d8992519",
      "resource_url": "/v1/assets/ast_6d693e9bc8e047c4af672a95d8992519",
      "name": "人物正面",
      "status": "Processing"
    }
  ]
}

删除成功时 data 为空数组。列表操作的 data 为资源数组。

GET /v1/assets/:resource_id 不使用信封，直接返回一个资源对象。它返回最近一次素材库操作保存的状态；需要刷新处理状态时，请使用 assets.get：

json{
  "id": "ast_6d693e9bc8e047c4af672a95d8992519",
  "type": "asset",
  "uri": "asset://ast_6d693e9bc8e047c4af672a95d8992519",
  "resource_url": "/v1/assets/ast_6d693e9bc8e047c4af672a95d8992519",
  "name": "人物正面",
  "status": "Active"
}

5. 素材分组

本节所有操作均使用 POST /v1/assets/:operation，且必须携带 model。

5.1 创建分组

operation: groups.create

json{
  "model": "YOUR_VIDEO_MODEL_ID",
  "name": "虚拟人物素材",
  "description": "用于视频生成的 AIGC 虚拟人像素材",
  "project_name": "default",
  "group_type": "AIGC"
}

真人出镜不通过 groups.create 创建 Person 分组。请先完成 真人认证，再使用 verification.result.get 返回的分组 ID 创建人物素材。

5.2 查询分组列表

operation: groups.list

json{
  "model": "YOUR_VIDEO_MODEL_ID",
  "page_number": 1,
  "page_size": 20,
  "filter": {
    "name": "品牌",
    "group_type": "AIGC",
    "statuses": ["Active"]
  }
}

page_number、page_size、filter 均为可选字段。

5.3 查询、更新、删除分组

使用 groups.create 或 groups.list 返回的 id。

json// groups.get
{
  "model": "YOUR_VIDEO_MODEL_ID",
  "id": "ast_6d693e9bc8e047c4af672a95d8992519"
}

json// groups.update
{
  "model": "YOUR_VIDEO_MODEL_ID",
  "id": "ast_6d693e9bc8e047c4af672a95d8992519",
  "name": "已审核人物",
  "description": "可用于品牌视频的人物素材"
}

json// groups.delete
{
  "model": "YOUR_VIDEO_MODEL_ID",
  "id": "ast_6d693e9bc8e047c4af672a95d8992519"
}

将注释中的 groups.get、groups.update 或 groups.delete 作为请求路径中的操作名，例如 POST /v1/assets/groups.get。

6. 素材管理

6.1 创建素材

operation: assets.create

url 必须可由 BitCloud 服务读取。创建后的素材通常需要异步处理。

json{
  "model": "YOUR_VIDEO_MODEL_ID",
  "group_id": "ast_6d693e9bc8e047c4af672a95d8992519",
  "url": "https://media.example.com/portrait.png",
  "asset_type": "Image",
  "name": "人物正面",
  "project_name": "default"
}

6.2 查询处理状态

刚创建的素材可能返回 status: "Processing"。使用 assets.get 刷新状态：

json// POST /v1/assets/assets.get
{
  "model": "YOUR_VIDEO_MODEL_ID",
  "id": "ast_6d693e9bc8e047c4af672a95d8992519"
}

仅当素材为 Active 时，才应将它的 asset://ast_... URI 提交给生成接口。

6.3 查询素材列表

operation: assets.list

json{
  "model": "YOUR_VIDEO_MODEL_ID",
  "group_id": "ast_6d693e9bc8e047c4af672a95d8992519",
  "page_number": 1,
  "page_size": 20,
  "filter": {
    "statuses": ["Active"],
    "name": "人物"
  }
}

传入 group_id 可只查询该分组内的素材；不传时查询当前账号可见的素材。

6.4 查询、更新、删除素材

json// assets.get
{
  "model": "YOUR_VIDEO_MODEL_ID",
  "id": "ast_6d693e9bc8e047c4af672a95d8992519"
}

json// assets.update
{
  "model": "YOUR_VIDEO_MODEL_ID",
  "id": "ast_6d693e9bc8e047c4af672a95d8992519",
  "name": "人物正面（已审核）"
}

json// assets.delete
{
  "model": "YOUR_VIDEO_MODEL_ID",
  "id": "ast_6d693e9bc8e047c4af672a95d8992519"
}

分别使用 assets.get、assets.update、assets.delete 作为操作名。删除后，该素材不能再用于后续生成任务。

7. 真人认证

真人认证适用于需要人物出镜的素材流程。

7.1 创建认证会话

operation: verification.sessions.create

json{
  "model": "YOUR_VIDEO_MODEL_ID"
}

响应示例：

json{
  "object": "asset_operation",
  "operation": "verification.sessions.create",
  "data": [
    {
      "id": "ast_39eb1540473642a9b67e2053e89ea254",
      "type": "verification_session",
      "resource_url": "/v1/assets/ast_39eb1540473642a9b67e2053e89ea254",
      "verification_url": "/v1/assets/ast_39eb1540473642a9b67e2053e89ea254/verification?token=..."
    }
  ]
}

在浏览器中打开 verification_url 完成认证。无论模型是否提供完成回调，都必须查询认证状态和结果，不能把浏览器跳转当作认证成功依据。创建会话不需要传入额外参数；如模型支持分组关联或协议确认，按对应操作完成即可。

创建会话只有在 data 中同时返回非空 id 和 verification_url 时才算成功。服务未返回可用会话时，网关返回 502 upstream_asset_response_invalid；客户端不得跳转或继续真人业务，应记录请求 ID 后联系支持人员。

7.2 查询认证会话状态

operation: verification.sessions.get（仅支持该能力的模型可用）

json{
  "model": "YOUR_VIDEO_MODEL_ID",
  "id": "ast_39eb1540473642a9b67e2053e89ea254"
}

返回的认证会话资源会更新 status；处于 Pending、Processing 时继续等待，完成后再查询结果。

7.3 同意真人认证协议

operation: verification.agreements.accept（仅模型要求时调用）

json{
  "model": "YOUR_VIDEO_MODEL_ID"
}

7.4 查询认证结果

使用创建认证会话时返回的 id：

json// verification.result.get
{
  "model": "YOUR_VIDEO_MODEL_ID",
  "id": "ast_39eb1540473642a9b67e2053e89ea254",
  "result_code": "optional-result-code"
}

根据返回的资源状态确认认证进度和结果。认证成功后，响应可能包含 type: "group" 的资源；保存该资源的 id，后续可作为 group_id 创建人物素材。

8. 在视频生成中引用素材

素材状态为 Active 后，在标准视频请求中填入 uri。以下示例将图片素材作为参考图：

json{
  "model": "YOUR_VIDEO_MODEL_ID",
  "prompt": "人物在柔和的棚拍光线中转向镜头",
  "content": [
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "asset://ast_6d693e9bc8e047c4af672a95d8992519"
      }
    }
  ]
}

将该请求提交至 POST /v1/videos 或 POST /v1/video/generations。请确保模型支持所使用的素材类型和输入角色。

完整视频请求格式请参阅 视频生成 API 接入文档。

9. 操作清单

若请求返回客户端错误，请检查 model、素材 ID、分组 ID 和必填字段是否来自同一套流程，不要自行替换或拼接资源 ID。

10. 错误处理

错误使用统一响应格式：

json{
  "error": {
    "message": "asset resource not found",
    "type": "invalid_request_error",
    "code": "asset_resource_not_found"
  }
}

11. 接入建议

• 保存接口返回的 id 和 uri，后续管理使用 id，视频生成使用 uri。
• 创建素材后先查询状态；Processing 和 Failed 的素材不可提交生成。
• 用户需要真人认证时，将浏览器跳转到 verification_url；不要修改、记录或公开该 URL，并在结果接口确认后再放行后续业务。
• 删除素材后不能再将其用于新的视频生成任务。