動画を作成 - TokenLab

概要

動画生成は非同期です。リクエストを送信すると、task_id と poll_url が返り、その後はポーリングで最終結果を取得します。

ポーリング動作

最も安定したポーリングのため、作成レスポンスで返された poll_url をそのまま使用してください。作成レスポンスで poll_url が返る場合は、その URL をそのまま使ってください。/v1/tasks/{id} を指す場合は、それを固定の正規ステータスエンドポイントとして扱ってください。

モデルとメディアの動作

音声出力はモデルによって異なります。TokenLab では、Veo 3 と Seedance のリクエストは output_audio を省略すると音声オンとして扱われます。モデルが音声制御に対応している場合は、output_audio で明示的に切り替えてください。互換エイリアスの outputAudio と generate_audio も受け付けますが、複数指定する場合は output_audio と同じ値である必要があります。本番環境では、画像・動画・音声入力には公開アクセス可能な https URL を優先してください。互換モデルでは data: URL も利用できますが、大きな base64 は retry・観測・デバッグを難しくします。

リクエストボディ

model

string

デフォルト:"veo3.1"

動画モデル ID。veo3.1、wan-2.7、happyhorse-1.0、viduq3、pixverse-v6、kling-3.0-video などの製品レベルの論理 ID を使い、text-to-video、image-to-video、reference-to-video などの違いは operation で選択してください。動画生成ガイドと Models API を参照してください。

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 を送信しないでください。

prompt

string

必須

生成したい動画のテキスト説明です。大半の公開動画モデルで必須です。

operation

string

実行する動画操作です。対応値として text-to-video、image-to-video、reference-to-video、start-end-to-video、video-to-video、video-extension、audio-to-video、motion-control を受け付けます。入力から自動推定もできますが、本番では明示指定を推奨します。

image_url

string

画像から動画生成に使う開始画像 URL です。最も広い互換性を得るには image_url を優先してください。

image

string

data:image/...;base64,... 形式のインライン画像です。互換モデルでは利用できますが、image_url の方が一般に扱いやすく安定します。

reference_images

array

reference-to-video フローで使う参照画像入力です。許容数はモデルごとに異なります。seedance-2.0 と seedance-2.0-fast では、TokenLab は現在最大 9 枚の参照画像に加えて、最大 3 本の参照動画と 3 本の参照音声をサポートします。モデル選択、4K の境界、Mini の注意点については Seedance 2.0 ビデオモデルガイドを参照してください。公開 https URL を推奨し、互換モデルでは data: URL も利用できます。 grok-imagine-video の reference-to-video は最大 7 件の画像参照を受け付け、duration は最大 10 秒です。grok-imagine-video-1.5-preview は image-to-video のみで、参照画像は受け付けません。

material_asset_id

string

素材を作成または自動画像準備で返される TokenLab Seedance 素材 ID。素材が ACTIVE になった後、TokenLab 素材ライブラリを使用できる Seedance モデルで使用できます。

material_asset_ids

array

複数の TokenLab Seedance 素材 ID。reference_images と同じ Seedance 画像参照数の上限を共有します。選択したモデルは TokenLab 素材ライブラリを使用できる必要があります。

選択した Seedance モデルが TokenLab 素材ライブラリを使用できる場合、TokenLab は生成前に画像フィールド（image, image_url, image_urls, reference_images, start_image, end_image）を再利用可能な素材として準備します。60 秒以内に準備が完了しない場合、API は auto_material_asset_ids 付きの 409 seedance_material_preparing を返します。素材が ACTIVE になってから再試行してください。選択したモデルが素材ライブラリを使用できない場合、通常の画像入力は通常の画像パスで処理され、明示的な素材 ID は再試行可能な素材可用性エラーで安全に失敗します。

reference_image_type

string

asset と style を区別するモデル向けの任意フィールドです。

kling_elements

array

kling-3.0-video の要素参照定義です。画像条件付きリクエストでのみ利用できます。1-3 個の要素を定義でき、各要素には name、任意の description、2-4 個の画像 URL を含む element_input_urls を指定します。prompt では @name で参照します。kling_elements と output_audio=true は併用できません。要素参照を使う場合は output_audio を省略するか false にしてください。

video_url

string

ソース動画の公開 URL。動画 URL ベースの video-to-video フローと motion-control で必要です。一部の派生フローでは代わりに task_id を使います。

video_urls

array

マルチモーダル参照条件付けに対応したモデル向けの追加参照動画入力です。許容数はモデルごとに異なります。seedance-2.0 と seedance-2.0-fast では、TokenLab は現在最大 3 本の参照動画をサポートします。

audio_url

string

audio-to-video 系モデルで使う公開音声 URL です。

audio_urls

array

マルチモーダル参照条件付けに対応したモデル向けの追加参照音声入力です。許容数はモデルごとに異なります。seedance-2.0 と seedance-2.0-fast では、TokenLab は現在最大 3 本の参照音声をサポートします。

task_id

string

一部の継続、延長、派生フローで使用するタスク識別子です。

extend_at

integer

一部の video-extension フローで使うモデル固有の延長開始オフセットです。

extend_times

string

一部の video-extension フローで使うモデル固有の延長回数・倍率です。

duration

integer

生成される出力動画の長さ（秒）です。Seedance 1.5/2.0 モデルでは、このフィールドを省略すると 5 が使われます。-1 を送ると、モデルが対応範囲内で長さを選択し、タスク完了までは保守的に課金見積もりされます。

seconds

integer

duration の互換エイリアスです。seconds と duration を両方送る場合、値は同一である必要があります。Seedance では seconds=-1 は duration=-1 と同じ自動長の意味になります。

aspect_ratio

string

正規のアスペクト比です。例: adaptive、16:9、9:16、1:1、4:3、3:4、21:9。Seedance では省略時に adaptive が使われます。

resolution

string

モデル依存の出力解像度です。Seedance は省略時に 720p を使用します。seedance-2.0 は 480p、720p、1080p、4k に対応し、seedance-2.0-fast と seedance-2.0-mini は 480p と 720p に限定されます。

output_audio

boolean

モデル依存の正規音声出力スイッチです。Veo 3 と Seedance は省略時に true になります。kling-3.0-video は要素参照を使わないリクエストでこのセレクタを受け付け、省略時は無音出力になります。output_audio=true と kling_elements は組み合わせないでください。

draft

boolean

Seedance 1.5 Pro の Draft ワークフロー用フラグです。Draft タスクに対応する Seedance モデルで draft=true を指定します。draft_task_id と同時に送信しないでください。

draft_task_id

string

Seedance 1.5 Pro のドラフト昇格タスク ID です。以前のドラフトタスク ID を送ると最終動画を作成します。汎用動画フィールドではありません。

ratio

string

aspect_ratio の互換エイリアスです。ratio と aspect_ratio を両方送る場合、値は同一である必要があります。

generate_audio

boolean

output_audio の互換エイリアスです。generate_audio、output_audio、outputAudio が同時に現れる場合、すべての値が一致している必要があります。

execution_expires_after

integer

対応する動画モデルの任意の実行期限（秒）です。Seedance は省略時に 172800 秒を使用します。

priority

integer

対応する動画モデルの任意のタスク優先度で、範囲は 0 から 9 です。priority と service_tier=flex は組み合わせないでください。

safety_identifier

string

対応する動画モデル向けの任意のエンドユーザー安全識別子です。Seedance で省略された場合、TokenLab は user があればその値を使用します。

service_tier

string

default は Seedance 2.0 モデルで互換 no-op として受け付けます。flex は選択したモデルが対応している場合のみ使用できます。

frames

integer

対応する動画モデル向けの任意のフレーム数です。Seedance 2.0 モデルと Seedance 1.5 Pro はこのフィールドに対応していません。

camera_fixed

boolean

対応する動画モデル向けの任意の固定カメラ指定です。Seedance 2.0 モデルはこのフィールドに対応していません。

fps

integer

フレームレート（1〜120）。FPS を公開しているモデルのみ有効です。

negative_prompt

string

生成で避けたい内容です。

seed

integer

再現可能な生成に使う乱数シードです。Seedance は省略時にランダムシードとして -1 を使用します。

cfg_scale

number

プロンプト追従強度（0〜20）。対応モデルのみ有効です。

motion_strength

number

動きの強さ（0〜1）。対応モデルのみ有効です。

start_image

string

start-end-to-video で使う開始フレーム画像 URL または互換画像入力です。

end_image

string

start-end-to-video で使う終了フレーム画像 URL または互換画像入力です。

size

string

対応する動画モデル向けのモデル固有サイズ階層です。

watermark

boolean

対応モデルが公開している任意の透かしスイッチです。Seedance は省略時に false を使用します。

effect_type

string

一部の編集・エフェクト系フローで使うモデル固有のエフェクト指定です。

user

string

エンドユーザーの一意な識別子です。Seedance では、このフィールドを省略した場合に TokenLab がこの値を safety_identifier としても使用します。

互換性メモ

正規の公開フィールドは snake_case のままです: aspect_ratio、output_audio、reference_images、reference_image_type。
互換性のため、TokenLab は ratio、generate_audio、outputAudio、seconds、referenceImages、referenceImageType も受け付けます。
正規フィールドとエイリアスフィールドを両方送る場合、値は一致している必要があります。競合するエイリアスはタスク作成前に拒否されます。
operation を省略すると、TokenLab は指定された入力から推論します。本番トラフィックでは明示的な operation の指定を引き続き推奨します。

入力のベストプラクティス

image_url、reference_images、video_url、audio_url には、公開アクセス可能な https URL を優先してください。
同一リクエスト内で base64 とリモート URL を混在させるのは避ける方が安全です。
リモートメディア URL は、再試行や非同期タスク生成をカバーできる有効期限にしてください。

Seedance パラメータ

Seedance 1.5/2.0 モデルでは、統一エンドポイントは TokenLab のフィールド名を主に使いつつ、互換エイリアス seconds、ratio、generate_audio も受け付けます。Seedance のセレクタを省略すると、duration=5、resolution=720p、aspect_ratio=adaptive、output_audio=true、watermark=false、return_last_frame=false、execution_expires_after=172800、priority=0、seed=-1 が使われます。 duration=-1 または seconds=-1 を指定すると、Seedance がモデル対応範囲内で出力長を選択します。TokenLab はタスク完了前に保守的にコストを見積もり、完了タスクの usage が取得できる場合は実績に基づいて精算します。service_tier=default は Seedance 2.0 で互換 no-op として受け付けます。service_tier=flex、frames、camera_fixed は選択モデルが対応していない場合に拒否されます。

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.0",
    "prompt": "A sleek product reveal with cinematic camera movement",
    "operation": "text-to-video",
    "duration": -1,
    "aspect_ratio": "adaptive",
    "resolution": "720p",
    "output_audio": true
  }'

レスポンス

string

正規の非同期タスク ID です。id と task_id の両方がある場合は、同じタスク識別子として扱ってください。

task_id

string

ポーリング用の一意なタスク ID です。

poll_url

string

このタスクに推奨されるポーリング URL です。状態確認にはこのパスをそのまま使ってください。

billing_transaction_id

string

決済がすでに完了している場合に返される TokenLab の請求トランザクション ID です。dashboard / 照合で使う取引識別子であり、非同期 id / task_id とは別物です。

status

string

初期ステータスは pending です。

created

integer

タスク作成時の Unix タイムスタンプです。

model

string

使用されたモデルです。

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,
    "aspect_ratio": "16:9"
  }'

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

画像から動画

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "hailuo-2.3-standard",
        "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,
        "aspect_ratio": "16:9"
    }
)

Kling 3.0 Elements

kling_elements は、要素参照が必要な場合に kling-3.0-video と一緒に使います。画像条件付きリクエスト（image_url、image_urls、start_image、end_image）を指定し、各要素をプロンプト内で @name として参照します。kling_elements と output_audio=true は併用できません。要素参照を使う場合は output_audio を省略するか false にしてください。

response = requests.post("https://api.tokenlab.sh/v1/videos/generations",
    headers=headers,
    json={
        "model": "kling-3.0-video",
        "prompt": "Place @hero_bag on a studio turntable with soft product lighting.",
        "operation": "image-to-video",
        "image_url": "https://example.com/studio-start.png",
        "duration": 5,
        "resolution": "720p",
        "kling_elements": [
            {
                "name": "hero_bag",
                "description": "black leather handbag",
                "element_input_urls": [
                    "https://example.com/bag-front.png",
                    "https://example.com/bag-side.png"
                ]
            }
        ]
    }
)

参照画像から動画

モデルが専用の参照条件付けに対応している場合は operation=reference-to-video を使います。TokenLab の対応値として、画像参照は reference_images、マルチモーダル参照動画と参照音声は video_urls と audio_urls を使います。seedance-2.0 と seedance-2.0-fast では、TokenLab は現在最大 9 枚の参照画像に加えて、最大 3 本の参照動画と 3 本の参照音声をサポートします。モデル選択、4K の境界、Mini の注意点については Seedance 2.0 ビデオモデルガイドを参照してください。duration は生成される出力長のみを制御し、参照動画入力の長さ上限を個別に設定するものではありません。 grok-imagine-video の reference-to-video は最大 7 件の画像参照（reference_images または image_urls）を受け付け、duration は最大 10 秒です。参照画像を image_url / image の先頭フレーム入力と組み合わせないでください。grok-imagine-video-1.5-preview は image-to-video のみです。

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 and palette while adding subtle motion.",
        "operation": "reference-to-video",
        "reference_images": [
            "https://example.com/ref-a.jpg",
            "https://example.com/ref-b.jpg"
        ],
        "reference_image_type": "asset",
        "duration": 8,
        "resolution": "720p",
        "aspect_ratio": "9:16"
    }
)

開始・終了フレーム制御

start_image と end_image を使って最初と最後のフレームを制御します。

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

動画から動画

grok-imagine-video の video-to-video では、公開 HTTPS の .mp4 URL を video_url に渡します。TokenLab はこれを xAI REST の video.url ボディへ変換します。resolution は 480p または 720p に設定できます。この編集フローでは duration と aspect_ratio は受け付けません。既存の動画を主入力として使う場合は operation=video-to-video を使用します。

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.",
        "resolution": "720p"
    }
)

モーション制御

主体画像とモーション参照動画の両方を必要とするモデルでは operation=motion-control を使用します。TokenLab は公開リクエスト形の image_url と video_url をモデルが必要とするリクエスト形式に正規化します。

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 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" \
  -H "Authorization: Bearer sk-your-api-key"

curl "https://api.tokenlab.sh/v1/models/veo3.1" \
  -H "Authorization: Bearer sk-your-api-key"

モデル固有の操作やフィールドに依存する前に、モデル詳細レスポンスを確認してください。audio-to-video や video-extension などの操作はモデル固有です。本ページの静的な例ではなく、そこで現在の可用性を確認してください。

​概要

​ポーリング動作

​モデルとメディアの動作

​リクエストボディ

​互換性メモ

​入力のベストプラクティス

​Seedance パラメータ

​Seedance の例

​レスポンス

​画像から動画

​Kling 3.0 Elements

​参照画像から動画

​開始・終了フレーム制御

​動画から動画

​モーション制御

​モデル検出

概要

ポーリング動作

モデルとメディアの動作

リクエストボディ

互換性メモ

入力のベストプラクティス

Seedance パラメータ

Seedance の例

レスポンス

画像から動画

Kling 3.0 Elements

参照画像から動画

開始・終了フレーム制御

動画から動画

モーション制御

モデル検出