Seedance 素材と実在人物の認証

Seedance 素材は、組織内で再利用できる画像、ビデオ、音声の参照です。まずワークフローを選んでください。通常のアバター素材と認証済み実在人物素材では作成経路が異なります。

素材ワークフローを選ぶCopy Anchor Link

素材の概念Copy Anchor Link

Seedanceの素材は、ビデオ生成時に後から選択できる、組織スコープの再利用可能なリファレンスです。

group_id と素材アセットの id は分けて管理してください。group_id はアップロードの整理用であり、素材アセットの id はビデオ生成用です。ビデオのリクエストで Seedance material asset not found or not accessible が返された場合は、group_id ではなく素材アセットの id を渡しているか、そのアセットが同じ組織に属しているか、削除されていないか、および status: "ACTIVE" であるかを確認してください。

素材の有効期限Copy Anchor Link

TokenLab は、素材アセットまたはそのグループを削除するまで、すべての素材アセットを保持します。TokenLab 側で非アクティブを理由に削除することはありません。

上流の Seedance プロバイダーは、30 日間使用されなかったアセットの作業用コピーを削除することがあります。これによりアセットが削除されたり ID が変わったりすることはありません。次に生成リクエストで使用すると、TokenLab が保存済みの元ファイルから新しい上流コピーを自動的に作成します。

• クリーンアップ後の最初の生成は、新しいコピーを準備する間、少し時間がかかることがあります。まだ準備できていない場合、リクエストは seedance_material_preparing を返します。しばらくしてから再試行してください。
• アセットまたはグループの削除は完全で、元に戻せません。

画像 URL と再利用可能な素材Copy Anchor Link

選択したモデルが対応する画像フィールドに公開 HTTP(S) URL または対応する data URL を指定できます。通常のメディア入力として処理され、再利用可能な素材 ID は自動作成されません。

再利用する場合は素材 API でアセットを作成し、ACTIVE を待ってから material_asset_id、material_asset_ids、または対応するメディアフィールドの asset://<id> を使用します。最初のフレーム、最後のフレーム、参照画像の役割を維持してください。

明示した素材が準備中の場合、POST /v1/videos/generations は 409 seedance_material_preparing と inactive_asset_ids を返します。素材が ACTIVE になるまで確認し、同じ ID で再試行してください。FAILED の場合は error_message に従って修正または再インポートします。

実在人物の素材認証Copy Anchor Link

製品において、実在人物を再利用可能なSeedanceリファレンスとして使用する前に同意と顔認証が必要な場合は、実在人物の素材認証を使用してください。

1. CallbackURL を指定して ビジュアル確認セッションの作成 を呼び出し、返された Result.BytedToken を保存します。
2. 確認対象者に Result.H5Link を開きます。言語を指定する場合は H5 リンクに lng を追加します。
3. H5 フローが完了すると、ブラウザーは bytedToken や resultCode などの公式クエリ名を付けて Result.CallbackURL を開きます。
4. BytedToken で ビジュアル確認結果の取得 をポーリングし、Result.GroupId が返るまで待ちます。
5. GroupId を保存し、liveness_face 素材作成時の group_id として使用します。

BytedToken の有効期間は30分です。両方の Action リクエストで同じ ProjectName を使用してください。認証には Authorization: Bearer <TOKENLAB_API_KEY> を使用し、Volc AK/SK 署名は受け付けません。

作成直後に返された H5Link を開いてください。トークンの有効期間中ならいつでも検証ページを初めて開ける、という意味ではありません。

オプション：テストコンソール を使用して、リクエストとコールバックフローの検証、素材グループの確認、および認証履歴の確認を行ってください。本番環境の統合では、APIを直接呼び出す必要があります。

素材グループの作成Copy Anchor Link

aigc_avatar グループには マテリアルアセットグループの作成 を使用します。新しい実在人物グループは認証フローを通じて作成されるため、認証された人物と素材グループはリンクされた状態になります。

グループ作成後の管理には、マテリアルアセットグループの一覧取得、マテリアルアセットグループの取得、マテリアルアセットグループの更新、および マテリアルアセットグループの削除 を使用します。

素材グループを削除すると、その中のTokenLab素材も削除され、元に戻すことはできません。現在の認証状態で削除が許可されていないためにTokenLab素材ライブラリが削除を完了できない場合、TokenLabは中立的な素材ライブラリエラーを返します。

素材のアップロードCopy Anchor Link

マテリアルアセットの作成 を使用して、公開アクセス可能なソースURLを一度に1つずつインポートします。

aigc_avatar の場合、group_id はオプションです。TokenLabは組織のデフォルトのバーチャルアバターグループを使用または作成します。liveness_face の場合、group_id は必須であり、ビジュアル確認結果の取得 によって返されたグループである必要があります。

表はファイルの取り込み上限です。取り込み要求の成功は、メディアや実在人物の検証成功を保証しません。ACTIVE を待ち、FAILED なら error_message に従って元ファイルを修正してから再取り込みしてください。

素材の取り込みは非同期で行われます。status が ACTIVE になるまで マテリアルアセットの取得 をポーリングしてください。HTTPレスポンスが成功したことは、リクエストが受け付けられたことを意味するだけであり、常にビジネスステータスを確認してください。ステータスが FAILED の場合は、error_message を確認し、ソース素材を修正して新しいアセットを作成してください。

マテリアル作成リクエストでは、asset_url はインポート元だけを表します。TokenLab は素材アセットの id を返します。生成時は元のURLではなく、その id を使用してください。

TokenLab は、素材またはその素材グループを削除するまで、組織の素材ライブラリに素材を保持します。上流のコピーがクリーンアップされた場合は自動的に再作成されます。上記の保持に関するセクションを参照してください。

実在人物の素材グループの場合、1つのグループが1人の実在人物に対応します。アップロードされた素材は、認証された顔と照合されます。複数の顔が含まれているアセットや、認証された人物と一致しない顔が含まれているアセットは失敗する可能性があります。最良の結果を得るには、全身の正面リファレンス画像と、顔がはっきりと写っている正面のクローズアップ画像の両方をアップロードしてください。

ビデオ生成での素材の使用Copy Anchor Link

アセットが ACTIVE になった後、動画を作成 を呼び出す際に、返されたTokenLabアセットの id を material_asset_id として渡すか、material_asset_ids に含めてください。素材アセットはSeedanceのリファレンス制限数にカウントされます。

REST または Volcengine ActionCopy Anchor Link

TokenLab ネイティブ統合では、snake_case の /v1/videos/assets* REST API を引き続き使用できます。既存の Volcengine クライアントは PascalCase 本文を維持し、Volcengine 互換素材 Actionを使用できます。どちらも同じ組織・プロジェクト内の素材データを操作します。

APIの例Copy Anchor Link

バーチャルアバターグループを作成し、画像をアップロードし、アクティブになるまでポーリングしてから、ビデオ生成リクエストで素材アセットIDを使用する例です。

curl https://api.tokenlab.sh/v1/videos/assets/groups \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"library_type":"aigc_avatar","group_name":"Product references"}'

curl https://api.tokenlab.sh/v1/videos/assets \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"library_type":"aigc_avatar","group_id":"group-20260720123456-abc12","asset_url":"https://example.com/reference.png","asset_type":"Image"}'

curl https://api.tokenlab.sh/v1/videos/assets/asset-20260720123457-def45 \
  -H "Authorization: Bearer $TOKENLAB_API_KEY"

実在人物の素材グループでは、素材をアップロードする前にビジュアル確認セッションを作成し、結果を取得します。

curl 'https://api.tokenlab.sh/api/v3?Action=CreateVisualValidateSession&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"CallbackURL":"https://yourapp.example.com/seedance/callback","ProjectName":"default"}'

curl 'https://api.tokenlab.sh/api/v3?Action=GetVisualValidateResult&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"BytedToken":"ZXhhbXBsZS10b2tlbg","ProjectName":"default"}'

実在人物向けの完全な Action フローCopy Anchor Link

認証結果から返された GroupId を CreateAsset に渡します。

curl 'https://api.tokenlab.sh/?Action=CreateAsset&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId":"group-20260720123456-real1",
    "URL":"https://example.com/person-front.png",
    "Name":"Verified front view",
    "AssetType":"Image",
    "ProjectName":"default"
  }'

GetAsset をポーリングし、状態が Active になったら、返された素材 ID をビデオ生成で使用します。