> ## 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. Обзор

В этом документе описано, как использовать возможности генерации видео из текста, видео из изображения, Omni-видео и управления движением через оригинальный протокол Kling 3.0.

Все четыре возможности работают в асинхронном режиме задач:

1. Вызовите соответствующий интерфейс создания задачи.
2. Сохраните `data.id` из ответа на создание.
3. Запросите статус задачи, используя тот же API-ключ, что и при создании задачи.
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-ключ. POST-запросы также должны указывать тип содержимого JSON:

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

### 1.3 Структура ответа

`data` в ответе на создание — объект. Часто встречающиеся поля:

| Поле | Тип | Описание |
| - | - | - |
| `id` | string | ID задачи, сгенерированный системой Kling, используется для последующих запросов |
| `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` |

В видеорезультате внутри `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 | Нет | Адрес для получения callback-уведомлений при изменении статуса задачи |
| `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-ключ, что и при создании задачи. Если 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 до 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 Описание тарификации

```
任务费用 = 对应分辨率和音频档位的每秒单价 × settings.duration
```

Ценовой тариф определяется параметрами `settings.resolution` и `settings.audio`. Например, при `1080p`, `audio=native` и `duration=5` стоимость равна «цена за секунду тарифа 1080p с аудио native × 5 секунд». Если `duration` не передан, расчёт выполняется по умолчанию за 5 секунд.

Средства списываются при создании задачи за запрошенную длительность; в случае неудачного создания или финальной генерации стоимость автоматически возвращается. Актуальные тарифы см. на странице цен используемого вами сервиса.

## 3. Видео из изображения

Официальное описание параметров: Image to Video

### 3.1 Создание задачи

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

Часто используемые поля запроса:

| Поле | Тип | Обязательность | Описание |
| - | - | - | - |
| `contents` | array | Да | Список мультимодального содержимого, должен содержать хотя бы один элемент |
| `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 | Нет | Адрес для получения callback-уведомлений при изменении статуса задачи |
| `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 МБ, ширина и высота не менее 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"
    }
  }'
```

После успешного создания возвращается 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-ключ, что и при создании задачи. Также можно запросить задачу по `external_task_ids`, передав `options.external_task_id`, указанный при создании. Параметр запроса поддерживает от 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 Описание тарификации

```
任务费用 = 对应分辨率和音频档位的每秒单价 × 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 | Да | Список мультимодального содержимого, должен содержать хотя бы один элемент |
| `contents[].type` | string | Да | `prompt`, `first_frame`, `last_frame`, `refer_image`, `feature_video`, `base_video` или `element` |
| `settings.resolution` | string | Нет | `720p`, `1080p` или `4k`, по умолчанию `720p` |
| `settings.multi_shot` | boolean | Нет | Нужно ли генерировать многокадровое видео, по умолчанию `true` |
| `settings.aspect_ratio` | string | Нет | `16:9`, `9:16` или `1:1`, по умолчанию `16:9`; обязателен, если нет изображения первого кадра и нет опорного видео |
| `settings.audio` | string | Нет | `off`, `native` или `original`, по умолчанию `off` |
| `settings.duration` | integer | Нет | 3–15 секунд, по умолчанию 5 секунд |
| `options.callback_url` | string | Нет | Адрес для получения callback-уведомлений при изменении статуса задачи |
| `options.external_task_id` | string | Нет | Пользовательский ID задачи |
| `options.watermark_info.enabled` | boolean | Н | |


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