メディアガイド
Seedance マテリアルと実在人物の検証
Seedance で画像、動画、音声、または検証済み人物を再利用する
Seedance マテリアルを使用すると、生成のたびにインポートすることなく、画像、動画、または音声ファイルを再利用できます。実在の人物を参照する場合は同意と視覚的な検証が必要ですが、仮想の人物、製品、スタイルの場合は不要です。
マテリアルタイプを選択する
| 再利用したいもの | 手順 |
|---|---|
| 1回限りの画像 | サポートされている画像フィールドにその URL を送信します。これにより再利用可能なマテリアル ID は作成されません |
| 仮想の人物、製品、スタイルを再利用 | aigc_avatar グループを作成し、アセットを作成して ACTIVE になるのを待ち、そのアセット ID を使用します |
| 実在の人物を再利用 | 視覚的検証を完了し、GroupId を受け取り、そのグループ内にアセットを作成して ACTIVE になるのを待ち、そのアセット ID を使用します |
| 既存の Volcengine マテリアルクライアントを移行 | Action リクエストの形状を維持し、Volc 互換マテリアルリファレンスを使用します |
グループとマテリアル
| 項目 | REST フィールド | Action フィールド | 意味 |
|---|---|---|---|
| マテリアルグループ | group_id | GroupId | 関連するマテリアルをまとめて管理します |
| マテリアル | id | Id | インポートされた 1 つの画像、動画、または音声ファイル。アクティブになった後にこの ID を使用します |
| 仮想アバターグループ | library_type: "aigc_avatar" | GroupType: "AIGC" | 実在人物の検証は不要です |
| 実在人物グループ | library_type: "liveness_face" | GroupType: "LivenessFace" | 視覚的検証フローの成功によってのみ作成されます |
| プロジェクト名 | project_name | ProjectName | 異なるプロジェクトのマテリアルを分離します。デフォルトは 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 の参照として再利用する前に、製品側で同意を取得し、顔を検証する必要がある場合はこのフローを使用します。
CallbackURLを指定して 視覚的検証セッションの作成 を呼び出します。Result.BytedTokenを保存し、検証対象の人物に対してResult.H5Linkを開きます。- H5 フローがコールバックにリダイレクトされた後、同じ
BytedTokenとProjectNameを使用して 視覚的検証結果の取得 をポーリングします。 - 返された
Result.GroupIdを保存します。このステップで TokenLab はLivenessFaceグループを作成およびバインドします。 - そのグループ 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 互換) を参照してください。