タスク作成 (Volc互換)

概要Copy Anchor Link

既存のVolc形式のSeedanceクライアントは、APIアドレスとキーを変更することでTokenLabを利用できます。

Seedance 2.0 ビデオモデル および ビデオ生成 も併せて参照してください。

認証とエンドポイントCopy Anchor Link

• Authorization: Bearer <TOKENLAB_API_KEY> を使用してください。
• Volc AK/SK署名は受け付けられません。リクエストにはTokenLabのBearerキーを含める必要があります。
• 公式のタスクパス POST /api/v3/contents/generations/tasks を使用してください。

コンテンツルールCopy Anchor Link

• type: "text" はプロンプトテキストです。
• role が指定されていない、または role: "first_frame" が指定された type: "image_url" は、最初のフレームとして扱われます。
• role: "last_frame" は、最初のフレームとペアにする必要があります。
• role: "reference_image"、reference_video、reference_audio は参照用として使用されます。
• image_url.url は、パブリックな画像URL、または asset://asset-YYYYMMDDHHMMSS-xxxxx のようなマテリアルURIを受け付けます。role によって、そのマテリアルが最初のフレーム、最後のフレーム、または参照画像のいずれであるかが決定されます。
• 最初のフレーム/最後のフレームの入力と参照メディアを1つのリクエスト内で混在させないでください。
• トップレベルの material_asset_id と material_asset_ids は受け付けません。TokenLab の素材 URI は image_url.url に指定してください。priority は Seedance 2.5 のみ対応します。

パラメータに関する注意点Copy Anchor Link

duration は整数の秒数で、-1 は自動の長さを指定します。既定値と制限はモデルごとに異なります。

Seedance 2.5 の最初のフレーム、最初と最後のフレーム、動画延長、動画から動画への生成には ratio: "adaptive" が必要です。動画から動画への生成には duration: -1 も必要です。output_format の mp4 と mov は Seedance 2.5 のみ対応します。

• ratio は 16:9、4:3、1:1、3:4、9:16、21:9、または adaptive を受け付けます。
• watermark、return_last_frame、seed、execution_expires_after、safety_identifier は、選択したモデルで有効な場合に受け付けられます。
• callback_url にはパブリックなHTTP(S)エンドポイントを指定できます。

コールバック配信Copy Anchor Link

callback_url が指定されている場合、タスクステータスが変更されるとTokenLabはHTTP POST を送信します。コールバックのステータスは queued、running、succeeded、failed、expired です。JSONボディはget-taskレスポンスと一致します。

2xx レスポンスは配信が完了したことを示します。succeeded および failed の場合、5秒以内に配信が成功しないと、最大3回まで再試行されます。コールバックには標準のJSONコンテンツヘッダーのみが含まれ、TokenLab固有の配信ヘッダーは含まれません。リダイレクトは追跡されず、プライベートまたは予約済みのネットワークターゲットは拒否されます。

タスクIDを保存してください。コールバックが配信されない場合でも、get-taskエンドポイントを使用して結果を取得できます。

画像の準備Copy Anchor Link

公開 HTTP(S) 画像 URL と対応する data URL は入力のまま使用され、再利用可能な素材として自動保存されません。明示的な asset://asset-... 参照は既存の TokenLab 素材を使用し、生成前に所有権と準備状況を確認します。素材が準備中なら完了後に再試行してください。作成に失敗した場合は error.code と error.message を確認してください。

既存のマテリアルについては、他のシステムから返された元の資産IDではなく、パブリックな asset-YYYYMMDDHHMMSS-xxxxx IDを使用してください。TokenLabは生成前にマテリアルの所有権を確認します。

作成レスポンスCopy Anchor Link

{
  "id": "cgt-20260102030405-a1b2c"
}

作成レスポンスにはタスクIDのみが含まれます。いつでもステータスと結果を取得できるように保存しておいてください。

重複タスクの防止Copy Anchor Link

作成リクエストには一意の Idempotency-Key を送信してください。レスポンスが届く前に接続が切断された場合は、同じAPIキー、べき等キー、およびリクエストボディを使用して再試行してください。

• 元のタスクが作成されていた場合、TokenLabは同じ cgt-... IDを返し、Idempotency-Replayed: true を追加します。
• 元のリクエストがまだ登録中の場合は 409 IdempotencyRequestInProgress を返します。後で同じキーとボディで再試行してください。
• 異なるボディでキーを再利用すると 409 IdempotencyConflict が返され、2つ目のタスクは作成されません。

べき等は公式のv3 REST作成パスに適用されます。これはJSONレスポンスの形状を変更するものではなく、X-Request-ID やキーのない同一のリクエストボディから推論されるものでもありません。

例Copy Anchor Link

REST作成Copy Anchor Link

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": "doubao-seedance-2.0",
    "content": [
      {"type": "text", "text": "A cinematic forest at sunset"},
      {"type": "image_url", "role": "reference_image", "image_url": {"url": "https://example.com/ref.png"}}
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p",
    "generate_audio": false,
    "callback_url": "https://example.com/webhooks/seedance"
  }'

既存のマテリアルについては、各URIを公式の content[] アイテムに入れ、その役割を宣言してください。

[
  {
    "type": "image_url",
    "role": "first_frame",
    "image_url": {"url": "asset://asset-20260720123458-start"}
  },
  {
    "type": "image_url",
    "role": "last_frame",
    "image_url": {"url": "asset://asset-20260720123459-end01"}
  }
]

次のステップCopy Anchor Link

タスクが最終ステータスに達するまで、返された cgt-... IDを使用して タスクの取得 (Volc互換) を呼び出してください。

curl -X POST "https://example.com/api/v3/contents/generations/tasks" \  -H "Content-Type: application/json" \  -d '{    "model": "doubao-seedance-2-0-260128",    "content": [      {        "type": "text",        "text": "A cinematic forest at sunset"      },      {        "type": "image_url",        "role": "reference_image",        "image_url": {          "url": "https://example.com/ref.png"        }      }    ],    "ratio": "16:9",    "duration": 5,    "resolution": "720p",    "generate_audio": false  }'

{  "id": "string"}