人像库审核概述

概述

人像库自 Seedance 2.0 起配套提供，2.0 及后续版本均须使用。当参考图 / 参考视频 / 首帧等素材中包含人脸时，必须先完成本接口的注册与审核，待 status 为 Active 后，在生视频请求里用 asset://{asset_id} 引用；未审核、未通过，或仍传原始 HTTPS / resolved_url，人脸都无法正确用于视频生成。

不含人脸的纯场景图、产品图，可继续直接传公网 HTTPS URL，不必走人像库。

本平台提供人像库 HTTP REST 接口，完成以下能力：

Base URL

https://api.mapi.zone/v1/portrait/...

接入准备

获取 API Token

在平台控制台创建 API 令牌，记下完整 Key（常见形态：sk-xxxxxxxx）。

请求头

所有接口均需携带：

通用约定

统一响应结构

所有接口返回 HTTP 200，通过 success 字段区分成功 / 失败：

成功：

{
  "success": true,
  "message": "",
  "data": { ... }
}

失败：

{
  "success": false,
  "message": "人类可读的错误说明"
}

HTTP 状态码始终为 200，业务错误通过 success: false + message 体现。401 / 403 由认证中间件在鉴权层返回。

分页参数（列表接口通用）

分页响应结构（data 字段内）：

{
  "page": 1,
  "page_size": 20,
  "total": 55,
  "items": [ ... ]
}

时间格式

created_at、updated_at 为 RFC3339 时间字符串，例如：2026-05-20T18:12:05.09398+08:00

枚举大小写

• asset_type 必须为 Image、Video、Audio（首字母大写）
• group_type 不传时服务端默认 AIGC

接口一览

审核状态说明

状态枚举

终态定义：Active、Failed。处于终态时，单条查询接口不再实时刷新。

状态更新来源

接入建议

1. 创建素材后，用 GET /v1/portrait/assets/{assetId} 轮询（建议间隔 3～10 秒）直到 status 为终态；不要依赖列表接口或后台 5 分钟同步来等待审核。
2. 仅展示列表时，用 GET /v1/portrait/assets 即可。
3. 含人脸素材须确认 status === "Active" 后，再用 asset://{asset_id} 提交生视频。

审核通过后如何引用

生视频请求里，把 asset_id 拼成 asset://{asset_id}，写入 metadata.content[].image_url.url（视频 / 音频同理）：

{
  "type": "image_url",
  "image_url": { "url": "asset://asset-20260520181205-vvds9" },
  "role": "reference_image"
}

提示词指代：content 中第 1 张图 =「图片 1」，第 2 张 =「图片 2」；视频 / 音频同理为「视频 1」「音频 1」。

ID 对照：

推荐调用流程

sequenceDiagram
    participant Client as 接入方
    participant API as 本平台 /v1/portrait

    Client->>API: POST /groups（创建素材组）
    API-->>Client: data.group_id

    Client->>Client: 上传文件到自有 CDN，得到公网 URL

    Client->>API: POST /assets（group_id + url + asset_type）
    API-->>Client: data.asset_id, status=Submitted

    loop 直到终态（Active 或 Failed）
        Client->>API: GET /assets/{assetId}
        API-->>Client: data.status
    end

    Client->>Client: status=Active 后拼 asset://{asset_id}，写入生视频 content

最小可行步骤：

1. POST /v1/portrait/groups → 保存 data.group_id（列表复用时用 remote_group_id）
2. 将素材上传至公网存储 → 得到 https://...
3. POST /v1/portrait/assets → 立刻保存 data.asset_id
4. 循环 GET /v1/portrait/assets/{asset_id} 直至 data.status 为 Active / Failed
5. status = Active 后，用 asset://{asset_id} 写入 metadata.content 发起视频生成

错误排查