メディアガイド

Seedance マテリアルと実在人物の検証

Seedance で画像、動画、音声、または検証済み人物を再利用する

Seedance マテリアルを使用すると、生成のたびにインポートすることなく、画像、動画、または音声ファイルを再利用できます。実在の人物を参照する場合は同意と視覚的な検証が必要ですが、仮想の人物、製品、スタイルの場合は不要です。

マテリアルタイプを選択する

再利用したいもの手順
1回限りの画像サポートされている画像フィールドにその URL を送信します。これにより再利用可能なマテリアル ID は作成されません
仮想の人物、製品、スタイルを再利用aigc_avatar グループを作成し、アセットを作成して ACTIVE になるのを待ち、そのアセット ID を使用します
実在の人物を再利用視覚的検証を完了し、GroupId を受け取り、そのグループ内にアセットを作成して ACTIVE になるのを待ち、そのアセット ID を使用します
既存の Volcengine マテリアルクライアントを移行Action リクエストの形状を維持し、Volc 互換マテリアルリファレンスを使用します

グループとマテリアル

項目REST フィールドAction フィールド意味
マテリアルグループgroup_idGroupId関連するマテリアルをまとめて管理します
マテリアルidIdインポートされた 1 つの画像、動画、または音声ファイル。アクティブになった後にこの ID を使用します
仮想アバターグループlibrary_type: "aigc_avatar"GroupType: "AIGC"実在人物の検証は不要です
実在人物グループlibrary_type: "liveness_face"GroupType: "LivenessFace"視覚的検証フローの成功によってのみ作成されます
プロジェクト名project_nameProjectName異なるプロジェクトのマテリアルを分離します。デフォルトは default です

グループ ID とアセット ID は分けて管理してください。グループはアップロードを整理するためのものであり、アセット ID は動画生成で使用される参照先です。パブリック ID は group-20260720123456-vrt01 や asset-20260720123457-def45 のような形式になります。

マテリアルの保持

TokenLab は、アセットまたはそのグループを削除するまで、すべてのマテリアルアセットを保持します。非アクティブであっても自動的にクリーンアップされることはありません。

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

画像 URL と再利用可能なマテリアル

選択したモデルが受け入れる画像フィールドに、パブリックな HTTP(S) URL またはサポートされているデータ URL を送信します。これらの入力は通常のメディアパスに従い、再利用可能なマテリアル ID は自動的に作成されません。

再利用可能なマテリアルの場合は、マテリアル API を通じてアセットを作成し、ACTIVE になるのを待ってから、サポートされているメディアフィールドで material_asset_id、material_asset_ids、または asset://<id> を使用してください。意図した最初のフレーム、最後のフレーム、または参照画像の役割を維持してください。

明示的なマテリアルがまだ準備中の場合、POST /v1/videos/generations は inactive_asset_ids を含む 409 seedance_material_preparing を返します。それらのアセットが ACTIVE になるまでポーリングし、同じマテリアル ID で再試行してください。アセットが FAILED の場合は、error_message を確認し、修正または再インポートしてから再試行してください。失敗したアセットを使用した生成リクエストは、failed_asset_ids を含む 422 seedance_material_failed を返します。

仮想アバターマテリアル

マテリアルアセットグループの作成を使用して aigc_avatar グループを作成します。REST でのアセット作成において、group_id は project_name が default の場合にのみ省略可能です。その場合、TokenLab は組織のデフォルトの仮想アバターグループを使用または作成します。デフォルト以外の project_name およびすべての実在人物アセットには group_id が必須です。

グループ作成後は、以下を使用して管理します:

グループを削除すると、その中に含まれる TokenLab マテリアルも削除され、元に戻すことはできません。

実在人物の検証

実在の人物を Seedance の参照として再利用する前に、製品側で同意を取得し、顔を検証する必要がある場合はこのフローを使用します。

  1. CallbackURL を指定して 視覚的検証セッションの作成 を呼び出します。Result.BytedToken を保存し、検証対象の人物に対して Result.H5Link を開きます。
  2. H5 フローがコールバックにリダイレクトされた後、同じ BytedToken と ProjectName を使用して 視覚的検証結果の取得 をポーリングします。
  3. 返された Result.GroupId を保存します。このステップで TokenLab は LivenessFace グループを作成およびバインドします。
  4. そのグループ ID でアセットを作成し、アセットが ACTIVE になるまでポーリングします。

BytedToken は 30 分間有効です。クライアントは CreateAssetGroup で LivenessFace グループを作成することはできません。これは、未検証のグループが検証済みとして提示されるのを防ぐためです。

作成後すぐに返された H5Link を開いてください。トークンの有効期間内であればいつでも検証ページを初めて開けるというわけではありません。

実在人物グループの場合、アップロードされたデータは検証済みの顔と照合されます。複数の顔が含まれている場合や、顔が一致しない場合はアセットが失敗する可能性があります。最良の結果を得るには、全身の正面参照画像と、顔がはっきりと写った正面のクローズアップ画像をアップロードしてください。

アセットの作成と準備

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

タイプサポートされている入力
画像jpeg, png, webp, bmp, tiff, gif, heic, heif; ≤ 30 MiB; 幅と高さ [300, 6000] px; アスペクト比 [0.4, 2.5]
動画mp4, mov; ≤ 200 MiB
音声aac, wav, mp3; ≤ 15 MiB

これらはファイルインポートの制限です。インポートリクエストが成功しても、メディアや実在人物の検証が通過するとは限りません。ACTIVE になるまで待機してください。アセットが FAILED になった場合は、error_message を使用してソースを修正してから再度インポートしてください。

マテリアルの取り込みは非同期です。status が ACTIVE になるまで マテリアルアセットの取得 をポーリングしてください。HTTP の成功はインポートが受け付けられたことを意味し、アセットの準備が完了したことを意味するものではありません。アセットが FAILED になった場合は、error_message を確認し、ソースを修正して新しいアセットを作成してください。

ソース URL はインポート時にのみ使用されます。TokenLab は独自のアセット ID を返し、アセットまたはそのグループを削除するまで、組織のマテリアルライブラリにアセットを保持します。

動画生成でのアセットの使用

アセットが ACTIVE になった後、動画の作成 を呼び出す際に以下のいずれかの形式を選択します:

  • 汎用的なマテリアル参照には material_asset_id
  • 複数の汎用的な参照には material_asset_ids
  • メディアの役割を明示する必要がある image_url、start_image、end_image、または reference_images には asset://<asset-id>

マテリアル参照は、選択したモデルの Seedance 参照制限にカウントされます。API が Seedance material asset not found or not accessible を返す場合は、その値がグループ ID ではなくアセット ID であること、同じ組織およびプロジェクトに属していること、削除されていないこと、そして ACTIVE であることを確認してください。

REST または Volcengine Action

TokenLab ネイティブの統合では、引き続き snake_case の /v1/videos/assets* REST エンドポイントを使用できます。既存の Volcengine クライアントは、マテリアルアクション (Volc 互換) を使用して PascalCase のボディを保持できます。どちらのインターフェースも、同じ組織およびプロジェクトスコープのマテリアルデータに対して動作します。

REST 例: 仮想アバターアセット

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","project_name":"default"}'

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

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

Action 例: 検証済み実在人物アセット

まず視覚的検証を作成し、完了させます:

curl 'https://api.tokenlab.sh/?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/?Action=GetVisualValidateResult&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"BytedToken":"<BYTED_TOKEN>","ProjectName":"default"}'

次に、返された 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"
  }'

ステータスが Active になるまで GetAsset でポーリングし、返されたアセット ID を動画生成に渡します。10 個の Action 操作、フィルター、ページネーション、レスポンス形状、およびエラーの詳細については、マテリアルアクション (Volc 互換) を参照してください。

このページの内容