Kling 3.0 API: миграция, Motion Control и код

Просто заменить строку модели в запросе Kling 2.6 недостаточно. Kling 3.0 уже доступен официально, однако маршруты V3, Turbo, Omni и Motion Control отличаются возможностями и схемами запросов. Надёжнее сначала выбрать нужный маршрут, а затем по очереди подключать аудио, multi-shot и референсы.

Сначала выберите endpoint, потом пишите код

В официальном руководстве Kling VIDEO 3.0 названа преемником VIDEO 2.6 и VIDEO O1: VIDEO 2.6 обновляется до VIDEO 3.0, а VIDEO O1 — до VIDEO 3.0 Omni. В developer API для моделей предусмотрены отдельные операции. Поэтому «Kling 3.0 API» — это семейство точек доступа, а не единый универсальный формат запроса.

Самая частая ошибка при интеграции — смешать упрощённую схему провайдера со схемой прямого Kling API. Рабочий запрос Krea — это пример для конкретной платформы, а не подтверждение того, что те же URL и поля действуют в официальной документации для разработчиков Kling.

Обзор доступных маршрутов есть в руководстве по интеграции Kling API. Здесь разберём именно миграцию на Kling 3.0 и поведение endpoint.

Что меняется при переходе с Kling 2.6 на 3.0

Согласно первичному руководству по моделям Kling, ключевое улучшение связано не только с более высоким разрешением, а с управляемостью, непрерывностью сцены и аудиовизуальной режиссурой. Ниже — возможности, которые Kling относит к этим семействам моделей.

На практике интеграция 2.6, построенная вокруг одного короткого промпта, в 3.0 может превратиться в управляемую последовательность сцен. В руководстве Kling также заявлено лучшее сохранение персонажей, объектов и деталей сцены при движении камеры, но независимый бенчмарк консистентности компания не публикует. Не смешивайте это заявление с тем, что действительно можно проверить в вашем приложении.

Минимальная асинхронная интеграция через Krea

Генерация видео выполняется асинхронно. Приложение должно отправить задачу, сохранить её идентификатор, затем опрашивать статус или принять callback и сохранить готовый результат. Не держите исходный HTTP-запрос открытым, пока модель рендерит видео.

В примере ниже используется публично задокументированный endpoint Kling 3.0 от Krea: структура запроса и поля задачи видны в опубликованном руководстве по Kling 3.0 API. Меняйте URL и имена полей, зависящие от провайдера, только после проверки официальной схемы Kling, с которой планируете работать.

Отправляем задачу на генерацию

import os
import time
import requests

API_KEY = os.environ["KREA_API_KEY"]
BASE_URL = "https://api.krea.ai"

payload = {
    "prompt": (
        "A paper boat crosses a rain-filled city gutter at night, "
        "macro camera, practical street lights, realistic water movement"
    ),
    "duration": 5,
    "mode": "std",
    "aspect_ratio": "16:9",
}

response = requests.post(
    f"{BASE_URL}/generate/video/kling/kling-3.0",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
job = response.json()
job_id = job["job_id"]
print(f"submitted {job_id}")

В документированном ответе Krea присутствует job_id и начальный статус, например scheduled. В примере провайдера для проверки статуса используется отдельный endpoint поиска задачи. До начала опроса сохраните ID задачи в базе вместе с собственным ID заказа.

Опрос с тайм-аутом и сохранение результата

TERMINAL = {"completed", "failed", "cancelled"}

for attempt in range(60):
    status_response = requests.get(
        f"{BASE_URL}/jobs/{job_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=30,
    )
    status_response.raise_for_status()
    job = status_response.json()
    status = job.get("status")

    if status in TERMINAL:
        break

    time.sleep(5)
else:
    raise TimeoutError(f"Kling job did not finish: {job_id}")

if job["status"] != "completed":
    raise RuntimeError(f"Kling job ended as {job['status']}: {job_id}")

video_url = job["result"]["urls"][0]
print(video_url)

В примерах Krea генерация занимала 51 секунду и 2 минуты 3 секунды. Поэтому учитывайте очередь при выборе тайм-аутов, а не обещайте фиксированное время генерации Kling.

В production webhook избавит от постоянного polling. Сверяйте ID задачи с задачей, созданной вашей системой, делайте обработчик идемпотентным и не считайте неподписанный callback самостоятельным доказательством подлинности.

Подключайте возможности 3.0 по одной

Названия параметров различаются между прямым Kling API и хостинг-провайдерами. Сделайте небольшой слой совместимости, а не распространяйте специфичный для провайдера JSON по всему приложению.

Официальное руководство заявляет поддержку нативного аудио, референсов элементов, multi-shot-историй и пяти языков диалогов. Но выбранный API endpoint может предоставлять лишь часть возможностей, доступных всему семейству.

Пример собственного multi-shot payload

В документированной схеме Krea используются временные блоки multi_prompt. Для хостинговой интеграции это удобный паттерн:

{
  "multi_prompt": [
    {
      "prompt": "Wide shot: a lighthouse stands on a calm rocky coast at dusk.",
      "duration": 4
    },
    {
      "prompt": "Storm clouds arrive; waves rise and spray crosses the rocks.",
      "duration": 4
    },
    {
      "prompt": "Night rain begins as the lighthouse beam sweeps toward camera.",
      "duration": 4
    }
  ],
  "duration": 12,
  "generate_audio": true,
  "mode": "std",
  "aspect_ratio": "16:9"
}

Проверяйте, что длительность верхнего уровня равна сумме длительностей всех блоков. Krea сообщает о результате длительностью 12.04 секунды для трёх блоков общей длительностью 12 секунд, поэтому не стоит ожидать математически точной длительности файла вплоть до миллисекунды.

Каждый блок Krea ограничен 512 символами, а вся управляемая последовательность — 15 секундами. Описывайте блок как постановку кадра: субъект, изменение и камера, а не как длинное литературное описание сцены. Если ваш прямой маршрут Kling использует официальную грамматику сцен, сохраните ту же модель таймлайна, но преобразуйте payload на границе адаптера.

Ограничения аудио и языков

В официальном руководстве перечислены китайский, английский, японский, корейский и испанский как поддерживаемые языки диалогов; также заявлены диалекты, акценты, реплики конкретных персонажей и смешанные языковые сцены. Для неподдерживаемого диалога входной текст переводится на английский, поэтому в мультиязычных приложениях нельзя рассчитывать на сохранение любого исходного языка.

Аудио влияет и на стоимость. В опубликованных тарифах Krea std стоит $0.1764 за секунду без аудио и $0.2646 с аудио; для pro указано $0.2352 без аудио и $0.3528 с аудио. Заявленная цена 4K — $0.441 за секунду вне зависимости от наличия аудио. Это цены Krea, а не универсальный тариф Kling API.

Практичный подход к итерациям: сначала рендерить черновики без звука, а затем включать аудио для финального кандидата в std или pro.

Production: стоимость, скорость и обработка ошибок

В официальном потребительском руководстве Kling для VIDEO 3.0 указано 6 кредитов за секунду для 720p без нативного аудио, 8 кредитов за секунду для 1080p без нативного аудио, 9 кредитов за секунду для 720p с аудио и 12 кредитов за секунду для 1080p с аудио. Voice Control добавляет 2 кредита за секунду. Эти цифры показывают относительную стоимость внутри этого руководства; не переводите их в долларовую цену developer API без проверки актуальной страницы тарифов для разработчиков.

Выбор не сводится к вопросу «какая модель дешевле?». Нужно учитывать биллинг и эксплуатационные требования:

Обрабатывайте ошибки по категориям:

1. Повторяйте временные ошибки провайдера с ограниченной экспоненциальной задержкой.
2. Не повторяйте запросы с некорректными параметрами, пока адаптер не исправит payload.
3. Храните на стороне клиента ключ идемпотентности или ID заказа, чтобы тайм-аут сети не создал незаметную дублирующую задачу.
4. Устанавливайте жёсткий лимит в долларах или кредитах для пакетной генерации.
5. Скачивайте или копируйте результат в долговременное хранилище до истечения временного URL провайдера.
6. Логируйте вместе вариант модели, длительность, настройки аудио, уровень разрешения и провайдера: для учёта расходов одной записи «Kling 3.0» недостаточно.

Чек-лист миграции с Kling 2.6 на 3.0

1. Инвентаризируйте текущие вызовы 2.6. Зафиксируйте ID моделей, входные изображения, начальный и конечный кадры, длительность, аудио и поведение callback.
2. Выберите маршрут семейства 3.0. V3 подходит для кинематографичной генерации по промпту, Turbo — для ускоренного маршрута, Omni — для мультимодального пути в стиле O1, Motion Control — для задач с референсом движения.
3. Создайте адаптер провайдера. Спрячьте схемы прямого Kling, Krea и других хостинговых сервисов за отдельными преобразователями.
4. Сначала перенесите минимальный запрос. Проверьте пятисекундную генерацию без звука в 16:9, прежде чем добавлять аудио или multi-shot-контролы.
5. Добавляйте по одному контролу на тест. Сначала проверьте длительность, затем аудио, затем направление сцен, затем референсы. Так проще найти проблемное поле.
6. Протестируйте конечные состояния. Покройте сценарии успеха, ошибки, отмены, тайм-аута, дублирующего callback и истёкшего URL результата.
7. Проведите теневой запуск с расчётом стоимости. Сравните фиксированный набор промптов на 2.6 и 3.0 при одинаковой длительности и уровне результата, а затем решите, оправдывает ли новый маршрут прирост качества или управляемости.

Миграцию можно считать завершённой, когда приложение способно откатить ID модели без изменений в бизнес-логике, контроле биллинга и обработке результатов.

FAQ по Kling 3.0 API

Есть ли официальный API для Kling 3.0?

Да. В официальной документации Kling для разработчиков есть API-страницы для конкретных моделей 3.0, а в первичном руководстве VIDEO 3.0 названа преемником VIDEO 2.6. Точную схему endpoint следует смотреть в актуальной developer-консоли, поскольку часть страниц рендерится на клиенте.

Motion Control — это параметр Kling 3.0?

Не стоит этого предполагать. Motion Control — специализированная возможность со своей страницей модели в экосистеме Kling. Используйте операцию и схему входных данных, задокументированные выбранным провайдером, вместо добавления непроверенного поля motion_control в обычный text-to-video запрос.

Какую длительность поддерживает Kling VIDEO 3.0?

Согласно официальному руководству по модели, VIDEO 3.0 поддерживает гибкую длительность от 3 до 15 секунд. У конкретного хостингового или Turbo-маршрута ограничения могут быть уже, поэтому проверяйте выбранный endpoint.

Поддерживает ли Kling 3.0 нативное аудио?

Да, это заявлено в официальном руководстве VIDEO 3.0: там описаны реплики конкретных персонажей, несколько языков, диалекты и акценты. Опциональность аудио и его тарификация зависят от endpoint или схемы провайдера.

Kling 3.0 Omni — это то же самое, что стандартный Kling 3.0?

Нет. Kling позиционирует VIDEO 3.0 как преемника 2.6, а VIDEO 3.0 Omni — как преемника O1. На страницах провайдеров они могут быть представлены разными ID моделей и разными контролами референсов или голоса.

Можно ли оплачивать API-вызовы веб-подпиской Kling?

Считайте потребительские подписки и биллинг developer API разными системами, пока актуальная документация аккаунта не утверждает обратное. Для API-маршрута обычно нужны отдельные аккаунт разработчика, ключ и настройка оплаты.

Полезная граница миграции проста: сохраните жизненный цикл задач из интеграции 2.6, замените адаптер, зависящий от модели, и проверяйте каждый новый контрол 3.0 именно на том маршруте, который его обслуживает. Это помогает избежать самого дорогого типа ошибки: интеграция успешно отправляет запросы, но незаметно использует не тот вариант модели, режим аудио или уровень тарификации.