本人認證與人像素材入庫
SD2.0、Fast、Mini 與 SD2.5 共用的 APIMaster 認證、素材及生成流程。
本人認證與人像素材入庫
四個模型共用 APIMaster 介面。上游路徑、憑證、素材 ID 及審核狀態由後台適配。官方本人認證、渠道人像素材審核、普通或虛擬素材審核是不同流程。僅提交本人明確授權的照片。
1. 能力與適用範圍
使用 APIMaster Key 查詢能力，以返回的 channel_id 綁定上下文。可用性取決於權限、專案與模型路由；不支援時明確拒絕，不自動更換渠道或模型。SD1.0、SD1.5 及自訂別名須另行核對精確協議。
| 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 |
2. 依能力選擇流程
official_h5 需要建立會話並由本人手機認證。channel_material_review 先建立 purpose=channel_portrait 素材組，再提交及查詢素材；owner_verified=false 不代表官方本人認證通過。支援時普通素材使用 purpose=ordinary。virtual_or_ordinary 不支援官方本人認證；unverified 表示能力未核實。省略 purpose 維持既有虛擬組行為，舊組不批次升級為已認證真人組。
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\",\"channel_id\":${APIMASTER_CHANNEL_ID},\"purpose\":\"channel_portrait\",\"name\":\"Authorized portrait materials\"}"
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 是共用素材提交及審核介面。舊 POST /v1/seedance2/private-avatar 是相同處理的相容入口。只有 Active 可生成，Processing、Pending、Failed 均不可用。官方 real_person 組的新照片須同人一致性審核；channel_portrait 是渠道素材審核。部分成功保留已通過素材。逾時後先查詢已受理素材，不自動重複 POST，也不從檔名或任務 ID 推造 asset_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=virtual / ordinary / channel_portrait / real_person |
| assets | public asset_id; status=Pending / Processing / Active / Failed |
| channel_material_review | verification_method, owner_verified=false, material_purpose, review.scope_model |
| 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; hourly cleanup ≤25 h; private files 0600 |
| 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 |