メディアガイド
VolcengineからSeedanceを移行する
Volcengineのリクエスト形式を維持したまま、SeedanceをTokenLabに切り替える
アプリケーションで既にVolcengineのSeedance APIを使用している場合、そのRESTパス、content[]ボディ、レスポンスフィールド、コールバック、およびPascalCaseのMaterial Actionをそのまま維持できます。APIホストを変更し、AK/SK署名をTokenLab APIキーに置き換えてください。
変更点
| 変更項目 | 既存のVolcengineクライアント | TokenLab |
|---|---|---|
| ベースURL | Volcengineのエンドポイント | https://api.tokenlab.sh/ |
| 認証 | AK/SKリクエスト署名 | Authorization: Bearer <TOKENLAB_API_KEY> |
| タスク転送 | 公式の /api/v3/contents/generations/tasks RESTパス | 維持 |
| Material/検証 Action | Action および 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/generationsAPIのみが受け付ける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を追加します:
2番目のActionは検証済みの GroupId を返します。そのIDを CreateAsset で使用してください。クライアントが直接 LivenessFace グループを作成することはできません。
移行チェックリスト
- APIホストを
https://api.tokenlab.shに置き換える。 - AK/SK署名をTokenLab Bearer APIキーに置き換える。
- 公式のRESTタスクメソッド、パス、リクエストボディのケースを維持する。ActionとバージョンはMaterialまたは検証操作のみに使用する。
- 関連するMaterialおよび検証リクエスト全体で同じ
ProjectNameを維持する。 - これらのエンドポイントによって返されるTokenLabのタスクID、グループID、アセットIDを保存する。
- 本番環境のトラフィックを移行する前に、作成、ポーリング、一覧表示、およびエラーレスポンスを1つずつ検証する。