ビデオと素材

タスク作成 (Volc互換)

Volc互換APIを使用してSeedanceタスクを作成します。

POST
/api/v3/contents/generations/tasks

概要

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

この例ではSeedance 2.0を使用しています。このエンドポイントはSeedance 2.5もサポートしていますが、モデル固有の差異については以下を参照してください。このページに記載されている再利用可能なTokenLabマテリアルURIの例は、Seedance 2.0に適用されます。

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

認証とエンドポイント

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

コンテンツルール

  • type: "text" はプロンプトテキストです。
  • role が指定されていない、または role: "first_frame" が指定された type: "image_url" は、最初のフレームとして扱われます。
  • role: "last_frame" は、最初のフレームとペアにする必要があります。
  • type: "video_url" には role: "reference_video" が必要であり、type: "audio_url" には role: "reference_audio" が必要です。role: "reference_image" は参照画像を示します。
  • アイテム制限: Seedance 2.0は最大16個の content アイテム(テキスト1、画像9、ビデオ3、オーディオ3、draft_task 1)を受け付けます。Seedance 2.5は最大51個(テキスト1、画像30、ビデオ10、オーディオ10、draft_task 1)まで受け付けます。
  • image_url.url は、パブリックな画像URL、または asset://asset-YYYYMMDDHHMMSS-xxxxx のようなマテリアルURIを受け付けます。role によって、そのマテリアルが最初のフレーム、最後のフレーム、または参照画像のいずれであるかが決まります。
  • 最初のフレーム/最後のフレームの入力と、参照メディアを1つのリクエスト内で混在させないでください。
  • RESTボディは、このページに記載されているフィールドのみを受け付けます。material_asset_id や material_asset_ids を含むその他のトップレベルフィールドは、400 UnsupportedParameter を返します。TokenLabのマテリアルURIは image_url.url に指定してください。

パラメータに関する注意

model は seedance-2.0 や seedance-2.5 などのTokenLabモデルIDを受け付けます。既存のクライアントは、これらのモデルに対して既に使用しているVolcengineモデルIDを引き続き送信できます。タスク取得レスポンスは、送信した model 値を返します。認識されない値は 400 InvalidParameter を返します。

duration は秒単位の整数です。-1 は自動時間を指定します。デフォルト値と制限はモデルによって異なります:

パラメータSeedance 2.0Seedance 2.5
duration4–15 / -1 (デフォルト: 5)4–30 / -1 (デフォルト: -1)
resolution480p, 720p, 1080p (デフォルト: 720p)480p, 720p (デフォルト: 720p)
generate_audioboolean (デフォルト: false)boolean (デフォルト: true)
priorityサポート対象外integer: 0–9
seedinteger: -1–4294967295 (デフォルト: -1)サポート対象外
execution_expires_after3600–259200 秒 (デフォルト: 172800)3600–259200 秒 (デフォルト: 172800)

Seedance 2.5の場合、最初のフレーム、最初の/最後のフレーム、ビデオ拡張、およびビデオ・ツー・ビデオのリクエストには ratio: "adaptive" が必要です。ビデオ・ツー・ビデオには duration: -1 も必要です。output_format はSeedance 2.5でのみ mp4 または mov を受け付けます。

  • ratio は 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, または adaptive (デフォルト: adaptive) を受け付けます。
  • watermark と return_last_frame はブール値です (デフォルト: false)。safety_identifier は最大64文字の文字列です。
  • service_tier は default のみ受け付けます。flex は 400 UnsupportedParameter を返します。
  • tools は最大1つのアイテム {"type": "web_search"} を受け付けます。
  • draft: true、frames、および camera_fixed はサポートされていません。camera_fixed: false はSeedance 2.0でのみ受け付けられます。
  • callback_url は、最大2,048文字のパブリックHTTP(S)エンドポイントを指定できます。

コールバック配信

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

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

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

画像の準備

パブリックなHTTP(S)画像URLおよびサポートされているデータURLは、提供された通りに使用されます。これらは自動的に再利用可能なマテリアルとして保存されません。明示的な asset://asset-... 参照は、既存のTokenLabマテリアルを使用します。TokenLabは生成前に所有権と準備状況を確認します。参照されたマテリアルがまだ準備中の場合は、準備ができるまで待ってから再試行してください。作成に失敗した場合は error.code と error.message を確認してください。

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

作成レスポンス

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

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

重複タスクの防止

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

  • 元のタスクが作成されていた場合、TokenLabは同じ cgt-... IDを返し、Idempotency-Replayed: true を追加します。
  • 異なるボディでキーを再利用すると、409 とコード idempotency_conflict が返され、2つ目のタスクは作成されません。
  • 255文字を超えるキー、または改行を含むキーは 400 InvalidParameter を返します。

キーはJSONレスポンスの形式を変更しません。TokenLabは X-Request-ID や、キーのない同一のリクエストボディから重複を推測することはありません。

例

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.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"}
  }
]

エラー

RESTエラーは {"error": {"code", "message", "param", "type"}} を使用します。リクエストの問題は 400 と InvalidParameter または UnsupportedParameter を返し、Bearerキーがない場合は 401 AuthenticationError を返します。残高不足 (402) やレート制限 (429) などのビデオ生成によるエラーは、そのHTTPステータスを維持します。

同じ操作は、POST /api/v3?Version=2024-01-01 におけるアクション CreateContentsGenerationsTasks、GetContentsGenerationsTask、ListContentsGenerationsTasks、および DeleteContentsGenerationsTasks としても利用可能です。新規の統合には、上記のRESTパスを使用してください。

次のステップ

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

curl -X POST "https://example.com/api/v3/contents/generations/tasks" \  -H "Content-Type: application/json" \  -d '{    "model": "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  }'
{  "id": "string"}

認証

BearerAuth
AuthorizationBearer <token>

APIキー認証。Dashboard > API > API KeysでAPIキーを作成または管理します。

場所: header

ヘッダー

X-TokenLab-Delivery-Policy?string

リクエストごとの配信ポリシー。APIキーおよびWorkspaceのデフォルト設定を上書きします。自動的にまず TokenLab Verified を試行し、出力、リクエストの受け入れ、または永続的なリソース作成の前に、一度だけ Official に切り替える場合があります。

指定できる値

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

べき等な REST タスク作成のためのクライアント生成キー(改行なし、1~255 文字)。同じ TokenLab API 認証情報の下で、同じ JSON ボディで同じキーを再利用すると元の cgt タスク ID が返されます。異なるボディで再利用すると、コード idempotency_conflict とともに 409 が返されます。キーが長すぎる、または改行が含まれている場合は 400 が返されます。タイムアウトや切断後に再試行する場合は、認証情報、キー、リクエストボディを変更しないでください。

長さ1 <= length <= 255

リクエストボディ

application/json

レスポンス

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json