本人認証と人物素材
Seedance の認証、素材管理、生成に共通する APIMaster ガイド。
本人認証と人物素材
4モデルは同じ APIMaster API を使用します。上流の API、ID、審査状態はバックエンドが対応付けます。公式の本人認証、チャネルの人物素材審査、通常素材・仮想人物の審査は別の処理です。明示的な使用許可のある写真だけを送信してください。
1. 機能と適用範囲
APIMaster キーで機能を照会し、返された 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 を開きます。HTTPS コールバックは APIMaster が管理するため、顧客のサーバーは不要です。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 が共通の素材登録・審査 API で、旧 POST /v1/seedance2/private-avatar は同じ処理の互換入口です。生成に使えるのは Active のみで、Processing、Pending、Failed は使用できません。公式 real_person グループの新しい写真は同一人物審査を受けます。channel_portrait は素材審査です。一部成功では承認済み素材を保持します。タイムアウト後は既存素材を照会し、POST の自動再送や 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 |