APIMaster.ai

本人認證與人像素材入庫

SD2.0、Fast、Mini 與 SD2.5 共用的 APIMaster 認證、素材及生成流程。

本人認證與人像素材入庫

一般圖片、影片及音訊使用統一素材庫。建立素材組只傳模型及名稱,不傳 channel_id 或 purpose;後台按目標模型管理審核與素材副本。

重要提示:明星與一般素人使用不同介面

只有明星才需要使用真人介面,發起本人活體認證:POST /v1/seedance2/private-avatar/verifications。

一般素人直接使用素材介面提交素材審核:POST /v1/seedance2/private-avatar/assets,不要使用真人介面,也不要建立本人活體認證工作階段。素材達到 Active 後即可引用。

四個模型共用 APIMaster 介面。上游路徑、憑證、素材 ID 及審核狀態由後台適配。官方本人認證、渠道人像素材審核、普通或虛擬素材審核是不同流程。僅提交本人明確授權的照片。

1. 能力與適用範圍

僅在使用獨立的官方 H5 本人認證流程時,查詢能力並使用支援 official_h5 的 channel_id。一般素材提交至統一素材庫,不需要選擇渠道。

model duration Image Video Audio
seedance-2.0 4–15 s ≤9 ≤3 / ≤15 s ≤3 / ≤15 s
seedance-2.0-fast 4–15 s ≤9 ≤3 / ≤15 s ≤3 / ≤15 s
seedance-2.0-mini 4–15 s ≤9 ≤3 / ≤15 s ≤3 / ≤15 s
seedance-2.5 4–30 s / -1 ≤30 ≤10 / ≤30 s ≤10 / ≤30 s

統一素材審核:建立、儲存與重複使用

一般圖片、影片及音訊使用統一素材庫。建立素材組只傳模型及名稱,不傳 channel_id 或 purpose;後台按目標模型管理審核與素材副本。

export APIMASTER_KEY='<your APIMaster key>'
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/groups' \
  -H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
  -d '{"model":"seedance-2.5","name":"My materials"}'

asset_type: Image / Video / Audio.

curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/assets' \
  -H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unified-audio-001' \
  -d '{"model":"seedance-2.5","group_id":"group_PUBLIC_ID","asset_type":"Audio","assets":[{"url":"https://your-storage.example/audio.mp3","name":"Reference audio"}]}'

儲存建組回傳的 data.id(提交時作為 group_id)、asset_id 及 asset_url(asset:// 引用)。主動提交素材審核,查詢任務、available_models 及 model_readiness,確認目標模型就緒再生成。同一素材 ID 可供日後使用;刪除、到期或補建副本時仍須確認素材及原檔可存取。官方 H5 本人認證是獨立流程,不是一般素材送審的前置步驟。

3. 本人手機認證

本節僅適用於明星。一般素人請跳過本人活體認證,直接進入素材提交審核流程。

official_h5 流程建立會話後,由本人在手機開啟 h5_link。APIMaster 託管 HTTPS 回呼,客戶不需自建回呼伺服器;不要傳 callback_url。長期金鑰與 BytedToken 僅在服務端管理。不能只憑瀏覽器結果確認成功,必須由服務端向上游查詢;重複回呼不重複建立資源。

export APIMASTER_KEY='<your APIMaster key>'
export APIMASTER_CHANNEL_ID='<available channel ID from the capability API>'
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/capabilities?model=seedance-2.5' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/verifications' \
 -H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
 -H 'Idempotency-Key: portrait-session-001' \
 -d "{\"model\":\"seedance-2.5\",\"channel_id\":${APIMASTER_CHANNEL_ID},\"name\":\"My portrait\"}"

4. 確認認證結果

completed 後取得公開 group_id。下列狀態及期限與人像使用授權期限不同。暫時網路錯誤保留原狀態,不自動建立新會話。控制台入口為 /console/seedance-materials。會話、組、素材及影片任務 ID 必須分開。

curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/verifications/verification_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
API fields / values
capabilities model, channel_id, method, configured, reason, hosted_callback, real_person_verified
verification session_id (id), method, status, h5_link (verification_url), created_at, expires_at, group_id
verification.status creating, pending, completed, failed, expired, failed_unconfirmed, submission_unknown
Idempotency-Key 8–128; same request → original receipt; changed request → 409
verification rate ≤3 / user / minute; upstream limits also apply
H5 / BytedToken single-use H5; query credential ≤30 min; expires_at ≠ portrait authorization expiry

5. 上傳及查詢素材

一般素人使用本節的素材提交介面即可,不需要先呼叫真人認證介面。

POST /uploads 僅託管原件;POST /assets 主動提交素材審核。一般素材組為 unified_virtual。目標模型就緒後才可生成;官方 real_person 組的新照片仍須同人審核。部分成功保留已通過素材。提交未確認時保留原任務及素材 ID,先查詢狀態,不要自動重複上傳。

curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/uploads' \
 -H "Authorization: Bearer $APIMASTER_KEY" -F 'file=@authorized-owner.png'
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/assets' \
 -H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
 -H 'Idempotency-Key: portrait-asset-001' \
 -d '{"model":"seedance-2.5","group_id":"group_PUBLIC_ID","asset_type":"Image","assets":[{"url":"<signed upload URL>","name":"Owner"}]}'
curl --fail-with-body 'https://apimaster.ai/v1/tasks/asset_task_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/assets?group_id=group_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/assets/asset_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
API fields / values
uploads JPEG / PNG ≤10 MB; upload_id, url, url_expires_at, delete_after
groups public id; group_type=unified_virtual / real_person
assets public asset_id; status=Pending / Processing / Active / Failed / SubmissionUnknown
review task asset_task_*; GET /v1/tasks/{id}

6. 生成與下載

生成前透過 /v1/videos/quote 查詢報價,報價不是最高收費保證。後台固定素材相容的渠道、帳號與專案,不相容組合明確拒絕。換模型仍按其輸入限制校驗,新增照片仍需審核。成功後查詢費用回執並下載影片。

curl --fail-with-body 'https://apimaster.ai/v1/videos' \
 -H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
 -H 'Idempotency-Key: portrait-video-001' \
 -d '{"model":"seedance-2.5","prompt":"The person smiles naturally","image_urls":["asset://asset_PUBLIC_ID"],"resolution":"480p","duration":4,"generate_audio":false}'
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/video-requests/video_request_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/videos/task_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/videos/task_PUBLIC_ID/billing' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/videos/task_PUBLIC_ID/content' -H "Authorization: Bearer $APIMASTER_KEY" -o owner.mp4
API fields / values
generation Idempotency-Key required; no automatic POST retry
receipt video_request_*; X-Seedance-Request-Id; replay → 202 + original receipt
video task task_*; separate from receipt, verification and asset IDs

7. 隱私與刪除

簽名連結屬敏感資訊,有效期內持有者可下載。不要記錄完整 H5 連結、簽名 URL 或回呼憑證。刪除託管原件不刪除上游資產;素材刪除移除 APIMaster 映射,僅在上游支援時執行上游刪除,不承諾未提供的能力。先刪素材再刪組。已生成影片不會自動消失。不保存生物辨識模板,審核通過不取代使用授權。

API / storage values
signed original URL 1 h
hosted original access ≤24 h; deletion ≤25 h
DELETE /uploads/{upload_id} hosted original
DELETE /assets/{asset_id} APIMaster mapping; upstream deletion if supported
DELETE /groups/{group_id} empty group

8. 費用與錯誤

2026-10-07 核對:官方文件稱本人認證限時免費。會話、審核、上傳、儲存及管理的實際費用依上下文而定,尚未全部核實,不自動購買權益包。影片沿用既有報價、預扣、結算及退款機制,應查看實際費用回執。錯誤區分權限、能力不支援、認證或審核待完成/失敗、素材不相容及上游結果不確定。不同使用者不得查詢或使用彼此資源。

HTTP context
400 input / callback
403 permissions
404 resource
409 pending / failed review / incompatible context
429 rate limit
502 / 503 uncertain upstream result / unavailable

Seedance 冪等提交與異常恢復

統一虛擬素材與自動恢復

新建虛擬組不指定 channel_id,即可透過同一 asset:// ID 引用相容模型。available_models、model_readiness、all_models_ready 表示就緒情況。不同服務須獨立審核;查詢審核任務更新狀態,補齊副本需原件仍可存取。指定渠道、既有素材組及官方 H5 素材保留各自綁定限制。

生成須帶 Idempotency-Key。提交階段僅在明確限流拒絕且無任務 ID 時可能切換服務。已受理任務因明確帳號停用、憑證失效或服務故障終止時,如有相容服務,最多自動恢復一次;沿用公開任務 ID 與凍結用戶費率,不新增生成預扣。繼續查詢原任務及計費回執。

恢復前,目標服務須已有相容且通過審核的副本,或完成獨立素材審核;不得複用其他服務的審核結論或跨帳號複製官方 H5 認證。參數、內容審核、版權錯誤、逾時、斷線及受理不明均不自動恢復。手動重提先查回執,僅 new_submission_safe=true 可使用新鍵。