> ## 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 Turbo Параметры и порядок использования приведены в соответствие с официальными. Подробное описание параметров см. в официальной документации. ## 1. Обзор В этом документе описано, как использовать возможности генерации видео из текста и из изображения через официальный протокол Kling 3.0 Turbo. Turbo использует тот же официальный протокол, что и стандартный Kling 3.0, структура запросов и ответов идентична; различия касаются только набора возможностей, доступных разрешений и тарификации. Обе возможности работают в асинхронном режиме задач: 1. Вызовите соответствующий API создания. 2. Сохраните `data.id` из ответа на создание. 3. Запрашивайте статус задачи с тем же API Key, который использовался при создании. 4. После успешного выполнения задачи получите и сохраните сгенерированное видео из `outputs`. ### 1.1 Адреса API | Возможность | Создание задачи | Запрос статуса | | - | - | - | | Генерация видео из текста | `POST /v3/kling/text-to-video/kling-3.0-turbo` | `GET /v3/kling/tasks` | | Генерация видео из изображения | `POST /v3/kling/image-to-video/kling-3.0-turbo` | `GET /v3/kling/tasks` | Полный URL в примерах состоит из `https://{api_domain}` и пути из таблицы, где `{api_domain}` — домен API, который вы используете. Turbo предоставляет только генерацию видео из текста и из изображения; Omni-видео и управление движением не поддерживаются. ### 1.2 Аутентификация Все запросы должны содержать API Key. В POST-запросах также необходимо указывать тип содержимого JSON: ``` Authorization: Bearer Content-Type: application/json ``` ### 1.3 Структура ответа `data` в ответе на создание — объект. Основные поля: `id` (ID задачи, сгенерированный системой Kling, используется для последующих запросов), `external_id` (возвращается как эхо `options.external_task_id`; может отсутствовать, если не задан) и `status` (статус задачи после создания, обычно `submitted`). `data` в ответе на запрос — массив. Каждая задача содержит `id`, `external_id`, `status` (`submitted`, `processing`, `succeeded` или `failed`), `message`, `create_time`, `update_time` и `outputs`. Видеорезультат в `outputs` обычно содержит поля `type`, `id`, `url`, `watermark_url` и `duration`. Поле `url` — ссылка на результат без водяного знака, `watermark_url` — ссылка с водяным знаком, `duration` — длительность видео в секундах. ## 2. Генерация видео из текста ### 2.1 Создание задачи ``` POST https://{api_domain}/v3/kling/text-to-video/kling-3.0-turbo ``` Поля запроса: | Поле | Тип | Обязательное | Значение по умолчанию / Допустимые значения | Описание | | - | - | - | - | - | | `prompt` | string | Да | | Текстовый промпт; может содержать положительные и отрицательные описания; максимум 3072 символа, рекомендуется не более 2500 символов | | `settings.resolution` | string | Нет | По умолчанию `720p`; `720p`, `1080p` | Разрешение генерируемого видео | | `settings.aspect_ratio` | string | Нет | По умолчанию `16:9`; `16:9`, `9:16`, `1:1` | Соотношение сторон кадра (ширина:высота) | | `settings.duration` | int | Нет | По умолчанию 5; целое число от 3 до 15 | Длительность генерируемого видео в секундах | | `options.callback_url` | string | Нет | | Адрес для приёма callback-уведомлений при изменении статуса задачи | | `options.external_task_id` | string | Нет | | Пользовательский ID задачи; не заменяет системный ID, может использоваться для запросов, должен быть уникальным в пределах одного пользователя | | `options.watermark_info.enabled` | boolean | Нет | По умолчанию `false` | Нужно ли создавать результат с водяным знаком | Видео с несколькими кадрами создаётся с помощью фиксированного формата `prompt`: «кадр n, m, words; кадр n, m, words;» (разделители — полуширинные символы). Здесь n — номер кадра (от 1 до 6), m — длительность кадра (не менее 1; сумма длительностей всех кадров равна общей длительности видео), words — промпт кадра (не более 512 символов). ### 2.2 Пример создания ```bash theme={null} curl -X POST 'https://{api_domain}/v3/kling/text-to-video/kling-3.0-turbo' \ -H 'Authorization: Bearer ' \ -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", "aspect_ratio": "16:9", "duration": 5 }, "options": { "external_task_id": "turbo-text-20260826-0001" } }' ``` После успешного создания возвращается ID задачи: ```json theme={null} { "code": 0, "message": "success", "request_id": "provider-request-id", "data": { "id": "kling-turbo-text-task-id", "external_id": "turbo-text-20260826-0001", "status": "submitted", "create_time": 1781080778802, "update_time": 1781080794151 } } ``` Сохраните `data.id`. Если `options.external_task_id` не передан, `data.external_id` может отсутствовать в ответе. ### 2.3 Запрос статуса задачи ``` GET https://{api_domain}/v3/kling/tasks?task_ids={task_id} ``` Используйте тот же API Key, что и при создании задачи. Для запроса по пользовательскому ID задачи можно также использовать `external_task_ids`. В каждом запросе нужно указать ровно один из параметров — `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-turbo-text-task-id' \ -H 'Authorization: Bearer ' ``` При успешном выполнении задачи возвращается: ```json theme={null} { "code": 0, "message": "success", "request_id": "provider-request-id", "data": [ { "id": "kling-turbo-text-task-id", "status": "succeeded", "outputs": [ { "type": "video", "url": "https://your-result-cdn.example.com/turbo-text.mp4", "duration": 5 } ] } ] } ``` `status=processing` означает, что задача все ещё выполняется; рекомендуется запрашивать статус каждые 10–30 секунд. `status=failed` означает, что задача не выполнена, и опрос следует прекратить. После успешного выполнения сохраните файл по адресу `outputs[type=video].url`; ссылка для скачивания может быть действительна ограниченное время. ### 2.5 Описание тарификации ``` Стоимость задачи = цена за секунду для соответствующего разрешения × settings.duration ``` Тариф определяется только параметром `settings.resolution` (`720p` или `1080p`). Если `duration` не передан, применяется значение по умолчанию — 5 секунд. Плата списывается при создании задачи на основании запрошенной длительности. Если создание задачи не удалось или конечная генерация завершилась ошибкой, плата автоматически возвращается. Точные тарифы указаны на странице цен того сервиса, который вы используете. ## 3. Генерация видео из изображения ### 3.1 Создание задачи ``` POST https://{api_domain}/v3/kling/image-to-video/kling-3.0-turbo ``` Поля запроса: | Поле | Тип | Обязательное | Значение по умолчанию / Допустимые значения | Описание | | - | - | - | - | - | | `contents` | array | Да | | Коллекция исходных материалов; должна содержать хотя бы один элемент | | `contents[].type` | string | Да | `prompt`, `first_frame` | Тип материала: промпт, первый кадр | | `contents[].text` | string | Нет | | Текстовый промпт при `type=prompt`; не более 2500 символов | | `contents[].url` | string | Нет | | Изображение первого кадра при `type=first_frame`; поддерживается URL или Base64 | | `settings.resolution` | string | Нет | По умолчанию `720p`; `720p`, `1080p` | Разрешение генерируемого видео | | `settings.duration` | int | Нет | По умолчанию 5; целое число от 3 до 15 | Длительность генерируемого видео в секундах | | `options.external_task_id` | string | Нет | | Пользовательский ID задачи; не заменяет системный ID, может использоваться для запросов, должен быть уникальным в пределах одного пользователя | | `options.watermark_info.enabled` | boolean | Нет | По умолчанию `false` | Нужно ли создавать результат с водяным знаком | Поддерживаются изображения `.jpg`, `.jpeg` и `.png`, размер файла не более 50 МБ, ширина и высота не менее 300 пикселей, соотношение сторон от 1:2.5 до 2.5:1. Генерация видео из изображения поддерживает только первый кадр; режимы «первый кадр + последний кадр» и «только последний кадр» пока не поддерживаются. `options.callback_url` также можно передавать; использование аналогично генерации видео из текста. Видео с несколькими кадрами создаётся тем же фиксированным форматом `prompt`. ### 3.2 Пример создания ```bash theme={null} curl -X POST 'https://{api_domain}/v3/kling/image-to-video/kling-3.0-turbo' \ -H 'Authorization: Bearer ' \ -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 }, "options": { "external_task_id": "turbo-image-20260826-0001" } }' ``` При успешном создании возвращается: ```json theme={null} { "code": 0, "message": "success", "request_id": "provider-request-id", "data": { "id": "kling-turbo-image-task-id", "external_id": "turbo-image-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, что и при создании задачи. Вы также можете использовать `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-turbo-image-task-id' \ -H 'Authorization: Bearer ' ``` При успешном выполнении задачи ссылка на видео находится в `outputs[type=video].url`: ```json theme={null} { "code": 0, "message": "success", "request_id": "provider-request-id", "data": [ { "id": "kling-turbo-image-task-id", "status": "succeeded", "outputs": [ { "type": "video", "url": "https://your-result-cdn.example.com/turbo-image.mp4", "duration": 5 } ] } ] } ``` При `status=processing` рекомендуется продолжать опрос каждые 10–30 секунд; при `status=failed` прекратите опрос и исправьте входные данные на основе сообщения об ошибке. ### 3.5 Описание тарификации ``` Стоимость задачи = цена за секунду для соответствующего разрешения × settings.duration ``` Тариф определяется только параметром `settings.resolution` (`720p` или `1080p`). Если `duration` не передан, применяется значение по умолчанию — 5 секунд. Плата списывается при создании задачи на основании запрошенной длительности. Если создание задачи не удалось или конечная генерация завершилась ошибкой, плата автоматически возвращается. Точные тарифы указаны на странице цен того сервиса, который вы используете. ## 4. Частые ошибки и примечания Ошибки API имеют следующую структуру: ```json theme={null} { "code": 1203, "message": "task not found (trace_id: platform-trace-id)", "request_id": "", "data": null } ``` Типичные коды состояния: 400/1200 (недопустимые параметры или тип содержимого; исправьте в соответствии с `message`), 401/1000 (API Key отсутствует или недействителен), 403/1103 (нет прав на выполнение), 404/1203 (задача не найдена или нет прав на её просмотр), 429/1302 (слишком много запросов; снизьте частоту и используйте экспоненциальную паузу), 500/5000, 503/5001, 504/5002 (ошибка сервиса или таймаут; повторите позже, не повторяйте запросы бесконтрольно). Если `message` содержит `trace_id`, обязательно укажите его при обращении в техподдержку. Другие примечания: * В тело запроса не нужно добавлять `model` или `model_name` — версия модели уже содержится в URL. * После создания задачи сохраняйте `data.id`; не принимайте `request_id` за ID задачи. * Максимальный размер тела одного запроса — 64 МБ; для больших изображений рекомендуется использовать публичный URL, доступный для Kling. * URL исходных материалов должен быть публично доступен для Kling и не должен зависеть от внутренней сети, Cookie или временного входа в систему. * При опросе API используйте интервал 10–30 секунд, а также общий таймаут и экспоненциальную задержку. * Таймаут POST-запроса не означает, что задача не была создана; сначала выполните запрос по `external_task_id` и только затем решайте, нужен ли повтор. * После получения статуса успеха сразу сохраните файл по ссылке `outputs[type=video].url` — ссылка на результат может перестать действовать. ## 5. Пример вызова на Python В приведённом примере используется стандартная библиотека `requests`; демонстрируется создание задачи генерации видео из текста и её опрос. Для генерации видео из изображения достаточно заменить API создания и тело запроса. ```python theme={null} import os import time import requests api_domain = os.environ["API_DOMAIN"] api_key = os.environ["PLATFORM_API_KEY"] headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", } payload = { "prompt": "A calm cinematic ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.