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

# Kling V4 動画生成

> テキスト・画像・参照素材からの動画生成、動画編集・延長に対応。720p / 1080p で 3～30 秒を生成し、常にステレオ音声を含みます。

> [!NOTE]
>
> このエンドポイントは非同期で処理されます。送信後、返された `task_id` を使い、`GET /v1/videos/generations/{task_id}` でタスクの状態と結果を取得してください。

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "kling-v4",
    "prompt": "A paper boat drifts along a gutter on a rainy night, with the gentle sound of rain",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "9:16"
  }'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://api.apimart.ai/v1/videos/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "kling-v4",
        "prompt": "A paper boat drifts along a gutter on a rainy night, with the gentle sound of rain",
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "9:16"
    }
)
response.raise_for_status()
print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.apimart.ai/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "kling-v4",
    prompt: "A paper boat drifts along a gutter on a rainy night, with the gentle sound of rain",
    duration: 5,
    resolution: "720p",
    aspect_ratio: "9:16"
  })
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

## モードの選択

5 つのモードはすべて同じモデル名 `kling-v4` を使用します。入力素材と `omni_reference_task_type` に応じてモードが選択されます。

| モード | 入力方法 |
| - | - |
| テキストから動画 | 画像・動画・音声素材を指定しない |
| 画像から動画 | 開始フレームを指定。終了フレームと最大 8 枚の中間フレームを追加可能 |
| 参照素材から動画 | `video_urls`、`audio_urls`、または `image_with_roles` 内の `reference_image` を指定。`omni_reference_task_type: "reference"` の明示的な指定も可能 |
| 動画編集 | `omni_reference_task_type: "edit"` と入力動画を指定 |
| 動画延長 | `omni_reference_task_type: "extend"` と入力動画を指定 |

`omni_reference_task_type` のデフォルトは `auto` で、省略時と同じです。`reference` を明示的に指定すると、`image_urls` の画像は参照画像として扱われます。

> [!WARNING]
>
> `edit` または `extend` を指定せずに `video_url` だけを渡すと HTTP 400 が返されます。動画を参照素材として使用する場合は `video_urls` を使ってください。

## リクエストヘッダー

**Authorization** `string` *required*

Bearer 認証：`Bearer <token>`。`<token>` は APIMart API Key です。

## リクエストパラメータ

**model** `string` *required*

`kling-v4` を指定してください。

**prompt** `string`

生成または編集する内容の説明。画像から動画の場合は省略可能で、それ以外のモードでは必須です。

参照素材からの生成では、`@Image1`、`@Video1`、`@Audio1` で素材を参照できます。各種類の配列順に 1 から番号が付きます。動画編集では入力動画が `@Video1`、参照画像が `@Image1`、`@Image2` などに対応します。

**duration** `integer`

生成する長さ（秒）。`3`～`30` に対応し、デフォルトは `5` です。

* 動画編集：省略すると、出力の長さは入力動画に従います。
* 動画延長：新しく生成する区間の長さ。元の動画と新しい区間を結合した動画全体が返されます。

**resolution** `string` (default: 720p)

出力解像度は `720p` または `1080p` です。解像度はこのフィールドで指定してください。V4 は `mode` に対応していません。

**aspect\_ratio** `string`

`16:9`、`9:16`、`1:1`、`21:9` に対応。参照素材からの生成では `auto` も使用できます。

| モード | デフォルトの動作 |
| - | - |
| テキストから動画 | `16:9` |
| 画像から動画 | 開始フレームに従う |
| 参照素材から動画 | `auto` |
| 動画編集 | 入力動画に従う |
| 動画延長 | このフィールドは指定不可。元の動画のアスペクト比を維持 |

**image\_urls** `string[]`

画像 URL のリスト。モードによって用途が異なります。

* 画像から動画：1 枚目は開始フレーム、2 枚目は終了フレーム。最大 2 枚です。
* 参照素材から動画・動画編集：最大 10 枚の参照画像。参照画像のみで動画を生成する場合は、`omni_reference_task_type: "reference"` を明示的に指定してください。

素材 URL は外部からアクセス可能である必要があります。

**image\_with\_roles** `object[]`

役割付き画像のリスト。各要素に `url` と `role` を含めます。

| `role` | 用途 |
| - | - |
| `first_frame` | 画像から動画の開始フレーム。必ず 1 枚指定 |
| `last_frame` | 画像から動画の終了フレーム、または動画延長の目標終了フレーム |
| `keyframe` | 画像から動画の中間フレーム。`middle_frame` も使用可能。配列順に使用し、最大 8 枚 |
| `reference_image` | 参照素材から動画を生成するための参照画像 |

画像から動画では、開始・終了・中間フレームの合計は最大 10 枚です。

**first\_frame\_image** `string`

画像から動画の開始フレーム URL。`image_with_roles` の `first_frame`、または `image_urls` の 1 枚目でも指定できます。

**last\_frame\_image** `string`

画像から動画の終了フレーム URL、または動画延長の目標終了フレーム URL。

**video\_urls** `string[]`

参照素材からの生成に使用する動画リスト。最大 5 本、合計で最大 30 秒を使用します。

動画編集・延長では、`video_url` の代わりに動画 URL を 1 件だけ指定することも可能です。`omni_reference_task_type: "edit"` または `"extend"` を指定してください。

**video\_url** `string`

動画編集・延長の入力動画 URL。`omni_reference_task_type: "edit"` または `"extend"` の指定が必要です。

動画編集の入力動画は 3 秒以上が必要です。3 秒未満は HTTP 400、30 秒を超える場合は先頭 30 秒を使用します。

**audio\_urls** `string[]`

参照素材からの生成に使用する音声リスト。最大 3 本、各 5～30 秒です。

参照素材からの生成では、参照画像・動画・音声の合計は最大 15 ファイルです。

**omni\_reference\_task\_type** `string` (default: auto)

`auto`、`reference`、`edit`、`extend` に対応しています。

* `auto`：素材に応じてテキスト・画像・参照素材からの生成を自動選択。省略時と同じです。
* `reference`：参照素材からの生成。`image_urls` の画像を参照画像として扱います。
* `edit`：動画編集。入力動画が必要です。
* `extend`：動画延長。入力動画が必要です。

**audio\_setting** `string`

`origin`（入力動画の音声を維持）と `auto`（音声を新たに生成）に対応。動画編集、または参照動画を含む参照素材からの生成でのみ使用できます。

* 動画編集：デフォルトで元の音声を維持。`auto` で音声を新たに生成します。
* 参照動画を含む参照素材からの生成：デフォルトで音声を新たに生成。`origin` で参照動画の音声を維持します。
* 動画延長：このフィールドは使用できません。元の音声を維持し、新しい区間には自動で音声を生成します。

V4 は常にステレオ音声付きの動画を出力し、音声と映像を同時に生成します。

## リクエスト例

以下の素材 URL はプレースホルダーです。実際に外部からアクセス可能な URL に置き換えてください。

### 画像から動画：開始・終了フレーム

```json theme={null}
{
  "model": "kling-v4",
  "prompt": "The camera slowly moves closer",
  "image_urls": ["https://example.com/start.png", "https://example.com/end.png"]
}
```

1 枚目が開始フレーム、2 枚目が終了フレームです。画像から動画では `prompt` を省略できます。

### 画像から動画：開始・中間・終了フレーム

```json theme={null}
{
  "model": "kling-v4",
  "prompt": "A girl walks from the window to the door, then looks back and smiles",
  "image_with_roles": [
    {"url": "https://example.com/1.png", "role": "first_frame"},
    {"url": "https://example.com/2.png", "role": "keyframe"},
    {"url": "https://example.com/3.png", "role": "keyframe"},
    {"url": "https://example.com/4.png", "role": "last_frame"}
  ],
  "duration": 10
}
```

中間フレームは配列順に使用します。開始フレームは必ず 1 枚指定し、開始・終了・中間フレームの合計は最大 10 枚です。

### 参照素材から動画

```json theme={null}
{
  "model": "kling-v4",
  "prompt": "The girl in @Image1 runs along the beach with the camera movement from @Video1 and background music from @Audio1",
  "image_with_roles": [
    {"url": "https://example.com/girl.png", "role": "reference_image"}
  ],
  "video_urls": ["https://example.com/camera.mp4"],
  "audio_urls": ["https://example.com/bgm.mp3"],
  "aspect_ratio": "auto",
  "duration": 5
}
```

参照画像は最大 10 枚、参照動画は最大 5 本、参照音声は最大 3 本で、合計は最大 15 ファイルです。参照動画は合計最大 30 秒を使用し、参照音声は各 5～30 秒である必要があります。

### 動画編集

```json theme={null}
{
  "model": "kling-v4",
  "prompt": "Change the scene to a snowy winter night",
  "omni_reference_task_type": "edit",
  "video_url": "https://example.com/in.mp4",
  "image_urls": ["https://example.com/style.png"]
}
```

入力動画は 3 秒以上が必要で、30 秒を超える場合は先頭 30 秒を使用します。`duration` と `aspect_ratio` を省略すると、長さとアスペクト比は入力動画に従います。デフォルトで元の音声を維持し、`audio_setting: "auto"` で新しい音声を生成できます。

### 動画延長

```json theme={null}
{
  "model": "kling-v4",
  "prompt": "The camera continues moving forward as the sky grows darker",
  "omni_reference_task_type": "extend",
  "video_url": "https://example.com/in.mp4",
  "duration": 5
}
```

入力動画の最後のフレームから延長します。元の動画と新しい区間を結合した動画全体が返され、課金対象は新しい区間の長さのみです。

`last_frame_image` または `image_with_roles` の `last_frame` で目標終了フレームを指定できます。延長では `aspect_ratio` と `audio_setting` は使用できません。

## タスクの照会

以下のリクエストのタスク ID を、送信時に返された ID に置き換えてください。

```bash theme={null}
curl --request GET \
  --url 'https://api.apimart.ai/v1/videos/generations/<task_id>' \
  --header 'Authorization: Bearer <token>'
```

生成時間の目安：3 秒の 720p 動画は約 3 分、15 秒の動画は約 3.5 分です。

## 料金

秒単位で課金されます。単価は[モデル料金](https://apimart.ai/pricing)をご確認ください。`720p` と `1080p` では単価が異なります。

動画編集と参照動画を含む参照素材からの生成には、動画入力用の単価を適用します。それ以外のモードには通常の生成単価を適用します。

| モード | 課金対象の秒数 |
| - | - |
| テキストから動画、画像から動画、画像または音声のみの参照素材からの生成 | 出力秒数 |
| 動画延長 | 新しい区間の秒数 |
| 動画編集、参照動画を含む参照素材からの生成 | 出力秒数 + max(出力秒数, 入力動画秒数) |

入力動画秒数は各動画の長さを合計して秒単位で切り上げ、最大 30 秒として計算します。例えば、3.04 秒の動画を `duration` なしで編集すると、出力は 4 秒、課金は 4 + 4 = 8 秒です。

動画編集と参照動画を含む参照素材からの生成では、送信時に入力動画の長さを取得します。取得に失敗すると HTTP 400 が返され、課金されません。生成に失敗した場合は全額返金されます。

## 非対応のパラメータ

以下のパラメータまたは値は HTTP 400 を返します。

* `mode`：V4 に `std`、`pro`、`4k` の区分はありません。`resolution` を使用してください。
* `negative_prompt`, `watermark: true`, `audio: false`.
* `multi_shot`, `multi_prompt`, `element_list`, `video_list`.
* `camera_control`, `voice_list`.

## よくあるエラー

| エラー | 対処方法 |
| - | - |
| `video_url needs omni_reference_task_type edit ... or extend` | `video_url` 使用時は `edit` または `extend` を指定。参照動画には `video_urls` を使用 |
| `image-to-video requires exactly 1 first frame` | 開始フレームを必ず 1 枚指定。終了・中間フレームのみでは不可 |
| `first frame, last frame and keyframes together are at most 10 images` | 開始・終了・中間フレームの合計を 10 枚以下にする |
| `reference images, videos and audios together are at most 15 files` | 参照素材の合計を 15 ファイル以下にする |
| `video edit requires an input video of at least 3 seconds` | 3 秒以上の入力動画を使用 |
| `Failed to probe the input video duration` | URL にアクセスでき、有効な動画ファイルであることを確認 |
| `has no std/pro/4k mode` | `mode` を削除して `resolution` を使用 |
| `Could not download the input from ... (HTTP 403)` | 直リンク制限がなく、外部からアクセス可能な素材 URL を使用 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.