建认证会话 ──awaiting_auth──▶ 刷脸 ──回查(resolve)──▶ active ──上传真人素材──▶ approved ──qasset:// 引用──▶ Seedance 视频生成

① 您 POST /v1/asset-groups {type:liveness_face, model, callback_url}
   → 平台返回 qgroupid，状态 pending

② 平台后台向供应商建认证会话，拿到 h5_link + byted_token
   → 组状态推进到 awaiting_auth

③ 您轮询 GET /v1/asset-groups/:qgroupid，状态变 awaiting_auth 后拿到 h5_link
   → 引导用户打开 h5_link 刷脸（⚠️ 链接约 120 秒有效，需尽快打开）

④ 用户刷脸完成 → 浏览器跳转回【您的 callback_url】，拼接 ?bytedToken=...&resultCode=10000&...
   → 您的服务器收到回调，确认 resultCode==10000（刷脸成功）

⑤ 您 POST /v1/asset-groups/:qgroupid/visual-validate-result {result_code:"10000"}
   → 平台凭一次性 byted_token 向供应商换取真人组（resolve），仅调一次
   → 组状态 awaiting_auth → active（成功）/ failed（失败）

之后：上传真人素材 → 审核 → 视频引用（与虚拟人一致）

{
  "qgroupid": "qgroup-uid001-1716100000000000000",
  "type": "liveness_face",
  "name": "代言人形象",
  "description": "用于品牌视频的真人形象",
  "model": "bytedance/doubao-seedance-2-0-260128",
  "status": "pending",
  "is_default": false,
  "created_at": 1716100000,
  "updated_at": 1716100000
}

{
  "qgroupid": "qgroup-uid001-1716100000000000000",
  "type": "liveness_face",
  "status": "awaiting_auth",
  "h5_link": "https://h5-v2.kych5.com?accessKeyId=...&bytedToken=...&lng=zh",
  "byted_token": "202603311449168C23BA26...",
  "model": "bytedance/doubao-seedance-2-0-260128",
  "created_at": 1716100000,
  "updated_at": 1716100020
}

https://your-domain.com/liveness/callback?bytedToken=202603311449168C23BA26...&resultCode=10000&...

{ "status": "awaiting_auth" }

                   ┌──────────────────┐
                   │     pending      │  ← 建组成功，平台后台建认证会话中
                   └────────┬─────────┘
                            │  会话建成、下发 h5_link
                            ▼
                   ┌──────────────────┐
                   │   awaiting_auth  │  ← 等用户刷脸 + 触发回查（带 h5_link/byted_token）
                   └────────┬─────────┘
                            │  visual-validate-result 触发回查
              ┌─────────────┴─────────────┐
              ▼                           ▼
     ┌──────────────────┐        ┌──────────────────┐
     │      active      │        │      failed      │
     │  ✅ 可上传真人素材 │        │  ❌ 终态不可恢复   │
     └──────────────────┘        └──────────────────┘
                                  fail_reason 字段含具体原因

{
  "qassetid": "qasset-uid001-1716100100000000000",
  "type": "image",
  "name": "代言人正脸",
  "status": "pending",
  "group_id": "qgroup-uid001-1716100000000000000",
  "created_at": 1716100100,
  "updated_at": 1716100100
}

{
  "qassetid": "qasset-uid001-1716100100000000000",
  "type": "image",
  "name": "代言人正脸",
  "model": "bytedance/doubao-seedance-2-0-260128",
  "status": "approved",
  "group_id": "qgroup-uid001-1716100000000000000",
  "created_at": 1716100100,
  "updated_at": 1716100250
}

{
  "qassetid": "qasset-uid001-1716100100000000000",
  "status": "failed",
  "group_id": "qgroup-uid001-1716100000000000000",
  "fail_reason": "face mismatch: not the same person",
  "created_at": 1716100100,
  "updated_at": 1716100250
}

{
  "error": {
    "type": "invalid_request_error",
    "message": "callback_url is required for liveness_face group"
  }
}