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

# Kling 3.0 & 3.0 Omni

パラメータと使用方法は公式仕様に合わせています。詳細なパラメータは公式ドキュメントを直接参照してください。

## 1. 概要

このドキュメントでは、Kling 3.0 純正プロトコルを使用して、テキストからビデオ、画像からビデオ、Omni ビデオ、モーションコントロール機能を利用する方法を説明します。

4つの機能はすべて非同期タスクモードを採用しています：

1. 対応する作成インターフェースを呼び出します。
2. 作成レスポンスの `data.id` を保存します。
3. タスク作成時に使用した同じ API Key でタスクのステータスを照会します。
4. タスクが成功したら、`outputs` から生成されたビデオを取得して保存します。

### 1.1 インターフェースアドレス

| 機能 | タスク作成 | タスク照会 |
| - | - | - |
| テキストからビデオ | `POST /v3/kling/text-to-video/kling-3.0` | `GET /v3/kling/tasks` |
| 画像からビデオ | `POST /v3/kling/image-to-video/kling-3.0` | `GET /v3/kling/tasks` |
| Omni ビデオ | `POST /v3/kling/omni-video/kling-3.0-omni` | `GET /v3/kling/tasks` |
| モーションコントロール | `POST /v3/kling/motion-control/kling-3.0` | `GET /v3/kling/tasks` |

このドキュメントの例における完全なアドレスは、`https://{api_domain}` に表のインターフェースパスを加えたものです。`{api_domain}` はお使いの API ドメインです。

### 1.2 認証

すべてのリクエストには API Key が必要です。POST リクエストでは JSON コンテンツタイプも指定する必要があります：

```
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
```

### 1.3 レスポンス構造

作成レスポンスの `data` はオブジェクトです。一般的なフィールドは以下のとおりです：

| フィールド | タイプ | 説明 |
| - | - | - |
| `id` | string | Kling システムが生成したタスク ID。後続の照会に使用します |
| `external_id` | string | `options.external_task_id` のエコーバック。未設定の場合は返されないことがあります |
| `status` | string | 作成後のタスクステータス。通常は `submitted` |

照会レスポンスの `data` は配列で、各タスクには以下のフィールドが含まれます：

| フィールド | タイプ | 説明 |
| - | - | - |
| `id` | string | システムが生成したタスク ID |
| `external_id` | string | 呼び出し元が定義したタスク ID（ある場合） |
| `status` | string | `submitted`、`processing`、`succeeded`、`failed` のいずれか |
| `message` | string | タスクステータス情報。失敗時は失敗理由（ある場合）を含みます |
| `create_time` | integer | 作成時間。Unix ミリ秒タイムスタンプ（ある場合） |
| `update_time` | integer | 更新時間。Unix ミリ秒タイムスタンプ（ある場合） |
| `outputs` | array | 生成結果。成功したタスクには通常 `type=video` の結果が 1 つ含まれます |

`outputs` 内のビデオ結果に含まれる一般的なフィールドは、`type`、`id`、`url`、`watermark_url`、`duration` です。このうち `url` は透かしなしの結果アドレス、`watermark_url` は透かし入りの結果アドレス、`duration` はビデオの長さ（秒）です。

## 2. テキストからビデオ

公式パラメータの説明：Text to Video

### 2.1 タスク作成

```
POST https://{api_domain}/v3/kling/text-to-video/kling-3.0
```

一般的なリクエストフィールド：

| フィールド | タイプ | 必須 | 説明 |
| - | - | - | - |
| `prompt` | string | 必須 | ビデオ生成のプロンプト。空にはできません。最大 3072 文字 |
| `settings.multi_shot` | boolean | 任意 | マルチショットビデオを生成するかどうか。デフォルトは `true` |
| `settings.resolution` | string | 任意 | `720p`、`1080p`、`4k` のいずれか。デフォルトは `720p` |
| `settings.aspect_ratio` | string | 任意 | `16:9`、`9:16`、`1:1` のいずれか。デフォルトは `16:9` |
| `settings.audio` | string | 任意 | `off` または `native`。デフォルトは `off` |
| `settings.duration` | integer | 任意 | 3〜15 秒。デフォルトは 5 秒 |
| `options.callback_url` | string | 任意 | タスクステータスが変化したときにコールバック通知を受け取るアドレス |
| `options.external_task_id` | string | 任意 | カスタムタスク ID |
| `options.watermark_info.enabled` | boolean | 任意 | 透かし入りの結果を生成するかどうか。デフォルトは `false` |

`multi_shot=true` の場合、Kling 公式のフォーマットに従ってプロンプトでマルチショットを記述できます。各ショットの長さの合計がビデオの総時間と等しくなる必要があります。

### 2.2 作成例

```bash theme={null}
curl -X POST 'https://{api_domain}/v3/kling/text-to-video/kling-3.0' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "A cinematic tracking shot of a red sports car driving along a coastal road at sunset",
    "settings": {
      "resolution": "1080p",
      "duration": 5,
      "audio": "native"
    },
    "options": {
      "external_task_id": "text-video-20260826-0001"
    }
  }'
```

作成が成功すると、タスク ID が返されます：

```json theme={null}
{
  "code": 0,
  "message": "success",
  "request_id": "provider-request-id",
  "data": {
    "id": "kling-text-task-id",
    "external_id": "text-video-20260826-0001",
    "status": "submitted",
    "create_time": 1781080778802,
    "update_time": 1781080794151
  }
}
```

### 2.3 タスク照会

```
GET https://{api_domain}/v3/kling/tasks?task_ids={task_id}
```

`data.id` を保存してください。`options.external_task_id` を渡さなかった場合、`data.external_id` は返されないことがあります。

タスク作成時に使用した同じ API Key を使用してください。タスク ID が存在しないかアクセスできない場合、`task not found` が返されます。

`external_task_ids` を使用してカスタムタスク ID を照会することもできます：

```
GET https://{api_domain}/v3/kling/tasks?external_task_ids={external_task_id}
```

`task_ids` と `external_task_ids` は、毎回いずれか 1 つだけを指定する必要があります。どちらも英語のカンマ区切りで 1〜50 個の ID を指定でき、レスポンスの `data` は配列となり、リクエスト ID の順序が維持されます。

### 2.4 照会例

```bash theme={null}
curl -X GET 'https://{api_domain}/v3/kling/tasks?task_ids=kling-text-task-id' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'
```

タスクが成功すると返されます：

```json theme={null}
{
  "code": 0,
  "message": "success",
  "request_id": "provider-request-id",
  "data": [
    {
      "id": "kling-text-task-id",
      "status": "succeeded",
      "outputs": [
        {
          "type": "video",
          "url": "https://your-result-cdn.example.com/text-video.mp4",
          "duration": 5
        }
      ]
    }
  ]
}
```

`status=processing` はタスクがまだ実行中であることを示します。10〜30 秒間隔での照会を推奨します。`status=failed` はタスクが失敗したことを示すため、ポーリングを続けないでください。タスクが成功したら、`outputs[type=video].url` に対応するファイルをすぐに保存してください。ダウンロードアドレスには有効期限がある場合があります。

### 2.5 課金について

```
タスク費用 = 対応する解像度とオーディオ帯の1 秒あたりの単価 × settings.duration
```

価格帯は `settings.resolution` と `settings.audio` によって決まります。例えば、`1080p`、`audio=native`、`duration=5` の場合の費用は「1080p ネイティブオーディオ帯の1 秒あたりの単価 × 5 秒」です。`duration` を渡さなかった場合はデフォルトの 5 秒で課金されます。

タスク作成時にリクエスト時間に応じて課金されます。タスクの作成に失敗した場合、または最終的な生成に失敗した場合、費用は自動的に返金されます。具体的な単価は、ご利用中のサービスの価格ページをご確認ください。

## 3. 画像からビデオ

公式パラメータの説明：Image to Video

### 3.1 タスク作成

```
POST https://{api_domain}/v3/kling/image-to-video/kling-3.0
```

一般的なリクエストフィールド：

| フィールド | タイプ | 必須 | 説明 |
| - | - | - | - |
| `contents` | array | 必須 | マルチモーダルコンテンツのリスト。少なくとも 1 つを含む必要があります |
| `contents[].type` | string | 必須 | `prompt`、`first_frame`、`last_frame`、`element` のいずれか |
| `settings.resolution` | string | 任意 | `720p`、`1080p`、`4k` のいずれか。デフォルトは `720p` |
| `settings.multi_shot` | boolean | 任意 | マルチショットビデオを生成するかどうか。デフォルトは `true` |
| `settings.audio` | string | 任意 | `off` または `native`。デフォルトは `off` |
| `settings.duration` | integer | 任意 | 3〜15 秒。デフォルトは 5 秒 |
| `options.callback_url` | string | 任意 | タスクステータスが変化したときにコールバック通知を受け取るアドレス |
| `options.external_task_id` | string | 任意 | カスタムタスク ID |
| `options.watermark_info.enabled` | boolean | 任意 | 透かし入りの結果を生成するかどうか。デフォルトは `false` |

`contents` の子項目フィールド：

| type | 必須フィールド | 説明 |
| - | - | - |
| `prompt` | `text` | テキストプロンプト。最大 3072 文字 |
| `first_frame` | `url` | 最初のフレーム画像。URL または Base64 に対応。必須 |
| `last_frame` | `url` | 最後のフレーム画像。URL または Base64 に対応。末尾フレームのみは非対応のため、最初のフレームも同時に提供する必要があります |
| `element` | `element_id`、`id` | 主体 ID と、プロンプト内でその主体を参照するためのインデックス ID。同じタスク内で `id` を重複させることはできません。最大 3 つの主体を指定できます |

画像は `.jpg`、`.jpeg`、`.png` に対応しており、ファイルは 50 MB 以下、幅と高さは 300 ピクセル以上、アスペクト比は 1:2.5 から 2.5:1 の間である必要があります。

### 3.2 作成例

```bash theme={null}
curl -X POST 'https://{api_domain}/v3/kling/image-to-video/kling-3.0' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [
      {
        "type": "prompt",
        "text": "The subject turns toward the camera while the wind moves naturally through the scene"
      },
      {
        "type": "first_frame",
        "url": "https://your-cdn.example.com/first-frame.png"
      }
    ],
    "settings": {
      "resolution": "1080p",
      "duration": 5,
      "audio": "off"
    },
    "options": {
      "external_task_id": "image-video-20260826-0001"
    }
  }'
```

作成が成功すると、`data.id` が後続の照会に使用するタスク ID になります：

```json theme={null}
{
  "code": 0,
  "message": "success",
  "request_id": "provider-request-id",
  "data": {
    "id": "kling-image-task-id",
    "external_id": "image-video-20260826-0001",
    "status": "submitted",
    "create_time": 1781080778802,
    "update_time": 1781080794151
  }
}
```

### 3.3 タスク照会

作成レスポンスの `data.id` を使用してタスクを照会します：

```
GET https://{api_domain}/v3/kling/tasks?task_ids={task_id}
```

`task_ids` で照会する場合は、タスク作成時に使用した同じ API Key を使用してください。作成時に渡した `options.external_task_id` を `external_task_ids` で照会することもできます。照会パラメータは、英語のカンマで区切った 1〜50 個の ID に対応しています。

### 3.4 照会例

```bash theme={null}
curl -X GET 'https://{api_domain}/v3/kling/tasks?task_ids=kling-image-task-id' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'
```

タスクが成功すると、ビデオアドレスは `outputs[type=video].url` にあります：

```json theme={null}
{
  "code": 0,
  "message": "success",
  "request_id": "provider-request-id",
  "data": [
    {
      "id": "kling-image-task-id",
      "status": "succeeded",
      "outputs": [
        {
          "type": "video",
          "url": "https://your-result-cdn.example.com/image-video.mp4",
          "duration": 5
        }
      ]
    }
  ]
}
```

`status=processing` の場合は 10〜30 秒間隔で照会を続けることを推奨します。`status=failed` の場合はポーリングを停止し、エラーメッセージに基づいて入力を修正してください。

### 3.5 課金について

```
タスク費用 = 対応する解像度とオーディオ帯の1 秒あたりの単価 × settings.duration
```

価格帯は `settings.resolution` と `settings.audio` によって決まります。`duration` を渡さなかった場合はデフォルトの 5 秒で課金されます。タスク作成時にリクエスト時間に応じて課金されます。タスクの作成に失敗した場合、または最終的な生成に失敗した場合、費用は自動的に返金されます。具体的な単価は、ご利用中のサービスの価格ページをご確認ください。

## 4. Omni ビデオ

公式パラメータの説明：Omni Video

### 4.1 タスク作成

```
POST https://{api_domain}/v3/kling/omni-video/kling-3.0-omni
```

一般的なリクエストフィールド：

| フィールド | タイプ | 必須 | 説明 |
| - | - | - | - |
| `contents` | array | 必須 | マルチモーダルコンテンツ |


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