素材ワークフローを選ぶ
素材の概念
Seedanceの素材は、ビデオ生成時に後から選択できる、組織スコープの再利用可能なリファレンスです。group_id と素材アセットの id は分けて管理してください。group_id はアップロードの整理用であり、素材アセットの id はビデオ生成用です。ビデオのリクエストで Seedance material asset not found or not accessible が返された場合は、group_id ではなく素材アセットの id を渡しているか、そのアセットが同じ組織に属しているか、削除されていないか、および status: "ACTIVE" であるかを確認してください。
画像素材の自動準備
選択した Seedance モデルが TokenLab 素材ライブラリを使用できる場合、image, image_url, image_urls, reference_images, start_image, end_image に画像 URL または対応するインライン data URL を直接送信できます。TokenLab はそれらを組織のデフォルトのバーチャルアバター素材グループに取り込み、最初のフレーム、最後のフレーム、参照画像としての役割を保持します。
素材が 60 秒以内に ACTIVE になれば、同じリクエストで生成が続行されます。完了しない場合、API は auto_material_asset_ids 付きの 409 seedance_material_preparing を返します。素材が ACTIVE になるまで取得または一覧で確認し、その後 material_asset_id または material_asset_ids で再試行してください。選択したモデルが素材ライブラリを使用できない場合、通常の画像 URL または data URL は通常の画像パスで処理され、明示的な素材 ID は再試行可能な素材可用性エラーで安全に失敗します。既存のバーチャルアバター素材 ID と実在人物素材 ID はそのまま使用され、再インポートされません。
実在人物の素材認証
製品において、実在人物を再利用可能なSeedanceリファレンスとして使用する前に同意と顔認証が必要な場合は、実在人物の素材認証を使用してください。CallbackURLを指定して ビジュアル確認セッションの作成 を呼び出し、返されたResult.BytedTokenを保存します。- 確認対象者に
Result.H5Linkを開きます。言語を指定する場合は H5 リンクにlngを追加します。 - H5 フローが完了すると、ブラウザーは
bytedTokenやresultCodeなどの公式クエリ名を付けてResult.CallbackURLを開きます。 BytedTokenで ビジュアル確認結果の取得 をポーリングし、Result.GroupIdが返るまで待ちます。GroupIdを保存し、liveness_face素材作成時のgroup_idとして使用します。
BytedToken の有効期間は30分です。両方の Action リクエストで同じ ProjectName を使用してください。認証には Authorization: Bearer <TOKENLAB_API_KEY> を使用し、Volc AK/SK 署名は受け付けません。
オプション：テストコンソール を使用して、リクエストとコールバックフローの検証、素材グループの確認、および認証履歴の確認を行ってください。本番環境の統合では、APIを直接呼び出す必要があります。
素材グループの作成
aigc_avatar グループには マテリアルアセットグループの作成 を使用します。新しい実在人物グループは認証フローを通じて作成されるため、認証された人物と素材グループはリンクされた状態になります。
グループ作成後の管理には、マテリアルアセットグループの一覧取得、マテリアルアセットグループの取得、マテリアルアセットグループの更新、および マテリアルアセットグループの削除 を使用します。
素材グループを削除すると、その中のTokenLab素材も削除され、元に戻すことはできません。現在の認証状態で削除が許可されていないためにTokenLab素材ライブラリが削除を完了できない場合、TokenLabは中立的な素材ライブラリエラーを返します。
素材のアップロード
マテリアルアセットの作成 を使用して、公開アクセス可能なソースURLを一度に1つずつインポートします。aigc_avatar の場合、group_id はオプションです。TokenLabは組織のデフォルトのバーチャルアバターグループを使用または作成します。liveness_face の場合、group_id は必須であり、ビジュアル確認結果の取得 によって返されたグループである必要があります。
素材の取り込みは非同期で行われます。
status が ACTIVE になるまで マテリアルアセットの取得 をポーリングしてください。HTTPレスポンスが成功したことは、リクエストが受け付けられたことを意味するだけであり、常にビジネスステータスを確認してください。ステータスが FAILED の場合は、error_message を確認し、ソース素材を修正して新しいアセットを作成してください。
マテリアル作成リクエストでは、asset_url はインポート元だけを表します。TokenLab は素材アセットの id を返します。生成時は元のURLではなく、その id を使用してください。
TokenLab は、素材またはその素材グループを削除するまで、組織の素材ライブラリに素材を保持します。
実在人物の素材グループの場合、1つのグループが1人の実在人物に対応します。アップロードされた素材は、認証された顔と照合されます。複数の顔が含まれているアセットや、認証された人物と一致しない顔が含まれているアセットは失敗する可能性があります。最良の結果を得るには、全身の正面リファレンス画像と、顔がはっきりと写っている正面のクローズアップ画像の両方をアップロードしてください。
ビデオ生成での素材の使用
アセットがACTIVE になった後、動画を作成 を呼び出す際に、返されたTokenLabアセットの id を material_asset_id として渡すか、material_asset_ids に含めてください。素材アセットはSeedanceのリファレンス制限数にカウントされます。
REST または Volcengine Action
TokenLab ネイティブ統合では、snake_case の/v1/videos/assets* REST API を引き続き使用できます。既存の Volcengine クライアントは PascalCase 本文を維持し、Volcengine 互換素材 Actionを使用できます。どちらも同じ組織・プロジェクト内の素材データを操作します。
APIの例
バーチャルアバターグループを作成し、画像をアップロードし、アクティブになるまでポーリングしてから、ビデオ生成リクエストで素材アセットIDを使用する例です。実在人物向けの完全な Action フロー
認証結果から返されたGroupId を CreateAsset に渡します。
GetAsset をポーリングし、状態が Active になったら、返された素材 ID をビデオ生成で使用します。