API 文件 · 素材

素材類型與真人認證

trust_class、虛擬人物與真人照片的刷臉認證。

建立素材時以 trust_class 宣告素材類型。平台不會自動辨識人像，以你的宣告為準；建立後無法修改，宣告錯誤請刪除後重新上傳。

trust_class	用於	使用條件
`normal`	一般圖片、影片、音訊（預設）	入庫後即可使用
`virtual_avatar`	AI 生成或卡通形象等虛擬人物，用於保持角色一致	入庫後即可使用；首次用於任務時平台會把素材同步到處理通道的素材庫（任務狀態 preparing），只會分配到支援素材庫的線路
`real_person`	真人照片（僅支援圖片）	入庫後為 authorization_required，素材中的本人完成真人認證後才能使用

真人認證流程

呼叫 POST /v1/assets/{id}/portrait-authorizations，傳入 { "model": "…" }（要使用這個素材的模型）。回傳 201 與認證物件：status 為 pending，帶有 h5_link 與 expires_at（30 分鐘後）。
把 h5_link 交給素材中的本人（例如產生 QR 碼），本人用手機開啟並依提示完成刷臉。完成後頁面會跳到本站的提示頁，回到你的應用等待結果即可。
以 GET /v1/portrait-authorizations/{id} 查詢，建議每 5 秒左右一次，直到 status 變為 verified、failed 或 expired。平台也會在背景定時查詢，不查詢也會更新。
verified 後素材變為 available，可以在該模型的任務中使用。

也可以在主控台 · 素材開啟素材詳情直接發起，頁面會顯示 QR 碼並自動更新結果。GET /v1/assets/{id}/portrait-authorizations 列出該素材最近的認證紀錄。

認證狀態

status	含義
`pending`	等待本人完成刷臉；h5_link 只在此狀態回傳
`verified`	認證通過，verified_at 為通過時間
`failed`	認證未通過，error 說明原因；可以重新發起
`expired`	30 分鐘內未完成；可以重新發起

認證依模型生效

認證只對發起時選擇的模型有效。以這個素材送出其他模型的任務時回傳 422 authorization_required，請為該模型再發起一次認證。同一素材在同一模型上已認證過時，再次發起會直接回傳既有的 verified 紀錄。

錯誤

HTTP	code	情境
422	`invalid_parameter`	素材不是 real_person、不是圖片，或 model 不存在
403	`permission_denied`	帳號未開通該模型
404	`not_found`	素材或認證紀錄不存在，或不屬於你
503	`no_available_channel`	該模型暫時沒有可用的真人認證通道，請稍後重試

素材中的人必須是完成刷臉的本人

上游會比對素材與刷臉的人臉，比對不通過時素材無法用於生成，使用它的任務會以 asset_rejected 失敗。

# 發起真人認證：回傳 h5_link，30 分鐘內有效
curl https://api.aitoken.tools/v1/assets/asset_xxx/portrait-authorizations \
  -H "Authorization: Bearer $AITOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"seedance-2.0-standard"}'

# 把 h5_link 傳給素材中的本人刷臉，然後查詢結果，直到 status 為 verified / failed / expired
curl https://api.aitoken.tools/v1/portrait-authorizations/auth_xxx \
  -H "Authorization: Bearer $AITOKEN_API_KEY"