APIMaster.ai

本人認証と人物素材

Seedance の認証、素材管理、生成に共通する APIMaster ガイド。

本人認証と人物素材

通常の画像・動画・音声には統一素材ライブラリを使用します。グループ作成時はモデルと名前だけを指定し、channel_id と purpose は省略します。対象モデルの審査と素材コピーはサーバーが管理します。

重要:著名人と一般の方では利用する API が異なります

本人の生体認証を開始する真人認証 API が必要なのは、著名人のみです:POST /v1/seedance2/private-avatar/verifications。

一般の方は POST /v1/seedance2/private-avatar/assets で素材を直接審査に提出してください。真人認証 API を使用したり、生体認証セッションを作成したりしないでください。素材の状態が Active になれば参照できます。

4モデルは同じ APIMaster API を使用します。上流の API、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"}]}'

返された group_id、asset_id、asset_url(asset:// 参照)を保存します。素材を審査に送信し、タスク、available_models、model_readiness を確認して対象モデルが利用可能になってから生成します。同じ素材 ID を後日再利用できますが、削除・期限切れ・コピー追加時には素材や元ファイルへのアクセスを確認してください。公式 H5 本人認証は別の処理で、通常の素材審査の前提ではありません。

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. 素材のアップロードと審査

一般の方はこの節の素材提出 API のみを使用してください。先に真人認証 API を呼び出す必要はありません。

POST /uploads は元ファイルを保管し、POST /assets は素材を審査に送信します。通常のグループは unified_virtual です。対象モデルが利用可能になってから生成してください。公式 real_person グループの新しい写真は引き続き同一人物の審査が必要です。一部成功時も承認済み素材は保持されます。送信結果が不明な場合は元のタスク ID と素材 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 のない明確なレート制限拒否の場合に限ります。受理後に明確なアカウント無効化、認証情報無効、サービス障害で終了したタスクは、互換サービスが利用可能なら最大 1 回自動復旧できます。公開タスク ID と確定済み利用料金を維持し、生成料金を二重に仮押さえしません。元のタスクと課金明細を照会してください。

復旧先には互換性のある審査済みコピーが必要で、なければ独立した素材審査を完了します。他サービスの審査結果や公式 H5 認証を別アカウントへ転用しません。パラメータ、審査、著作権エラー、タイムアウト、切断、受理不明は対象外です。手動再送前に受付記録を照会し、new_submission_safe=true の場合のみ新しいキーを使ってください。