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

# Генерация видео Kling v4

> Единая модель kling-4.0 для текста, референсов и начального/промежуточных/конечного кадров

Все три режима используют `kling-4.0`. Путь генерации выбирается по переданным материалам. API асинхронный; после отправки запрашивайте результат по ID задачи платформы.

> [!NOTE]
>
> Используйте API-ключ платформы. В материковом Китае можно заменить `https://toapis.com` на `https://toapis.cn`. Доступность зависит от развернутой конфигурации канала и прав аккаунта.

## Режимы ввода

| Режим | Содержимое запроса |
| - | - |
| Текст в видео | Передайте текст и параметры результата без медиа. |
| Референсы | Используйте `image_urls` / `video_urls` или материалы с reference-ролями. Изображения и видео можно сочетать. |
| Ключевые кадры | Явно задайте `first_frame`, `keyframe`, `last_frame` в `image_with_roles`. Не добавляйте референсные изображения или видео. |

## Параметры запроса

**Authorization** `string` *required*

Авторизация: `Bearer YOUR_API_KEY`.

**model** `string` *required*

Всегда `kling-4.0`. Не меняйте ID модели при переключении режима.

**prompt** `string` *required*

Обязательный непустой текст, до 8000 символов Unicode. Опишите субъект, движение, камеру и связь между материалами.

**duration** `integer` (default: 5)

Целое число от 3 до 30 секунд. По умолчанию 5.

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

`720p` или `1080p`. По умолчанию `720p`. Разрешение выбирается этим полем.

**aspect\_ratio** `string`

`auto`, `16:9`, `9:16`, `1:1`, `21:9`. При отсутствии сохраняется значение провайдера; для автоматического соотношения можно явно передать `auto`.

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

Массив URL референсных изображений, до 10. Позиция не означает начальный/конечный кадр. Количество суммируется с reference-ролями; не дублируйте материалы.

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

Массив URL референсных видео, до 5 вместе с `video_with_roles`.

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

Поля объекта: `url` и `role`. `reference` / `reference_image` обозначают референс. `first_frame`, `keyframe`, `last_frame` обозначают начальный, промежуточный и конечный кадры.

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

Поля объекта: `url` и `role`. Поддерживаются `reference` / `reference_video`.

**metadata** `object`

Логическое поле `keep_original_sound` сохраняет звук референсного видео, например `{"keep_original_sound": true}`. Только для референсного видео. В режиме ключевых кадров запрещено даже значение false.

**client\_business\_id** `string`

Необязательный бизнес-ID клиента, сохраняется в задаче и поддерживается тем же API статуса.

## Правила материалов и валидация

* Используйте общедоступные HTTP(S) URL без имени пользователя и пароля. Локальные файлы сначала загрузите через [загрузку изображений](https://docs.toapis.com/docs/ru/api-reference/uploads/images.md) или [видео](https://docs.toapis.com/docs/ru/api-reference/uploads/videos.md). Не передавайте локальные пути или base64.
* Режим референсов допускает до 10 изображений и 5 видео. Обычные массивы и явные reference-роли суммируются; не отправляйте один материал дважды.
* Нужен хотя бы 1 ключевой кадр. До 1 начального, 1 конечного и 8 промежуточных. Всего не более `min(duration + 1, 10)`. Для 3 секунд до 4 кадров, для 5 до 6, для 9-30 до 10.
* Промежуточные кадры идут в порядке элементов `keyframe` в массиве. Начальный и конечный определяются ролью, а не позицией обычного изображения. Только начальный, только конечный или только промежуточные также включают режим ключевых кадров.
* Ключевые кадры несовместимы с референсами. Не используйте старые Kling `mode`, `audio`, `video_list` и структуры Omni. `audio_with_roles`, `metadata.elements`, `metadata.voices` не поддерживаются.
* Недопустимые параметры, роли, URL, количества и сочетания режимов отклоняются. Исправьте ошибку перед повторной отправкой. Страница не гарантирует пределы размера, кодеков или длины входного видео; учитывайте требования загрузки и провайдера.

## Примеры запросов

### Текст в видео

```json theme={null}
{
  "model": "kling-4.0",
  "prompt": "Волны у берега, плавное приближение камеры, закатный свет",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}
```

### Референсы

```json theme={null}
{
  "model": "kling-4.0",
  "prompt": "Сохранить персонажа с изображения и движение камеры из референсного видео",
  "duration": 10,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "image_urls": [
    "https://example.com/character.png"
  ],
  "video_urls": [
    "https://example.com/motion.mp4"
  ],
  "metadata": {
    "keep_original_sound": true
  }
}
```

### Ключевые кадры

```json theme={null}
{
  "model": "kling-4.0",
  "prompt": "Плавный переход от начального кадра через промежуточную сцену к конечному",
  "duration": 5,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "image_with_roles": [
    {
      "url": "https://example.com/first.png",
      "role": "first_frame"
    },
    {
      "url": "https://example.com/middle-1.png",
      "role": "keyframe"
    },
    {
      "url": "https://example.com/middle-2.png",
      "role": "keyframe"
    },
    {
      "url": "https://example.com/last.png",
      "role": "last_frame"
    }
  ]
}
```

### Отправка задачи

```bash cURL theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-4.0",
  "prompt": "Волны у берега, плавное приближение камеры, закатный свет",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}'
```

```json theme={null}
{
  "id": "task_example",
  "object": "generation.task",
  "model": "kling-4.0",
  "status": "queued",
  "created_at": 1792713600
}
```

## Статус задачи и оплата

Поле `id` ответа является ID задачи платформы. Используйте API ниже вместо task\_id провайдера. Статусы: `queued`, `in_progress`, `completed`, `failed`. См. [статус видео](https://docs.toapis.com/docs/ru/api-reference/tasks/video-status.md) и [Webhook задач](https://docs.toapis.com/docs/ru/api-reference/webhooks/task-webhooks.md).

```bash theme={null}
curl --request GET \
  --url https://toapis.com/v1/videos/generations/YOUR_TASK_ID \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

По умолчанию 5 секунд / 720p. Явно задавайте параметры для контроля результата. Фиксированные цены и соответствие сохранения звука старому тарифу Sound не обещаются. Оплата определяется котировкой аккаунта и полями usage / billing задачи.


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