ビデオと素材

動画の作成

動画生成タスクを開始します

POST
/v1/videos/generations

概要

動画生成は非同期で行われます。作成リクエストが成功すると、タスク id(task_id と同じ値)と poll_url が返されます。その ID を使用して、status が completed または failed になるまで GET /v1/tasks/{id} を呼び出し、その後 video_url を読み取ります。詳細は動画ステータスの取得を参照してください。

  • 生成結果ファイルは30日間保存されます。より長期間必要な場合はダウンロードしてください。データの保持を参照してください。
  • キューに入っている Seedance タスクは、タスクのキャンセルでキャンセルできます。
  • コストはタスクが受け付けられた時点で仮確保され、タスクが完了または失敗した時点で決済されます。請求と料金を参照してください。
  • タイムアウト後に作成リクエストを安全に再試行するには、Idempotency-Key ヘッダーを送信してください。

各モデルはそれぞれ固有の操作とフィールドを受け付けます。GET /v1/models/{model}(モデルの取得)には、操作ごとに受け入れられるフィールド、解像度、再生時間、アスペクト比が一覧表示されます。その一覧に含まれないフィールドや値を指定すると、受け入れ可能な値とともに 400 が返されます。duration、resolution、aspect_ratio、output_audio は自身で設定してください。省略した場合、TokenLab はその操作に対するモデルのデフォルト値を使用しますが、一致するデフォルトがない場合、リクエストは 400 を返し、設定が必要なフィールド名を提示します。

音声およびメディア入力

オーディオの動作は、選択したモデルおよび操作によって異なります。オーディオセレクターが表示されていない場合でも、動画に音声が含まれることがあります。セレクターを省略することと、falseを送信することは異なります。

  • veo3.1、veo3.1-fast、および veo3.1-lite は常に音声を生成します。output_audio を省略するか true を送信してください。false は拒否されます。
  • wan-2.6 および wan-2.7 は常に音声を含みます。output_audio を省略するか true を送信してください。wan-3.0 および wan-3.0-prime も常に音声を含み、オーディオセレクターは使用しません。
  • hailuo-h3 はネイティブ音声を生成し、ミュートスイッチはありません。モデル詳細に記載されていないオーディオセレクターは送信しないでください。
  • viduq3-pro および viduq3-turbo はデフォルトで音声を生成します。無音で出力するには output_audio: false(または audio: false)を送信してください。Seedance および PixVerse モデルは output_audio を受け付けます。デフォルトに依存せず、明示的に送信してください。これは、リストに記載されている操作に対してのみ使用してください。
  • audio_url / audio_urls は入力または参照用の音声を提供します。これらは音声出力のスイッチではありません。動画編集、モーション転送、およびスタイル転送では入力サウンドトラックが保持される場合があります。ソース音声を保持することは、ミュートすることを意味しません。

許可される値や音声に依存する価格については、モデル詳細を確認してください。モデルでリストされている場合、エイリアスである outputAudio、generate_audio、およびブール値の audio は、組み合わせて使用する際に output_audio と一致している必要があります。モデルファミリー内のすべてのバージョンや操作が同じオーディオ制御を共有しているとは想定しないでください。

画像、動画、音声には一般公開されておりアクセス可能な https URL を使用し、タスクが開始されるまで有効な状態を維持してください。メディア URL は最大 8,192 文字まで指定できます。一部のモデルはインラインの data: 画像 URL(フィールドあたり最大 2,000,000 文字)も受け付けますが、大きなファイルには URL の方が信頼性が高くなります。同一リクエスト内でインライン Base64 とリモート URL を混在させないでください。

リクエストボディ

modelstringデフォルト: veo3.1

動画モデル ID。モデル一覧の取得(recommended_for=video)で現在の動画モデルを一覧取得し、モデルを明示的に送信してください。

PixVerse

  • モデル: pixverse-c1, pixverse-v6, pixverse-v5.6
  • 操作: text-to-video, image-to-video, start-end-to-video, reference-to-video
  • 音声セレクター: output_audio, デフォルトは false

TokenLab では、上記の PixVerse モデルは operation=video-extension を受け付けません。

HappyHorse

  • モデル: happyhorse-1.0
  • 操作: text-to-video, image-to-video, reference-to-video, video-to-video
  • 音声セレクター: output_audio を送信しないでください。
promptstring

動画のテキスト説明(最大 10,000 文字)。ほとんどの操作で必須ですが、不要な操作についてはモデル詳細に記載されています。

operationstring

生成モード: text-to-video、image-to-video、reference-to-video、start-end-to-video、video-to-video、video-extension、または motion-control。各モデルはこれらの一部のみをサポートしており、それ以外を指定した場合は 400 unsupported_operation が返されます。省略した場合、TokenLab は入力内容から推論します。extend_at または extend_times を含む task_id は video-extension、参照画像や素材がある場合は reference-to-video、end_image がある場合は start-end-to-video、動画入力がある場合は video-to-video、画像入力(image、image_url、image_urls、または start_image)がある場合は image-to-video、それ以外は text-to-video となります。不一致によるエラーを早期に検知するため、明示的に送信することをお勧めします。

image_urlstring

最初のフレーム画像の一般公開されたアクセス可能な URL。Seedance 2.0 モデルでは、ACTIVE な TokenLab 素材を最初のフレームとして使用するための asset://asset-YYYYMMDDHHMMSS-xxxxx も受け付けます。最も幅広いモデルサポートを得るには、https URL の使用を推奨します。

imagestring

データ URL 形式のインライン画像(例: data:image/jpeg;base64,...)。一部のモデルのみが受け付けます。image_url の方がより多くのモデルで動作します。

image_urlsarray

このフィールドが一覧に含まれるモデル用の画像 URL。件数の制限については reference_images を参照してください。

reference_imagesarray

reference-to-video 用の参照画像(https URL またはデータ URL 形式)。件数制限はモデルによって異なります:

  • seedance-2.0、seedance-2.0-fast、seedance-2.0-mini: 素材アセットを含めて合計最大9件の画像参照。これを超えると 400 too_many_seedance_reference_images が返されます。
  • seedance-2.5: image_urls と reference_images を合わせて合計最大30件の画像入力。
  • grok-imagine-video: 最大7件、duration は最大10秒までに制限されます。grok-imagine-video-1.5 および grok-imagine-video-1.5-preview は参照画像を受け付けません。
  • その他のモデル: モデル詳細を参照してください。上限を超えたリクエストは 400 too_many_items を返します。

Seedance 2.0 モデルは、ACTIVE な TokenLab 素材に対する asset://asset-YYYYMMDDHHMMSS-xxxxx も受け付けます。モデルの選定、4K の制限、Mini に関する注意事項については、Seedance 2.0 動画モデルガイドを参照してください。grok-imagine-video では、参照画像と image_url または image を併用しないでください。

start_imagestring

最初のフレームの画像です。end_image を指定した場合、リクエストは start-end-to-video となります。end_image を指定しない場合は image-to-video となり、start_image はコントラクトで image として定義されているモデルにおいて image と同様に機能します。公開URLまたはデータURLを受け付けます。Seedance 2.0モデルでは asset://asset-YYYYMMDDHHMMSS-xxxxx も使用可能です。

end_imagestring

start-end-to-video 用の最後のフレーム画像。start_image と同じ入力を受け付けます。

material_asset_idstring

素材アセットの作成によって返された TokenLab Seedance 素材アセット ID。Seedance 2.0 モデルでのみ受け付けられます。他のモデルでは 400 unsupported_seedance_material_asset_model が返されます。アセットは ACTIVE 状態であり、自身のアカウントに属している必要があります。このフィールドは汎用的な参照入力です。最初のフレーム、最後のフレーム、または参照画像としての意味を明示的に割り当てるには、代わりに start_image、end_image、または reference_images に asset://<material_asset_id> を指定してください。

material_asset_idsarray

最大9個の TokenLab Seedance 素材アセット ID。これらは Seedance 2.0 モデルの9件の画像参照の上限としてカウントされます。

通常の画像 URL は画像入力として渡され、再利用可能な素材アセットは作成されません。再利用可能なアセットは素材 API を通じて作成し、その TokenLab ID または asset://asset-YYYYMMDDHHMMSS-xxxxx URI を使用してください。明示的な素材によって 409 seedance_material_preparing が返された場合は、返された inactive_asset_ids を確認し、それらの素材が ACTIVE になった後に再試行してください。

video_urlstring

動画を受け付ける操作(video-to-video、video-extension、motion-control)において、このフィールドが一覧に含まれるモデル用のソース動画の一般公開アクセス可能な URL。

video_urlsarray

このフィールドが一覧に含まれるモデル用のソースまたは参照動画。seedance-2.5 は、video_url と video_urls を合わせて合計最大10件の動画入力を受け付けます。その他のモデルについてはモデル詳細を参照してください。

audio_urlstring

このフィールドが一覧に含まれるモデルにおいて、音声参照または音声駆動操作に使用する公開音声 URL。これは入力であり、音声出力の切り替えスイッチではありません。

audio_urlsarray

このフィールドが一覧に含まれるモデル用の参照音声。seedance-2.5 は、audio_url と audio_urls を合わせて合計最大10件の音声入力を受け付け、プロンプトなしで音声参照のみのリクエストも許可します。seedance-2.5 では、参照音声と参照動画を合わせて最大30秒までです。

task_idstring

このフィールドが一覧に含まれるモデルにおいて、ワークスペース内の過去のタスクの ID(video-extension 用)。自身のワークスペースに属していないタスクを指定すると 403 task_not_owned が返されます。

extend_atinteger

video-extension を開始するソース動画の秒数。grok-imagine-video では必須です。

extend_timesstring

このフィールドが一覧に含まれるモデルにおいて、video-extension で追加する秒数。grok-imagine-video は 6 または 10 を受け付けます。

durationinteger

出力動画の長さ(秒単位)。指定可能な値はモデルと操作によって異なります。それ以外の値を指定すると 400 invalid_duration が返されます。Seedance モデルでは、モデルの対応範囲内でモデルに長さを選択させるための -1 も受け付けます。その場合、料金はタスクが完了するまで控えめに見積もられます。motion-control や grok-imagine-video の video-to-video など、一部の操作では duration を受け付けません。

secondsinteger

duration の互換用エイリアス。両方を送信する場合、同じ値である必要があります。

aspect_ratiostring

アスペクト比(例: 16:9、9:16、1:1、4:3、3:4、21:9、または adaptive(Seedance))。指定可能な値はモデルと操作によって異なります。それ以外の値を指定すると 400 invalid_aspect_ratio が返されます。

resolutionstring

出力解像度(例: 480p、720p、1080p、または 4k)。指定可能な値はモデルと操作によって異なり、一部のモデルでは 360p、540p、768p も使用されます。それ以外の値を指定すると 400 invalid_resolution が返されます。

output_audioboolean

この設定が一覧に含まれる操作用の音声出力セレクター。省略した場合はモデルのデフォルトに従います。false はモデルが許可している場合にのみ無音出力を要求します。上記の音声に関する注意事項および選択したモデルの詳細を参照してください。

output_formatstring

seedance-2.5 など、このフィールドが一覧に含まれるモデル用のコンテナ形式(mp4 または mov)。一覧にないモデルでは省略してください。

return_last_frameboolean

生成された最後のフレームも last_frame_url として返すかどうか。Seedance モデルのみ。

watermarkboolean

このフィールドが一覧に含まれるモデル(Seedance モデル)用の透かしトグル。

negative_promptstring

このフィールドが一覧に含まれるモデルにおいて、生成される動画で除外したい要素(最大5,000文字)。

seedinteger

このフィールドが一覧に含まれるモデルにおいて、再現性のある生成を行うためのシード値。Seedance 2.0 モデルではランダムシードとして -1 を受け付けます。seedance-2.5 はこのフィールドを受け付けません。

fpsinteger

このフィールドが一覧に含まれるモデル用のフレームレート(1〜120 fps)。

framesinteger

このフィールドが一覧に含まれるモデル用のフレーム数。Seedance モデルでは受け付けられません。

execution_expires_afterinteger

Seedance モデルにおいて、タスクが期限切れになるまでにキューで待機できる秒数(3600〜259200)。

priorityinteger

Seedance モデル用のタスク優先度(0〜9)。service_tier=flex と併用しないでください。

service_tierstring

Seedance 2.0 および 2.5 モデルでは、互換性のための何もしない操作(no-op)として default が受け付けられます。これらのモデルでは flex は拒否されます。

safety_identifierstring

Seedance モデル用のエンドユーザー安全性識別子(最大128文字)。省略された場合、指定されていれば TokenLab は user を使用します。

toolsarray

Seedance 2.0 および 2.5 モデルにおいて、生成中にモデルが使用できるツール。サポートされているツールは {"type": "web_search"} です。

userstring

エンドユーザーの一意の識別子。Seedance モデルでは、safety_identifier が省略された場合に TokenLab がこの値を代わりに使用します。

互換性のあるフィールド名

  • プライマリフィールドには snake_case を使用します: aspect_ratio、output_audio、reference_images。
  • 互換性のため、TokenLab は ratio、generate_audio、outputAudio、seconds、referenceImages も受け付けます。
  • プライマリフィールドとそのエイリアスを両方送信する場合、それらの値は一致している必要があります。不一致の場合は、conflicting_audio_selector、conflicting_duration、または conflicting_aspect_ratio とともに 400 が返されます。

Seedance パラメータ

Seedance モデル(seedance-2.0、seedance-2.0-fast、seedance-2.0-mini、seedance-2.5)は、上記の TokenLab フィールド名およびエイリアスである seconds、ratio、generate_audio を受け付けます。バージョンによる違いは以下のとおりです:

Seedance 2.0 モデルseedance-2.5
解像度seedance-2.0: 480p, 720p, 1080p, 4k。seedance-2.0-fast および seedance-2.0-mini: 480p, 720p480p, 720p
再生時間-1、4〜15 秒-1、4〜30 秒
アスペクト比1:1, 3:4, 4:3, 9:16, 16:9, 21:9, adaptivetext-to-video および reference-to-video では同様。image-to-video、start-end、動画編集、拡張では adaptive が必要。動画編集では duration=-1 も必要
出力形式mp4mp4 または mov
seed受付可能受付不可
参照入力素材を含めて9件の画像参照(素材はこれらのモデルでのみ受け付けられます)合計30件の画像、10件の動画、10件の音声ファイル

これらの値の最新の定義元はモデル詳細です。デフォルトに依存せず、duration、resolution、aspect_ratio、output_audio を明示的に送信してください。モデルの recommended_request に一般的なリクエストが示されています。

duration=-1 または seconds=-1 を指定すると、Seedance はモデルの対応範囲内で出力時間を自動的に決定します。TokenLab はタスク完了前にコストを控えめに見積もり、完了したタスクの使用状況が利用可能になった時点で決済します。これらのモデルでは service_tier=flex および frames は拒否されます。

Seedance の例

cURL
curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "A sleek product reveal with cinematic camera movement",
    "operation": "text-to-video",
    "duration": -1,
    "aspect_ratio": "adaptive",
    "resolution": "720p",
    "output_audio": true
  }'

レスポンス

結果、エラー、タイムスタンプ、モデルを説明するフィールドは、タスクで利用可能な場合に返されます。

idstring

タスク ID。task_id と同一です。

task_idstring

GET /v1/tasks/{id} でポーリングするためのタスク ID。

poll_urlstring

このタスクのステータス URL(/v1/tasks/{id})。API キーを使用して呼び出してください。

statusstring

タスクのステータス: pending、processing、completed、failed。新しいタスクは通常 pending になります。

createdinteger

タスクが作成された Unix タイムスタンプ。

modelstring

使用されたモデル。

billing_transaction_idstring

決済がすでに完了している場合の請求トランザクション ID。タスク ID とは異なります。

video_urlstring

動画 URL。作成レスポンスにすでに結果が含まれている場合にのみ存在します。通常はステータスレスポンスから読み取ります。

errorstring | object

タスクが失敗した場合のエラーメッセージまたは構造化エラーオブジェクト。

エラー

ステータスとコード意味
400 invalid_requestフィールドの形式が不正であるか、範囲外であるか、または不足しています。error.param にその名前が示されます。「Set aspect_ratio explicitly」のようなメッセージは、省略されたフィールドにこのリクエスト用のデフォルト値が存在しないことを意味します。
400 unsupported_operation、unsupported_parameter、invalid_resolution、invalid_duration、invalid_aspect_ratio、invalid_parameter_value、too_many_items、prompt_too_longリクエストが、その操作に対してモデルが受け付ける条件に一致していません。通常、エラーメッセージに受け入れ可能な値が一覧表示されます。
400 invalid_parameter入力が操作に適合していません(例: text-to-video で画像が送信された場合)。
400 conflicting_audio_selector、conflicting_duration、conflicting_aspect_ratioエイリアスとそのプライマリフィールドの値が一致していません。
400 unpriceable_selection選択された組み合わせに価格設定がありません。resolution、duration、aspect_ratio、または音声設定を変更してください。
400 too_many_seedance_reference_images、unsupported_seedance_material_asset_modelSeedance 2.0 モデルに対する画像参照が多すぎるか、または他のモデルに素材が送信されました。
402残高不足です。
403 task_not_owned指定された task_id は別のワークスペースに属しています。
409 seedance_material_preparing、seedance_material_route_unavailable素材がまだ ACTIVE 状態ではないか、選択されたモデルが提供された素材を使用できません。
429レート制限を超過しました。レート制限を参照してください。

リクエスト

curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1",
    "prompt": "A cat walking through a garden, cinematic lighting",
    "operation": "text-to-video",
    "duration": 4,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

レスポンス

Response
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "model": "veo3.1",
  "created": 1706000000
}

画像から動画 (Image to Video)

import requests

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "hailuo-2.3",
        "prompt": "The scene begins from the provided image and adds gentle natural motion.",
        "operation": "image-to-video",
        "image_url": "https://example.com/image.jpg",
        "duration": 6,
        "resolution": "768p"
    }
)

参照から動画 (Reference to Video)

モデルが専用の参照条件付けをサポートしている場合は、operation=reference-to-video を使用します。画像の参照は reference_images に指定し、参照動画や音声を受け付けるモデルでは video_urls および audio_urls を使用します。duration は生成される出力の長さのみを設定します。参照動画入力の長さを制限するものではありません。モデルごとの件数制限については、上記の reference_images を参照してください。

import requests

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "veo3.1",
        "prompt": "Keep the same subject identity, palette, and framing while adding subtle natural motion.",
        "operation": "reference-to-video",
        "reference_images": [
            "https://example.com/ref-a.jpg",
            "https://example.com/ref-b.jpg"
        ],
        "duration": 8,
        "resolution": "720p",
        "aspect_ratio": "9:16"
    }
)

キーフレーム制御

最初と最後のフレームを制御するには、start_image と end_image を使用します:

import requests

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "viduq2-pro",
        "operation": "start-end-to-video",
        "start_image": "https://example.com/day.jpg",
        "end_image": "https://example.com/night.jpg",
        "duration": 5,
        "resolution": "720p"
    }
)

動画から動画 (Video to Video)

モデルが既存の動画をプライマリ入力として受け付ける場合は、operation=video-to-video を使用します。grok-imagine-video の場合、video_url に公開 HTTPS .mp4 URL を渡し、編集用の prompt を送信します。resolution、duration、aspect_ratio は省略してください。

import requests

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "grok-imagine-video",
        "operation": "video-to-video",
        "video_url": "https://example.com/source.mp4",
        "prompt": "Enhance the clip while preserving the original motion."
    }
)

動画の延長 (Video Extension)

以前の結果を継続して生成するには、operation=video-extension を使用します。自身のワークスペースのタスクの task_id と prompt を送信します。その他のフィールドはモデルによって異なります。grok-imagine-video では extend_at も必要となり、extend_times として 6 または 10 を指定します。veo3.1 および veo3.1-fast は task_id と prompt を受け取ります。Seedance モデルでは、この操作に対して video_url、video_urls、task_id が一覧表示されます。

モーション制御 (Motion Control)

モデルが被写体画像とモーション参照動画の両方を想定している場合は、operation=motion-control を使用します。image_url と video_url を送信します。resolution は必須です。

import requests

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "kling-3.0-motion-control",
        "operation": "motion-control",
        "prompt": "Keep the subject identity stable while following the motion reference.",
        "image_url": "https://example.com/subject.png",
        "video_url": "https://example.com/motion.mp4",
        "resolution": "720p"
    }
)

モデルの探索

利用可能な公開動画モデルとサポートされる操作は時間の経過とともに変化します。モデル固有のフローを構築する前に、Models API を使用して現在のサポート状況を確認してください:

curl "https://api.tokenlab.sh/v1/models?recommended_for=video"

curl "https://api.tokenlab.sh/v1/models/veo3.1"

モデル固有の操作やフィールドに依存する前に、モデル詳細のレスポンスを確認してください。video-extension や motion-control などの操作はモデル固有です。このページの静的な例に依存せず、そちらで最新の利用可否を確認してください。

認証

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

作成リクエストを安全に再試行するためのオプションのキー。タスクごとに新しい一意の値(UUIDなど)を送信してください。同じキーとボディで再試行すると、元の作成リクエストの結果(通常は元のタスク)が返され、2つ目のタスクの作成、ディスパッチ、課金は行われません。すでに受け入れられたキーで異なるボディを指定すると、409で拒否されます。255文字を超えるキーは無視され、そのリクエストには冪等性保護が適用されません。詳細は冪等性キーを使用した安全な再試行を参照してください。

長さ1 <= length <= 255

リクエストボディ

application/json

レスポンス

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json