TokenLab Seedance Materials：プロダクションワークフロー向け再利用可能なビデオリファレンス

チームで同じフェイススワップ用URLを3つの異なるAPIコールに貼り付けたことがあるなら、なぜSeedanceマテリアルライブラリが存在するのか、すでにご存知でしょう。再利用可能なビデオ参照は、スプレッドシートからコピーした使い捨てのURLとして扱うよりも、ライフサイクルステータスを持つアセットとして扱う方が効率的です。TokenLabはそれらのアセットを組織単位でスコープするため、複数のコール間で参照を保存、検証、再利用できます。私たちはワークフローの形状をテストしました。グループが実在人物のマテリアルを整理し、アセットが実際の参照を保持し、生成コールはステータスが ACTIVE になった後にのみIDを消費します。例えば、かつて画像リンクのスプレッドシートを管理し、同じ参照ビデオを5回も再アップロードしていたチームは、その習慣を1つのマテリアルアセットIDに置き換えることができます。

重要なポイント

• マテリアルアセットは生成準備が整った参照オブジェクトであり、マテリアルグループは関連するアセット（特に実在人物のワークフロー用）を整理するためのコンテナです。
• マテリアルアセットの id を material_asset_id（または material_asset_ids 内）として使用するのは、ステータスが ACTIVE になってからにしてください。
• ライブラリには2つのタイプがあります。バーチャルアバターやその他の非実在人物の再利用可能な参照用の aigc_avatar と、検証が必要な実在人物のマテリアルグループ用の liveness_face です。
• TokenLabは、互換性のある画像入力（image、image_url、image_urls、reference_images、start_image、end_image）を、個別のアップロード手順なしで自動的にマテリアルアセットとして準備できます。
• 準備に60秒以上かかる場合、APIは 409 seedance_material_preparing を返し、併せてポーリングして再試行可能な auto_material_asset_ids を提供します。
• Seedanceは、このマテリアルシステムがサポートする現在のパブリックモデルファミリーです。特定のティアへの依存関係を構築する前に、ドキュメントでモデルごとの正確な機能詳細を確認してください。

Seedanceマテリアルライブラリ：アセットとグループ

Seedanceマテリアルは、TokenLabがリクエスト単位のURLではなく、組織単位のアセットとして保存する再利用可能な参照（画像、ビデオ、またはオーディオ）です。生のファイルリンクをすべての create-video コールに渡す代わりに、参照を一度アップロードまたはインポートし、生成準備が整うのを待ってから、必要な回数だけIDで参照します。

これが重要な理由は3つあります。第一に、繰り返しのアップロードは帯域幅を浪費し、特に大きな参照ビデオではすべてのリクエストのレイテンシを増加させます。第二に、生のURLは期限切れになったり、ローテーションされたり、元のホスティングストレージシステムによって取り消されたりします。TokenLabが管理するマテリアルアセットには、そのような脆弱性はありません。第三に、キャラクターの一貫性やブランドの一貫性を保つビデオパイプラインを構築するチームにとって最も重要な点ですが、マテリアルはバージョン管理、監査、交換が可能な安定した識別子を提供し、そのたびに生成ロジックを修正する必要がなくなります。

マテリアルアセットとマテリアルグループ

このシステムの2つのコアオブジェクトは、マテリアルアセットとマテリアルアセットグループです。APIリファレンスを注意深く読んでいないと、混同しやすい部分です。

マテリアルアセットは、単一の参照オブジェクト（1つのアバター画像、1つの生存確認済み顔、1つの参照ビデオクリップ）です。作成すると、APIは id を返します。その id は、アセットが ACTIVE ステータスになった後にビデオ生成コールに渡すものです。

マテリアルアセットグループは、group_id で識別されるコンテナです。グループは関連するアセットをまとめます。これらは実在人物（liveness_face）ワークフローにおいて構造的に必須であり、グループ内の個々のアセットをアップロードする前に、グループレベルで検証が行われます。

要するに、group_id は「整理」し、material_asset_id は「生成」します。APIの異なる場所で両方のフィールドを目にすることになります。このシステムでチームが最もよく犯す統合ミスは、これらを間違った場所で使用することです。

フィールド	識別するもの	使用場所
group_id	マテリアルアセットグループ（コンテナ）	グループの作成または参照（特に実在人物の検証フロー）
id (マテリアルアセット上の)	単一の再利用可能な参照	ACTIVE になると material_asset_id になる
material_asset_id	単一のアセット参照	1つの参照スロットのために create-video に渡される
material_asset_ids	アセット参照の配列	複数の再利用可能な参照が必要な場合に create-video に渡される

完全なフィールド定義と必須パラメータは、create material asset および create material asset group のAPIリファレンスに記載されています。プロダクションコードに組み込む前に必ずお読みください。ドキュメントはワークフローの形状をカバーしており、すべてのリクエストパラメータを網羅しているわけではありません。

バーチャルアバターと実在人物のワークフロー

Seedanceマテリアルは2つのライブラリタイプをサポートしています。この区別は単なる見かけ上の違いではなく、2つの異なる安全性と同意の姿勢を反映しています。

aigc_avatar：バーチャルアバターと非実在人物の参照

aigc_avatar タイプは、検証済みの実在人物に紐付かない再利用可能な参照（イラストキャラクター、合成アバター、様式化されたフィギュア、製品マスコット、類似のアセット）をカバーします。これらは検証ステップなしで、マテリアルアセット作成フローを通じて直接作成できます。

製品が架空のキャラクターやブランドアバターを中心にビデオを生成する場合、ほぼ間違いなくこのライブラリタイプが適しています。身元確認の要件がないため、作成パスがよりシンプルです。

liveness_face：実在人物のマテリアルグループ

liveness_face タイプは、実在人物の肖像を中心に構築されたマテリアルグループ用です。これは、実際の個人をフィーチャーした顔の一貫性のあるビデオ生成に使用される種類の参照です。これには身元と同意が関わるため、TokenLabはグループにアセットをアップロードする前に検証フローを要求します。

検証シーケンスにはいくつかの明確なステップがあります：

1. セッション作成 — バックエンドがグループの検証セッションをリクエストします。
2. H5フロー — 検証対象者がホストされたWebフローを通じて生存確認（Liveness check）を完了します。H5はモバイルWeb検証インターフェースを指します。
3. コールバック — 検証セッションが終了すると、TokenLabがシステムに通知します。
4. 結果のバインド — 検証済みの身元がマテリアルグループにバインドされます。
5. グループスコープのアップロード — バインドが成功した後にのみ、その特定のグループにマテリアルアセットをアップロードできます。

つまり、実在人物のマテリアルは本質的に「グループ優先」です。aigc_avatar のように直接アセット作成にスキップすることはできません。グループが存在し、検証に合格してからでないと、アセットのアップロードは有効になりません。

チェックリスト：適切なライブラリタイプの選択

• 参照は実在する識別可能な人物の顔や肖像ですか？ → liveness_face を使用し、検証フローを計画してください。
• 参照は合成、イラスト、または非実在人物のアバターですか？ → aigc_avatar を使用し、検証をスキップしてください。
• 製品は同じ実在人物に対して複数の生成で一貫した身元を必要としますか？ → グループを一度構築し、一度検証し、将来のアセットのためにグループを再利用してください。
• 顧客から提供された参照がどちらのタイプに該当するか不明ですか？ → 確認できるまでは liveness_face として扱い、ドキュメントで確認してください。推測は禁物です。

すべての生成モデルやリクエストタイプが両方のライブラリタイプを同一にサポートしているとは限りません。アーキテクチャを決定する前に、Seedance Video Models guide で現在のサポート状況を確認してください。

自動マテリアル準備の仕組み

すべての参照に手動アップロードステップが必要なわけではありません。TokenLabは、生成リクエストの一部として、互換性のある画像入力を自動的にマテリアルアセットとして準備できます。これにより、単純なケースでの往復が不要になります。

自動準備で認識されるフィールドは以下の通りです：

• image
• image_url
• image_urls
• reference_images
• start_image
• end_image

これらを生成コールに直接渡すと、TokenLabがバックグラウンドでインポートと準備を処理します。最初にマテリアルアセットエンドポイントを個別に呼び出す必要はありません。

準備に60秒以上かかる場合

準備は通常高速です。より大きく複雑な参照画像は、生成準備が整ったアセットに処理されるまでに時間がかかる場合があります。準備が60秒を超えると、APIは以下を返します：

409 seedance_material_preparing

これには、まだ準備中のアセットIDを含む auto_material_asset_ids フィールドが付属しています。

これは従来の意味でのエラーではありません。再試行のシグナルです。統合においては、409 seedance_material_preparing をユーザーに見せるべき失敗ではなく、「後でもう一度確認する」ためのレスポンスとして扱う必要があります。返されたアセットIDをポーリングし、ACTIVE ステータスになるのを待ってから、それらのIDを使用して生成を進めてください。

私たちのパイプラインでは、このステータスをレート制限のバックオフのように扱っています。つまり、想定内の一時的な状態であり、ユーザー向けの報告ではなくコード内で処理します。単なるtry/catchではなく、小さな再試行ループを推奨します。

生成におけるSeedanceマテリアルライブラリの使用

マテリアルアセット（手動アップロードか自動準備かを問わず）が ACTIVE ステータスに達すると、その id は create video コールにおいて material_asset_id として、または material_asset_ids のエントリとして使用可能になります。

コアワークフローは以下のようになります：

1. 参照が実在人物かどうかを決定します。それに応じて liveness_face（検証あり）または aigc_avatar を選択します。
2. 実在人物の場合：マテリアルグループを作成し、検証セッションとH5フローを実行し、コールバックを受け取り、結果をバインドします。
3. マテリアルアセットを作成またはインポートします。直接アップロードコールを行うか、生成リクエスト内の互換性のある画像フィールドで自動準備を処理させます。
4. ステータスを確認します。ACTIVE と報告されるまで、アセットIDを生成に渡さないでください。
5. 409 seedance_material_preparing を受け取った場合は、返された auto_material_asset_ids をポーリングし、ACTIVE に解決されたら再試行します。
6. create-video コールで id を material_asset_id として、または material_asset_ids 内で使用し、レイテンシと品質のニーズに応じて現在のSeedanceモデルをターゲットにします。
7. 参照を再アップロードする代わりに、将来の生成コール全体で同じアセットIDを再利用します。

これはタスク管理が重要になる場面でもあります。再利用されたマテリアルアセットに基づいて構築された生成コールは、途中で停止する必要があるかもしれません。これはコスト管理、クリエイティブブリーフの変更、または悪いプロンプトなどが原因で発生する可能性があります。キャンセルが実行中のビデオジョブとどのように相互作用するかについては、Seedance task cancellation に関する記事を参照してください。

TokenLabで現在利用可能なビデオ生成モデルのより広範な比較については、ビデオモデルカテゴリページで現在のオプションを並べて確認できます。

実践的な次のステップ

• プロトタイピングを行う場合は、aigc_avatar マテリアルから始めてください。作成パスがよりシンプルであり、最初に構築すべき検証依存関係がありません。
• 製品が実在人物の一貫性を必要とする場合は、検証フロー（セッション → H5 → コールバック → バインド）をオンボーディングの第一級の要素として構築してください。
• 本番環境にリリースする前に、409 seedance_material_preparing に対する再試行ループを追加してください。これをエッジケースではなく、想定される動作として扱ってください。
• マテリアルアセットIDを独自の内部参照レコードと一緒に保存してください。そうすれば、どのアセットがどのキャラクターや製品にマッピングされているかを再導出する必要がなくなります。
• マテリアルアセットおよびマテリアルアセットグループのAPIリファレンスを直接確認してください。ドキュメントはワークフローの形状を説明しており、正確なリクエスト/レスポンスフィールドは、統合コードを書く前に現在のドキュメントと照らし合わせて確認する必要があります。

Seedanceアセットダッシュボードでは、すでに作成したアセットのステータス、ライブラリタイプ、グループ関係を確認できます。

AIビデオAPI価格2026の概要にある現在の料金は、コストが使用量に応じてどのようにスケールするかを理解するのに役立ちます。TokenLabダッシュボードの使用量エクスポートのガイダンスを使用して、独自の使用データを追跡およびエクスポートすることもできます。

FAQ

マテリアルアセットとマテリアルグループの違いは何ですか？

マテリアルアセットは、単一の再利用可能な参照オブジェクト（1つのアバター画像、1つの生存確認済み顔、1つの参照ビデオクリップ）です。その id は ACTIVE になると material_asset_id になります。マテリアルグループは group_id で識別されるコンテナです。グループは関連するアセットを整理し、liveness_face ワークフローに必須です。要するに、group_id は整理し、material_asset_id は生成します。

なぜ生成コールが 409 seedance_material_preparing を返すのですか？

image_url や start_image などの互換性のある画像フィールドによってトリガーされる自動マテリアル準備には、60秒以上かかる場合があります。その場合、APIは auto_material_asset_ids を伴う 409 seedance_material_preparing を返します。それらのIDをポーリングし、ACTIVE になるのを待ってから生成を再試行してください。これは失敗ではなく、一時的な進行中の状態を示しています。

実在人物の参照には常に検証が必要ですか？

はい。参照に実際の識別可能な人物の顔や肖像が含まれる場合は、常に liveness_face タイプとその検証フローを使用してください。このフローでは、グループにアセットをアップロードする前に、セッション作成、H5生存確認、コールバック、バインドステップが必要です。イラストや合成アバターなどの非実在人物の参照は aigc_avatar を使用し、このパスは不要です。

1つのマテリアルアセットを複数のSeedanceビデオジョブで再利用できますか？

はい、アセットが ACTIVE になれば可能です。その id を create-video コールで material_asset_id として、または material_asset_ids 内で使用してください。参照を再アップロードする代わりに、将来の生成コール全体で同じアセットIDを再利用します。実行中のジョブを停止する必要がある場合は、Seedance task cancellation を参照してください。

ソースと鮮度

• Seedance Video Models guide — https://docs.tokenlab.sh/guides/seedance-2-video — 2026-07-09に確認
• Create Seedance material asset (API reference) — https://docs.tokenlab.sh/api-reference/video/create-material-asset — 2026-07-09に確認
• Create Seedance material asset group (API reference) — https://docs.tokenlab.sh/api-reference/video/create-material-asset-group — 2026-07-09に確認
• Create video (API reference) — https://docs.tokenlab.sh/api-reference/video/create-video — 2026-07-09に確認
• TokenLab Seedance assets dashboard — /dashboard/seedance-assets — 2026-07-09に確認

ここで説明されているAPIの動作、フィールド名、ステータスのセマンティクスは、確認日時点のパブリックドキュメントおよびダッシュボードのコピーを反映しています。TokenLabのSeedanceマテリアルシステムは活発に開発中です。本番統合コードを確定する前に、リンク先のドキュメントで現在のパラメータ名、ステータス値、モデル固有のサポートを確認してください。

安定した再利用可能な参照に依存するビデオパイプラインを構築している場合は、Seedance Video Models guide から始めてください。現在のパラメータ名を確認し、ターゲットモデルティアが実際に何をサポートしているかを確認する最も速い方法です。