メディアガイド

VolcengineからSeedanceを移行する

Volcengineのリクエスト形式を維持したまま、SeedanceをTokenLabに切り替える

アプリケーションで既にVolcengineのSeedance APIを使用している場合、そのRESTパス、content[]ボディ、レスポンスフィールド、コールバック、およびPascalCaseのMaterial Actionをそのまま維持できます。APIホストを変更し、AK/SK署名をTokenLab APIキーに置き換えてください。

変更点

変更項目既存のVolcengineクライアントTokenLab
ベースURLVolcengineのエンドポイントhttps://api.tokenlab.sh/
認証AK/SKリクエスト署名Authorization: Bearer <TOKENLAB_API_KEY>
タスク転送公式の /api/v3/contents/generations/tasks RESTパス維持
Material/検証 ActionAction および Version クエリパラメータ維持
タスクボディVolcengine形式の content[]維持
MaterialボディGroupId や ProjectName などのPascalCaseフィールド維持
非同期結果VolcengineタスクのライフサイクルTokenLabの cgt-... タスクID(ポーリングおよびオプションのコールバック付き)

AK/SKのみで署名されたリクエストは 401 AuthenticationError を返します。すべてのTokenLabリクエストには Authorization: Bearer <TOKENLAB_API_KEY> を含める必要があります。

エンドポイントの選択

既存のクライアントTokenLabエンドポイント
Volcengine RESTタスククライアント/api/v3/contents/generations/tasks およびそのタスクパス
Materialまたは検証 ActionクライアントPOST /?Action=...&Version=2024-01-01 または POST /api/v3?Action=...&Version=2024-01-01

ビデオタスクについては、既存のRESTメソッド、パス、JSONボディを維持してください。Materialおよび検証リクエストは、引き続きActionおよび Version クエリパラメータを使用します。Actionエンドポイントは、タスクActionである CreateContentsGenerationsTasks、GetContentsGenerationsTask、ListContentsGenerationsTasks、および DeleteContentsGenerationsTasks も受け付けますが、新規の作業にはRESTパスを使用してください。

公式タスクパス

メソッドとパス目的
POST /api/v3/contents/generations/tasksビデオタスクの作成
GET /api/v3/contents/generations/tasks/{id}タスクの読み取り
GET /api/v3/contents/generations/tasksタスクの一覧表示
DELETE /api/v3/contents/generations/tasks/{id}キュー内のタスクをキャンセル。開始済みのタスクは 409 task_not_cancellable を返します

RESTクライアントは以下の同等のリファレンスを使用できます:

リクエストボディのルール

  • content[] は text、image_url、video_url、audio_url、および draft_task アイテムを受け付けます。
  • image_url の場合、role を省略するか、Image-to-Videoには first_frame を使用してください。last_frame は first_frame と組み合わせて使用するか、Reference-to-Videoには reference_image を使用します。
  • 選択したSeedanceワークフローがそのメディアロールを受け付ける場合、asset://asset-YYYYMMDDHHMMSS-xxxxx のようなパブリックMaterial URIを使用できます。
  • RESTボディは、model、content、ratio、duration、resolution、generate_audio、watermark、return_last_frame、seed、execution_expires_after、safety_identifier を含む公式フィールドのみを受け付けます。デフォルト値はモデルに依存します。seedance-2.0 モデルでは generate_audio は false、seedance-2.5 では true となり、duration は seedance-2.0 モデルで 5、seedance-2.5 で -1 となります。このREST形式は resolution 値として 480p、720p、1080p を受け付けますが(seedance-2.5 は 480p と 720p のみ)、統一された /v1/videos/generations APIのみが受け付ける 4k は受け付けません。seedance-2.5 は seed、frames、camera_fixed を拒否します。
  • callback_url はパブリックなHTTP(S)エンドポイントを受け付けます。TokenLabは queued、running、succeeded、failed、expired に対して同じクエリタスクボディを送信します。succeeded と failed のみが公式の動作(5秒のタイムアウト、およびエンドポイントが通知を認識しない場合の再試行)に従います。

最小限のREST例

curl 'https://api.tokenlab.sh/api/v3/contents/generations/tasks' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Idempotency-Key: $CLIENT_JOB_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "content": [
      {"type":"text","text":"A cinematic product reveal"},
      {"type":"image_url","role":"reference_image","image_url":{"url":"https://example.com/reference.png"}}
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p"
  }'

返された cgt-... IDを保存してください。status が succeeded、failed、cancelled、または expired になるまでポーリングします。作成レスポンスをビデオの完了と見なさないでください。callback_url を提供する場合でも、succeeded または failed の通知が繰り返されることを許容し、リカバリパスとしてポーリングを継続してください。

v1とv3の型を分離する

このエンドポイントに対して /v1/tasks/{id} のレスポンス構造を再利用しないでください。統一されたv1 APIは pending、processing、completed、failed を報告しますが、Volc互換のv3 APIは queued、running、succeeded、failed、cancelled、expired を報告します。公式のv3レスポンスは duration をJSON文字列として表現し、失敗していないタスクでは error を省略します。

作成タイムアウトや切断後の安全なリカバリのために、REST作成リクエストに一意の Idempotency-Key を追加してください。同じキーで同じボディを再試行すると元の cgt-... IDが返されます。同じキーで異なるボディを指定すると 409 が返されます。

Materialおよび本人確認

同じActionエンドポイントは、10種類のMaterialおよびMaterialグループ操作もサポートしています。正確なPascalCaseボディ、フィルタ、ページング、レスポンスエンベロープ、および12時間のMaterial URLについては、Material Actions (Volc互換) を参照してください。

本人確認用Materialは、アップロード前に2つのActionを追加します:

  1. Visual Validationセッションの作成
  2. Visual Validation結果の取得

2番目のActionは検証済みの GroupId を返します。そのIDを CreateAsset で使用してください。クライアントが直接 LivenessFace グループを作成することはできません。

移行チェックリスト

  1. APIホストを https://api.tokenlab.sh に置き換える。
  2. AK/SK署名をTokenLab Bearer APIキーに置き換える。
  3. 公式のRESTタスクメソッド、パス、リクエストボディのケースを維持する。ActionとバージョンはMaterialまたは検証操作のみに使用する。
  4. 関連するMaterialおよび検証リクエスト全体で同じ ProjectName を維持する。
  5. これらのエンドポイントによって返されるTokenLabのタスクID、グループID、アセットIDを保存する。
  6. 本番環境のトラフィックを移行する前に、作成、ポーリング、一覧表示、およびエラーレスポンスを1つずつ検証する。

このページの内容