人像库审核概述

概述

本平台提供人像库 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 为终态。
2. 仅展示列表时，用 GET /v1/portrait/assets 即可，依赖后台 5 分钟同步。
3. 调用 Seedance 2.0 前确认 status === "Active"，并使用 resolved_url。

推荐调用流程

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=Processing

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

    Client->>Client: status=Active 后，使用 resolved_url 调用 Seedance 2.0

最小可行步骤：

1. POST /v1/portrait/groups → 保存 data.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 后，使用 data.resolved_url 发起视频生成

错误排查