Skip to main content
実在人物の素材は、本人が確認済みの人物の姿を動画内で参照するために使用します。素材グループの作成、本人による Web ページでの確認、素材の追加、素材が利用可能になるまでの待機、動画生成タスクの送信という順序で進めます。 本ページでは画像素材を例に、AIHubMix API で素材を管理し、新版の /ai/v1/videos を優先して動画を生成します。既存の /v1/videos クライアントについては、互換プロトコルの例を参照してください。

前提条件

  • 有効な AIHubMix API Key を用意し、環境変数 AIHUBMIX_API_KEY から読み取ります。
  • 新版の動画 API を使用する前に、コンソールで非同期タスクを有効にし、アカウントに十分な残高と対象モデルの利用権限があることを確認します。
  • 素材に写る本人が用途に同意し、Web ページでの確認手続きを本人自身で完了する必要があります。同じ素材グループには、同一人物の素材のみを追加します。
  • モデルプロバイダーが読み取れる画像の直接リンクを用意し、素材の処理中もリンクが有効であることを確認します。
  • コマンドラインの例には Bash、curl、jq が必要です。同じターミナルで順番に実行し、返された素材グループ、確認セッション、素材、動画タスクの ID を保持してください。
BytePlus 公式の実在人物の素材ガイドは Seedance 2.0 と Seedance 2.5 を対象としています。本ページの新版動画の主な例では、本番環境での検証が完了した AIHubMix モデル ID doubao-seedance-2-5-260628 を使用します。具体的なバージョン、参照メディアの種類、パラメータは、現在のモデル Schema とアカウントで利用可能な機能を基準にしてください。検証範囲は今回のフロー検証を参照してください。この結果から、すべての Seedance バージョンで実在人物の素材を利用できると判断しないでください。
ターミナル環境を準備します。API Key は実行環境からあらかじめ設定されている必要があります。

  1. 素材グループを作成する

リクエストボディで受け付けるのは name のみです。名前は空にできず、最大 100 文字です。作成に成功すると HTTP 201 が返され、初期ステータスは pending_auth になります。 素材グループの公開フィールドは idobjectnamestatuscreated_atupdated_at です。objectasset_group 固定で、時刻フィールドは Unix 秒です。その後、status=active で素材を追加できる状態になったことを判断します。 作成レスポンスを受け取れなかった場合は、重複して作成することを避けるため、まず一覧を照会してください。
一覧は datahas_morenext_after を返します。次のページでは after=前のページのnext_after を渡します。limit のデフォルトは 20、最大は 100 です。名前は冪等性の識別子として使用されないため、ID と作成時刻を併せて素材グループを識別してください。

  1. 本人確認リンクを取得する

確認セッションを作成します。リクエストボディは不要です。
作成に成功すると HTTP 201 が返されます。公開フィールドは idobjectgroup_idstatuscreated_atexpires_atcompleted_at です。objectverification_session 固定で、時刻フィールドは Unix 秒、未完了時の completed_atnull です。
verification_url は作成成功時のレスポンスでのみ返され、その後の照会ではリンクは再び返されません。速やかに素材に写る本人へリンクを渡し、公開ログ、コードリポジトリ、問い合わせのスクリーンショットには含めないでください。有効期限は expires_at を基準とし、期限切れ後は元のリンクを使用できません。
本人が verification_url を開き、ページに表示される主体と用途を確認し、関連する規約を読んで同意したうえで、ページの案内に従って操作を完了します。BytePlus の公式ガイドでは、この手続きには個人の BytePlus アカウントへのログインが必要とされています。ページでカメラへのアクセス許可を求められた場合は、本人が端末を操作して許可してください。 公式ページには素材のアップロードなどの手順が含まれる場合があります。実際の案内に従って完了してください。その後、本ページの API による素材作成手順も実行し、AIHubMix が返す素材 ID を取得する必要があります。Web ページに表示された別の素材 ID を、そのまま API の例に代入しないでください。

  1. 確認結果を照会する

クライアントは 10 から 15 秒ごとに照会し、ローカルでの待機時間に上限を設定できます。この間隔は利用上の推奨値です。Web ページに完了が表示された場合や空白のページが返された場合も、API でセッションが verified、素材グループが active であることを確認してから素材を追加してください。 再作成時に 409 verification_session_active が返された場合は、まず既存のセッションと素材グループを照会してください。有効なセッションが存在する場合、素材グループの確認が完了している場合、または前回の結果が確認待ちの場合は、繰り返し新規作成しないでください。完了しない状態が続く場合はサポートに連絡してください。
Web ページの internal error は、確認セッションの終了を意味しません。まず本節の 2 つの GET リクエストでセッションと素材グループを照会してください。セッションがまだ pending の場合は、同じグループのセッションを繰り返し作成しないでください。セッションが verified かつ素材グループが active の場合にのみ、素材の追加に進んでください。Web ページのエラーだけでは原因を判断できません。完了しない状態が続く場合は、ID を保持してサポートに連絡してください。

  1. 画像 URL から素材を作成する

画像の準備

画像ファイルを返す絶対 HTTP(S) URL を指定します。HTTPS を推奨します。リンクはログインや追加のリクエストヘッダーなしで読み取れる必要があります。ローカルパス、プライベートネットワークのアドレス、Base64、ユーザー名とパスワードを含む URL は、素材作成 API では使用できません。URL に # フラグメントを含めないでください。 BytePlus の実在人物の素材ガイドでは、鮮明な正面写真が推奨され、素材の登録には以下の要件を満たす必要があります。 上記は公式の素材ライブラリの要件です。動画モデルには参照素材に対する独自の制限がある場合もあります。アップロード前に対象モデルの要件も確認してください。HTTP による作成が成功しても、素材の処理が完了したことを意味しません。

作成リクエスト

IMAGE_URL を、本人から利用への同意を得た画像の直接リンクに変更してください。例のドメインはプレースホルダーであり、実在人物の画像は提供していません。
リクエストボディで受け付けるのは上記の 3 フィールドのみです。Idempotency-Key は任意のリクエストヘッダーで、最大 128 バイトです。先頭と末尾の空白、および制御文字は使用できません。音声と動画のファイル制限は上記の公式ガイドを参照し、対象モデルが対応する種類と長さを確認してください。 初回作成では通常 HTTP 201、既存素材を再利用する場合は 200、結果が確認待ちでステータスが reconciling の場合は 202 が返されます。常にオブジェクトの status を読み取ってください。 素材の公開フィールドは idobjectgroup_idasset_typestatusclient_reference_idcreated_atupdated_atdeleted_at です。objectasset 固定です。未指定または削除済みの client_reference_id は返されず、未削除時の deleted_atnull です。時刻フィールドは Unix 秒です。照会では元の画像 URL は返されないため、アプリケーション側で記録を保持してください。

  1. 素材が利用可能になるまで待つ

10 から 15 秒ごとに照会し、ローカルでの待機時間に上限を設定できます。ローカルのポーリングを停止しても、サーバー側の操作はキャンセルされません。
作成結果が不明で、一致する結果が見つからない状態が続く場合、素材が reconciling のままになることがあり、素材や素材グループの削除にも影響する場合があります。ID と元のリクエスト識別子を保持してサポートに連絡してください。識別子を変更して繰り返し作成したり、一定時間待てば自動的に削除されると想定したりしないでください。

  1. 素材を使用して動画を生成する

動画の参照には、AIHubMix の素材作成レスポンスに含まれる完全な id を使用します。形式は asset://<asset_id> です。同じリクエストで参照するすべての素材は、同一の素材グループに属し、現在のアカウントが所有し、いずれも active である必要があります。素材グループも利用可能な状態を維持している必要があります。 参照の種類は、素材作成時の asset_type と一致する必要があります。asset:// は動画の参照フィールドで使用します。ブラウザーでのダウンロード用アドレスとしては使用できません。

新版の動画プロトコル

まずエンドポイントのパスで現在のモデル Schema を確認します。
モデルが参照画像に対応していることを確認してから送信します。以下では、今回の本番環境での検証に成功した Seedance 2.5 のパラメータ duration=4resolution="480p"aspect_ratio="3:4"generate_audio=false を使用します。新版では input_references[].url を直接使用します。ASSET_ID は、前の手順で AIHubMix が返した素材 ID です。
新版では整数の duration でリクエストする長さを指定します。その他の許容値はモデル Schema を基準にしてください。resolution="480p" はリクエストする解像度の区分であり、出力の幅または高さが 480 ピクセルに固定されることを保証するものではありません。実際の寸法は生成ファイルを基準にしてください。最初と最後のフレームには frame_images[].image_url.url を使用し、併せて frame_type を設定できます。対応する機能をモデルがサポートしている場合にのみ使用してください。パラメータの詳細は動画生成を参照してください。

互換動画プロトコル

既存のクライアントで /v1/videos を使用する場合は、参照を content または extra_body.content に配置し、URL を対応するメディアオブジェクト内にネストします。本例では extra_body.content を使用します。
互換版の例は doubao-seedance-2-0-260128 を維持し、既存の互換 API の仕様と BytePlus 公式の素材参照に関する説明に基づいて記載しています。今回、Seedance 2.0 の動画生成と /v1/videos による互換版の作成は実測していません。新版 Seedance 2.5 の検証結果を、この例にそのまま適用することはできません。
2 種類の例からいずれか一方を選んで実行してください。動画の作成は毎回独立したリクエストです。互換リクエストに input_references を混在させないでください。両方の場所に content を指定すると、extra_body.content がトップレベルの content を上書きします。指定は一方のみにすることを推奨します。 互換版が返す idGET /v1/videos/{id} での照会に使用し、完了後は GET /v1/videos/{id}/content でダウンロードしてください。互換版の ID を /ai/v1/videos の照会に使用しないでください。詳細は互換動画 APIを参照してください。

  1. 新版の動画をポーリングしてダウンロードする

以下の Python の例は、前述の新版の作成手順にのみ続くものです。環境変数の VIDEO_ID を読み取り、タスクは再作成しません。requests のインストールが必要です。
30 分はこの例のローカル待機時間の上限であり、サーバー側タスクのタイムアウトを示すものではありません。照会の HTTP 200 は生成成功を意味しないため、必ず status を確認してください。ポーリングには /ai/v1/videos/{id} を使用します。統一タスク API の /ai/v1/tasks/{id} は、読み取り専用のスナップショットを提供します。 動画の照会とダウンロードには、タスク作成時と同じ API Key を使用します。完了後は速やかにダウンロードし、自分で保存してください。結果には保持期限があり、expires_at を基準にします。期限切れの場合は 410 artifact_expired が返されることがあります。

今回のフロー検証

2026-09-07 の本番環境での検証では、インターネットからアクセス可能な HTTPS の JPEG 直接リンク、本人が完了した Web ページでの確認、および上記の Seedance 2.5 パラメータを使用し、以下の結果を確認しました。 今回のファイルは 1,558,358 バイトでした。ffprobe では H.264、24 fps、560 × 752 ピクセル、4.041667 秒、音声トラックなしと検出されました。これらは今回の生成結果の値であり、毎回のリクエストで同じ寸法、長さ、ファイルサイズが出力されることを示すものではありません。 確認ページを初めて開いた際に internal error が表示され、その後の API 照会でも pending のままでした。ページエラーの原因は未確認です。このテストでは、その後、独立したテストグループの新しいページを使用し、本人による操作の完了後にセッションが verified、素材グループが active であることを確認しました。新しいグループの使用は今回のテストでの対応方法に限られます。素材グループを繰り返し再作成することを一般的に推奨するものではなく、元のセッションが終了したことも意味しません。 今回、Seedance 2.0 の動画生成、互換 API による作成、音声と動画の素材、最初と最後のフレーム、削除、およびその他の異常条件の組み合わせは実測していません。関連する説明は API 仕様と公式資料に基づいて維持しています。今回の検証は、ガイド全体のすべてのシナリオを対象としていません。

冪等な再試行

  • 素材作成がタイムアウトした場合やレスポンスを受け取れなかった場合は、元の Idempotency-Keyclient_reference_id、URL、asset_type を保持し、同じリクエストを再送してください。2 つの識別子のいずれかが、同じアカウント、同じ素材グループの既存素材に一致すると、その素材が再利用されます。
  • 同じ識別子に対応する URL または asset_type が変わると、409 asset_idempotency_conflict が返されます。署名付き画像 URL の更新も URL の変更に該当します。
  • どちらの識別子も指定しない場合、リクエスト間の重複排除は保証されません。別の素材を作成することが確定した場合にのみ、新しい識別子を使用してください。
  • 素材 ID を取得済みの場合は、まず GET /ai/v1/assets/{id} で照会してください。reconciling は失敗を意味しません。新しい識別子に変更して再作成しないでください。
  • 素材の削除が完了すると、元の冪等性識別子は保持されなくなります。その識別子を使って削除済み素材を復元しようとしたり、古い作成リクエストを再送したりしないでください。
  • 本節の冪等性の仕様は素材作成にのみ適用されます。素材グループ、確認セッション、動画の作成には適用できません。新版の動画作成レスポンスを受け取れなかった場合は、重複生成を避けるため、まず GET /ai/v1/videos?limit=20&order=desc で元のタスクを探してください。

素材と素材グループを削除する

削除する前に、互換 API から送信したタスクも含め、その素材を参照するすべての動画が終了していることを確認してください。削除操作は取り消せません。ダウンロード済みの動画ファイルは、自分で管理する必要があります。 単一の素材を削除します。
202 が返された場合は削除処理が継続中です。GET /ai/v1/assets/{id}status=deleted になるまで照会を続けてください。削除を再度リクエストすると現在のステータスが返されます。reconciling の場合は結果の確認を続け、完了しない状態が続く場合はサポートに連絡してください。 素材グループ全体を削除すると、グループ内の素材も同時に削除されます。cascade=true を明示的に渡す必要があります。
受け付けられると 202 が返されます。GET /ai/v1/asset-groups/{id} で照会してください。deleting は処理中、partially_deleted は一部が未削除の状態を示し、deleted で初めて完了となります。デフォルトでは、一覧に削除済みの素材グループは表示されません。 409 asset_group_in_use は、まだ終了していない操作または動画タスクがあることを示します。待機し、関連するステータスを照会してから再試行してください。互換版の動画タスクについては、自分で終了を確認する必要があります。削除リクエストが、すべての互換タスクによる使用状況を自動的に判断すると想定しないでください。

よくある質問

Web ページでの操作を完了しても素材を追加できないのはなぜですか?

まず確認セッションと素材グループを照会し、verifiedactive を基準にしてください。Web ページに internal error が表示された場合も、同じ確認を行います。pending の間は同じグループのセッションを繰り返し作成しないでください。結果が未確認の場合は、しばらくしてから再度照会してください。完了しない状態が続く場合は、ID を添えてサポートに連絡してください。確認リンクや本人の写真を提出する必要はありません。

素材が利用可能でも動画生成に失敗するのはなぜですか?

参照に AIHubMix が返した素材 ID を使用しているか、すべての素材が同じグループに属しているか、メディアの種類が一致しているか、現在のモデルが該当する入力に対応しているかを確認してください。素材の active は素材が利用可能であることを示します。動画タスクの完了ステータスとエラー情報は、別途確認する必要があります。

よくある API エラーにはどう対処しますか?

その他の動画エラーは非同期タスクのエラーコードを参照してください。問い合わせ時には、発生時刻、HTTP ステータス、error.code、返された error.tid(存在する場合)、関連リソースの ID を提供してください。API Key、確認リンク、署名付き画像 URL は提供しないでください。

参考資料

更新日:2026-09-07