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

再利用可能なビデオ参照は、生成リクエストごとにコピーされる使い捨てのURLではなく、ライフサイクルステータスを持つアセットとして管理する方が容易です。これまで画像リンクのスプレッドシートを管理したり、同じ参照ビデオを5回も再アップロードしたり、3つの異なるAPIコールに同じフェイススワップ用URLを再入力したりしたことがあるなら、Seedance materialsが解決しようとしている課題はすでにご理解いただけているはずです。

TokenLabのSeedance materialライブラリは、ビデオチームが生成コール全体で参照を保存、検証、再利用するための組織スコープの方法を提供します。この記事では、materialアセットとは何か、materialグループが個々のアセットとどのように関連しているか、自動準備がどのように機能するか、そして実在人物の検証がワークフローのどこに適合するかを解説します。

重要なポイント

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

Seedance Materialとは

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

これが実用上重要な理由は3つあります。

第一に、繰り返しのアップロードは帯域幅を浪費し、特に大きな参照ビデオの場合、すべてのリクエストのレイテンシを増加させます。

第二に、生のURLは有効期限が切れたり、ローテーションされたり、元のホスティングシステムによって取り消されたりします。TokenLabが管理するmaterialアセットには、そのような脆弱性はありません。

第三に、キャラクターの一貫性やブランドの一貫性を重視したビデオパイプラインを構築するチームにとって最も関連性が高い点ですが、materialを使用することで、生成ロジックを毎回変更することなく、バージョン管理、監査、交換が可能な安定した識別子が得られます。

Materialアセット vs. Materialグループ

このシステムの2つの中心的なオブジェクトはmaterialアセットとmaterialアセットグループであり、APIリファレンスを詳しく読んでいないと混同しやすくなります。

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

materialアセットグループは、group_idで識別されるコンテナです。グループは関連するアセットを整理するものであり、実在人物（liveness_face）のワークフローでは構造的に必須です。このワークフローでは、アセットをアップロードする前にグループレベルでの検証が必要となります。

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

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

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

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

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

aigc_avatar: バーチャルアバターおよび非実在人物の参照

aigc_avatarタイプは、検証済みの実在人物と結びついていない再利用可能な参照を対象としています。イラストキャラクター、合成アバター、様式化されたフィギュア、製品マスコットなどがこれに該当します。これらは検証ステップなしで、materialアセット作成フローを通じて直接作成できます。

架空のキャラクターやブランドアバターを中心にビデオを生成するプロダクトであれば、ほぼ間違いなくこのライブラリタイプが適しています。身元確認の要件がないため、作成パスが単純です。

liveness_face: 実在人物のMaterialグループ

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

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

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

つまり、実在人物のmaterialは本質的に「グループ優先」です。aigc_avatarのように直接アセット作成に進むことはできません。グループが存在し、検証を通過してからでなければ、アセットのアップロードは無効です。

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

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

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

自動Material準備の仕組み

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

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

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

これらを生成コールに直接渡すと、TokenLabはmaterialアセットエンドポイントを個別に呼び出すよう要求する代わりに、バックグラウンドでインポートと準備を処理します。

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

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

409 seedance_material_preparing

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

これは従来の意味でのエラーではなく、再試行のシグナルです。統合においては、409 seedance_material_preparingを「しばらくしてから確認する」レスポンスとして扱い、エンドユーザーに表示する失敗とは見なさないでください。返されたアセットIDをポーリングし、ACTIVEステータスになるのを待ってから生成に進んでください。

実用上、これは生成パイプラインに単一のtry/catchではなく、小さな再試行ループが必要であることを意味します。自動化されたビデオパイプラインを構築するチームは、このステータスをレート制限のバックオフと同じように扱うべきです。つまり、予期される一時的な状態であり、ユーザー向けの報告ではなくコード内で処理されるべきものです。

生成でMaterialを使用する方法

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

中心となるワークフローは以下の通りです。

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

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

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

実用的な次のステップ

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

すでに作成したアセットのステータス、ライブラリタイプ、グループ関係を確認するには、Seedance assets dashboardでmaterialライブラリを直接閲覧できます。

プロダクションワークフローを確定する前に、コストが使用量に応じてどのように拡大するかを理解するために、AI video API pricing 2026の概要で現在の料金を確認することをお勧めします。また、TokenLab dashboard usage exportsのガイダンスを使用して、独自の使用データを追跡およびエクスポートすることも可能です。

FAQ

Seedance materialアセットとは何ですか？ materialアセットは、独自のライフサイクルステータスを持つ組織スコープのオブジェクトとして保存される、再利用可能なビデオ生成参照（画像、ビデオ、またはオーディオ）です。ACTIVEに達すると、毎回生のURLを再供給する代わりに、複数の生成コール全体でIDによって参照できます。

group_idとmaterial_asset_idの違いは何ですか？ group_idはmaterialアセットグループを識別します。これは主に実在人物（liveness_face）のアセットを整理し、グループレベルで検証を管理するために使用されるコンテナです。material_asset_idは単一の再利用可能な参照（materialアセット作成時に返されるid）を識別し、ビデオ生成コールに渡すものです。

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

seedance_material_preparingとはどういう意味ですか？ これは、生成リクエスト内のimage_urlやstart_imageなどの互換性のある画像フィールドによってトリガーされる自動material準備が、完了までに60秒以上かかる場合に返される409レスポンスです。レスポンスにはauto_material_asset_idsが含まれているため、それらのIDをポーリングし、ACTIVEになったら生成を再試行できます。これは一時的な進行状態を示すものであり、失敗ではありません。

ソースと鮮度

• Seedance 2.0 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 — https://tokenlab.sh/en/dashboard/seedance-assets — 2026-07-09確認

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

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