> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 動画を作成

> 動画生成タスクを作成します

## 概要

動画生成は非同期です。リクエストを送信すると、`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・観測・デバッグを難しくします。

## リクエストボディ

<ParamField body="model" type="string" default="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` で選択してください。[動画生成ガイド](/ja/guides/video-generation) と [Models API](/ja/api-reference/models/list-models) を参照してください。
</ParamField>

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

<ParamField body="prompt" type="string" required>
  生成したい動画のテキスト説明です。大半の公開動画モデルで必須です。
</ParamField>

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

<ParamField body="image_url" type="string">
  画像から動画生成に使う開始画像 URL です。最も広い互換性を得るには `image_url` を優先してください。
</ParamField>

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

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

<ParamField body="material_asset_id" type="string">
  [素材を作成](/ja/api-reference/video/create-material-asset)または自動画像準備で返される TokenLab Seedance 素材 ID。素材が `ACTIVE` になった後、TokenLab 素材ライブラリを使用できる Seedance モデルで使用できます。
</ParamField>

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

<Info>
  選択した 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 は再試行可能な素材可用性エラーで安全に失敗します。
</Info>

<ParamField body="reference_image_type" type="string">
  `asset` と `style` を区別するモデル向けの任意フィールドです。
</ParamField>

<ParamField body="kling_elements" type="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` にしてください。
</ParamField>

<ParamField body="video_url" type="string">
  ソース動画の公開 URL。動画 URL ベースの `video-to-video` フローと `motion-control` で必要です。一部の派生フローでは代わりに `task_id` を使います。
</ParamField>

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

<ParamField body="audio_url" type="string">
  `audio-to-video` 系モデルで使う公開音声 URL です。
</ParamField>

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

<ParamField body="task_id" type="string">
  一部の継続、延長、派生フローで使用するタスク識別子です。
</ParamField>

<ParamField body="extend_at" type="integer">
  一部の `video-extension` フローで使うモデル固有の延長開始オフセットです。
</ParamField>

<ParamField body="extend_times" type="string">
  一部の `video-extension` フローで使うモデル固有の延長回数・倍率です。
</ParamField>

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

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

<ParamField body="aspect_ratio" type="string">
  正規のアスペクト比です。例: `adaptive`、`16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`21:9`。Seedance では省略時に `adaptive` が使われます。
</ParamField>

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

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

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

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

<ParamField body="ratio" type="string">
  `aspect_ratio` の互換エイリアスです。`ratio` と `aspect_ratio` を両方送る場合、値は同一である必要があります。
</ParamField>

<ParamField body="generate_audio" type="boolean">
  `output_audio` の互換エイリアスです。`generate_audio`、`output_audio`、`outputAudio` が同時に現れる場合、すべての値が一致している必要があります。
</ParamField>

<ParamField body="execution_expires_after" type="integer">
  対応する動画モデルの任意の実行期限（秒）です。Seedance は省略時に `172800` 秒を使用します。
</ParamField>

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

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

<ParamField body="service_tier" type="string">
  `default` は Seedance 2.0 モデルで互換 no-op として受け付けます。`flex` は選択したモデルが対応している場合のみ使用できます。
</ParamField>

<ParamField body="frames" type="integer">
  対応する動画モデル向けの任意のフレーム数です。Seedance 2.0 モデルと Seedance 1.5 Pro はこのフィールドに対応していません。
</ParamField>

<ParamField body="camera_fixed" type="boolean">
  対応する動画モデル向けの任意の固定カメラ指定です。Seedance 2.0 モデルはこのフィールドに対応していません。
</ParamField>

<ParamField body="fps" type="integer">
  フレームレート（1〜120）。FPS を公開しているモデルのみ有効です。
</ParamField>

<ParamField body="negative_prompt" type="string">
  生成で避けたい内容です。
</ParamField>

<ParamField body="seed" type="integer">
  再現可能な生成に使う乱数シードです。Seedance は省略時にランダムシードとして `-1` を使用します。
</ParamField>

<ParamField body="cfg_scale" type="number">
  プロンプト追従強度（0〜20）。対応モデルのみ有効です。
</ParamField>

<ParamField body="motion_strength" type="number">
  動きの強さ（0〜1）。対応モデルのみ有効です。
</ParamField>

<ParamField body="start_image" type="string">
  `start-end-to-video` で使う開始フレーム画像 URL または互換画像入力です。
</ParamField>

<ParamField body="end_image" type="string">
  `start-end-to-video` で使う終了フレーム画像 URL または互換画像入力です。
</ParamField>

<ParamField body="size" type="string">
  対応する動画モデル向けのモデル固有サイズ階層です。
</ParamField>

<ParamField body="watermark" type="boolean">
  対応モデルが公開している任意の透かしスイッチです。Seedance は省略時に `false` を使用します。
</ParamField>

<ParamField body="effect_type" type="string">
  一部の編集・エフェクト系フローで使うモデル固有のエフェクト指定です。
</ParamField>

<ParamField body="user" type="string">
  エンドユーザーの一意な識別子です。Seedance では、このフィールドを省略した場合に TokenLab がこの値を `safety_identifier` としても使用します。
</ParamField>

## 互換性メモ

* 正規の公開フィールドは 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 の例

```bash cURL theme={null}
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
  }'
```

## レスポンス

<ResponseField name="id" type="string">
  正規の非同期タスク ID です。`id` と `task_id` の両方がある場合は、同じタスク識別子として扱ってください。
</ResponseField>

<ResponseField name="task_id" type="string">
  ポーリング用の一意なタスク ID です。
</ResponseField>

<ResponseField name="poll_url" type="string">
  このタスクに推奨されるポーリング URL です。状態確認にはこのパスをそのまま使ってください。
</ResponseField>

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

<ResponseField name="status" type="string">
  初期ステータスは `pending` です。
</ResponseField>

<ResponseField name="created" type="integer">
  タスク作成時の Unix タイムスタンプです。
</ResponseField>

<ResponseField name="model" type="string">
  使用されたモデルです。
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "status": "pending",
    "model": "veo3.1",
    "created": 1706000000
  }
  ```
</ResponseExample>

## 画像から動画

```python theme={null}
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` にしてください。

```python theme={null}
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 ビデオモデルガイド](/ja/guides/seedance-2-video)を参照してください。`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 のみです。

```python theme={null}
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` を使って最初と最後のフレームを制御します。

```python theme={null}
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` を使用します。

```python theme={null}
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` をモデルが必要とするリクエスト形式に正規化します。

```python theme={null}
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](/ja/api-reference/models/list-models) を真値として確認してください：

```bash theme={null}
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` などの操作はモデル固有です。本ページの静的な例ではなく、そこで現在の可用性を確認してください。