Kling API: официальный доступ и агрегаторы — руководство по интеграции (2026)

Запрос к Kling — это не один универсальный API-вызов. Видеомодель Kling от Kuaishou доступна через официальную Open Platform, а также через агрегаторы вроде WaveSpeedAI, KIE и fal. У каждого варианта свои ключи, ID моделей, структура запросов и биллинг. Общая для всех схема одна: отправить асинхронную задачу, сохранить её ID, дождаться финального статуса и забрать результат без бесконтрольных повторных запусков.

Сначала выберите платформу, потом SDK

У Kling есть официальная Open Platform, однако по запросу «Kling API» находятся и независимые шлюзы. Ориентируйтесь не только на название модели, а на доступность поставщика, скорость интеграции и контроль расходов.

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

Официальный сценарий Kling

Официальная Open Platform — выбор, если закупочные процедуры требуют прямых отношений с Kuaishou или нужен доступ к моделям от первого лица. В актуальной документации отдельно описаны создание учётных данных, запуск задач, callbacks, правила параллельности и коды ошибок. Не пытайтесь подставить сюда payload от агрегатора — используйте официальный маршрут:

1. Создайте или получите официальные учётные данные по руководству по аутентификации, а затем храните токен только на сервере.
2. Отправьте описанную асинхронную видеозадачу в эндпоинт нужной модели, используя поля из официального справочника.
3. Добавьте callback_url, если хотите получать изменения статуса автоматически. В документации перечислены состояния submitted, processing, succeed и failed; при ошибке сохраняйте task_status_msg.
4. Локально соблюдайте текущий лимит параллельных задач для аккаунта. В официальном гайде превышение описано как HTTP 429 с бизнес-кодом 1303, а не как работа, которую Kling обязательно поставит в очередь за вас.
5. Используйте официальный справочник кодов ошибок, чтобы отличать неверные учётные данные, некорректные параметры, исчерпанные ресурсы, блокировки по политике и временные серверные сбои.

В доступной версии официальной страницы аутентификации контент рендерится на клиенте, поэтому здесь не приводится непроверенный пример генерации токена. Возьмите актуальный формат ключа непосредственно с этой страницы и не рассчитывайте, что заголовок от WaveSpeed, KIE или fal подойдёт без изменений.

При этом официальный жизненный цикл можно привести к единой внутренней модели, не угадывая точный payload:

official_credential = get_from_kling_console()
task = POST official_model_endpoint(official_credential, documented_input)
store(task.task_id)
wait_for_callback_or_query_status(task.task_id)
if status == "succeed": save_output(task_result.videos)
else: classify(http_status, business_code, task_status_msg)

Это схема жизненного цикла, а не готовый для вставки эндпоинт. Точный формат токена, путь, поля запроса и контейнер ответа сверяйте с официальной документацией по ссылке.

Когда агрегатор удобнее

Агрегаторы часто быстрее для прототипов, которым нужен доступ pay-as-you-go, один аккаунт для нескольких моделей или SDK провайдера. Но именно они управляют ключом, схемой, очередью, URL результата и иногда сроком хранения файлов. Прежде чем повторять запрос, определите, на каком уровне произошёл сбой.

Что можно унифицировать в Kling API

В продакшене детали конкретного поставщика стоит скрыть за одной внутренней функцией. Независимо от выбранного маршрута приложению нужно выполнять одни и те же шаги:

1. Проверять промпт и URL медиа до списания кредитов.
2. Отправлять задачу на генерацию видео с ID модели, специфичным для провайдера.
3. Сразу сохранять возвращённый ID задачи или prediction.
4. Принимать callback либо опрашивать эндпоинт результата, пока задача не перейдёт в финальное состояние.
5. Сохранять URL результата, провайдера, модель, параметры и метаданные о стоимости.
6. Прекращать повторы, если провайдер сообщает об ошибке, отмене, тайм-ауте или удалении.

Ваш слой абстракции может возвращать собственный нормализованный объект, например такой:

{
  "provider": "wavespeed",
  "job_id": "provider-job-id",
  "status": "queued",
  "output_url": null,
  "error": null
}

Параметры, которые легко перенести между провайдерами

Сами понятия совпадают, но названия полей — нет. generate_audio, sound и generate_audio: true могут описывать схожее поведение в разных сервисах. Для каждого провайдера нужен отдельный адаптер схемы.

Параметры, которые нельзя переносить напрямую

Первое типичное препятствие — ID моделей. kling-3.0, kling-3.0/video, fal-ai/kling-video/v3/standard/text-to-video и kwaivgi/kling-v3.0-std/text-to-video обозначают разные API-маршруты, а не взаимозаменяемые значения.

То же касается заголовков аутентификации, имён callback-полей, URL результатов, значений статуса задачи и правил загрузки файлов. Если клиент жёстко ожидает статус одного провайдера, например completed, он может неверно интерпретировать ответ другого со статусом succeeded или failed.

Три реальные формы запросов

Эти примеры для конкретных провайдеров наглядно показывают, почему универсального эндпоинта Kling не существует.

WaveSpeedAI: ID prediction и опрос результата

WaveSpeedAI документирует Kling 3.0 Standard text-to-video по следующему адресу:

POST https://api.wavespeed.ai/api/v3/kwaivgi/kling-v3.0-std/text-to-video

Запрос использует Bearer-токен. Эндпоинт возвращает ID prediction, а результат доступен по адресу:

GET https://api.wavespeed.ai/api/v3/predictions/{prediction_id}/result

Минимальный сценарий cURL выглядит так:

export WAVESPEED_API_KEY="replace_me"

submit=$(curl --fail-with-body -s \
  -X POST \
  "https://api.wavespeed.ai/api/v3/kwaivgi/kling-v3.0-std/text-to-video" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cinematic sunrise over a futuristic cityscape",
    "duration": 5,
    "aspect_ratio": "16:9",
    "cfg_scale": 0.5,
    "shot_type": "customize"
  }')

prediction_id=$(printf '%s' "$submit" | jq -r '.data.id // .id')

curl -s \
  "https://api.wavespeed.ai/api/v3/predictions/$prediction_id/result" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY"

В документации модели WaveSpeedAI указаны ролики длительностью 3–15 секунд, соотношения 16:9, 9:16 и 1:1, а также значение cfg_scale по умолчанию 0.5. В таблице цен Standard указано $0.42 за 5-секундный ролик без звука и $0.63 со звуком. Это актуальный срез цен конкретного провайдера, а не универсальный тариф Kling.

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

KIE: createTask и callback либо запрос статуса

KIE использует общий эндпоинт для создания задач:

POST https://api.kie.ai/api/v1/jobs/createTask

Идентификатор модели Kling 3.0 — kling-3.0/video, а для аутентификации используется Bearer-токен. Компактный payload для одной сцены выглядит так:

{
  "model": "kling-3.0/video",
  "callBackUrl": "https://example.com/webhooks/kie",
  "input": {
    "prompt": "A paper boat moving across a sunlit stream, gentle camera push-in",
    "duration": "5",
    "aspect_ratio": "16:9",
    "mode": "std",
    "sound": false,
    "multi_shots": false
  }
}

KIE документирует видео длительностью 3–15 секунд, выходные соотношения 16:9, 9:16 и 1:1, а также до пяти сцен в режиме multi-shot. Для каждой multi-shot-сцены можно задать от 1 до 12 секунд. Элементы изображений используют 2–4 URL файлов JPG или PNG, при документированном максимуме 10 MB на изображение; для видеоэлемента используется один URL MP4 или MOV размером до 50 MB.

Callback необязателен, но KIE рекомендует его для продакшена. Вебхук должен проверять подпись, когда она доступна, быстро подтверждать получение и отправлять результат задачи в очередь. Опрос статуса задачи оставьте как резервный вариант на случай пропущенных callbacks.

В документации KIE выделены отдельные коды частых ошибок: включая 401 при неверной аутентификации, 402 при недостатке кредитов, 422 при ошибках валидации и 429 при rate limit. Логируйте код вместе с сообщением: общего текста «Kling failed» недостаточно, чтобы понять, безопасен ли повтор.

fal: эндпоинт модели и клиент очереди

fal предоставляет Kling 3.0 через ID эндпоинтов, привязанные к конкретным моделям. Для Standard text-to-video документирован следующий ID:

fal-ai/kling-video/v3/standard/text-to-video

В raw API используется заголовок Authorization: Key $FAL_KEY. В примерах для Python и JavaScript применяется клиент fal с поддержкой очереди — обычно это проще, чем самостоятельно писать цикл опроса.

import { fal } from "@fal-ai/client";

fal.config({ credentials: process.env.FAL_KEY });

const result = await fal.subscribe(
  "fal-ai/kling-video/v3/standard/text-to-video",
  {
    input: {
      prompt: "A paper boat moving across a sunlit stream, gentle camera push-in",
      duration: 5,
      aspect_ratio: "16:9",
      generate_audio: false,
      negative_prompt: "blur, distort, low quality",
      cfg_scale: 0.5
    },
    logs: true
  }
);

console.log(result.data.video.url);

fal документирует диапазон 3–15 секунд, три соотношения сторон для text-to-video и диапазон cfg_scale от 0 до 1 со значением по умолчанию 0.5. В схеме Standard сказано, что prompt и multi_prompt — альтернативы: передавайте одно поле, не оба. Документированное значение generate_audio по умолчанию — true, поэтому задавайте его явно, если бюджет или пайплайн постобработки рассчитан на ролики без звука.

fal также документирует отдельные ID для image-to-video и motion-control. Не пытайтесь вывести эти ID простой заменой text-to-video в строке — сначала проверьте актуальный справочник модели.

Квоты, ожидание в очереди и защита кредитов

Единой публичной квоты Kling, действующей одновременно для официальной платформы, WaveSpeedAI, KIE и fal, нет. Параллельность, rate limits, остаток кредитов, списания за неуспешные задачи и хранение результатов определяет выбранный вами маршрут. Храните эти значения в конфигурации провайдера, а не в константах с названием KLING_LIMIT.

Один пользователь точно сформулировал операционный риск, который обычно скрывается за общим советом «настройте ретраи»:

«Kling списывает деньги за каждую генерацию, а у очереди есть реальная задержка. Первым делом я бы добавил лимит расходов и параллельности — иначе агент, который повторяет генерацию из-за неудачного кадра, незаметно сожжёт кредиты за ночь». — @ukrroot on X

Ограничители бюджета и параллельности

Внедрите эти механизмы до того, как разрешите агенту или batch-воркеру вызывать Kling:

1. Максимум задач в работе: Установите лимит для каждого провайдера вместо запуска отдельной задачи на каждый промпт.
2. Бюджет на задачу: До отправки оценивайте длительность, тариф, аудио и число результатов.
3. Бюджет повторов: Выборочно повторяйте транспортные ошибки; не повторяйте ошибки валидации, аутентификации и недостатка кредитов.
4. Журнал задач: Записывайте ID задачи провайдера до любого последующего запроса, чтобы перезапуск воркера не создал дублирующую генерацию.
5. Политика финальных состояний: Считайте задачи с ошибкой, отменой, тайм-аутом или удалением завершёнными, если провайдер прямо не указывает, что их можно безопасно отправить заново.
6. Оповещение по кредитам: Останавливайте очередь, когда баланс или прогнозируемые траты пересекают порог.
7. Защита ключей и результатов: Храните ключи на сервере, сразу отзывайте скомпрометированные ключи и копируйте готовые видео в надёжное хранилище.

Пятисекундный тест в Standard может стоить недорого по сравнению с 15-секундной задачей Pro или роликом со звуком, но само понятие «недорого» зависит от провайдера. Перед выбором тарифа по умолчанию изучите актуальную страницу модели.

Что измерять перед запуском в продакшен

Отслеживайте эти поля для каждого запроса:

Считайте задержки и квоты характеристиками конкретного эндпоинта: в открытых источниках нет единого SLA для разных провайдеров.

FAQ по Kling API

У Kling есть официальный API?

Да. Kling поддерживает раздел документации для разработчиков официальной Open Platform. Официальный маршрут и сторонние шлюзы — это разные сервисы, поэтому актуальные учётные данные, квоты и цены проверяйте в документации Kling Open Platform.

Существует единый универсальный эндпоинт Kling API?

Нет. Официальная платформа, WaveSpeedAI, KIE и fal используют разные пути эндпоинтов, ID моделей, заголовки аутентификации и контейнеры ответов. Сделайте адаптер для каждого провайдера, а не предполагайте, что kling-3.0 валиден везде.

Выбирать polling или webhooks?

Если провайдер поддерживает callback или webhook, используйте его в продакшене. Но polling стоит сохранить для локальных тестов и восстановления после пропущенных callbacks. Добавьте экспоненциальную задержку, общий лимит ожидания и идемпотентность, чтобы запоздалый callback не создал дублирующую запись.

Какие длительности и соотношения сторон поддерживаются?

В нескольких актуальных документациях агрегаторов для Kling 3.0 указаны клипы длительностью 3–15 секунд и соотношения 16:9, 9:16 и 1:1. Отдельные эндпоинты могут отличаться, поэтому сверяйтесь со страницей выбранной модели и не считайте эти значения универсальным контрактом от первого лица.

Меняется ли стоимость при включении аудио?

Как правило, да. WaveSpeedAI указывает множитель 1.5× за звук для своего эндпоинта Kling 3.0 Standard, а fal и KIE предоставляют аудио или звук как параметры запроса. Проверяйте актуальную страницу биллинга выбранного эндпоинта и задавайте флаг явно.

Почему повтор запроса привёл к дополнительным списаниям?

Повтор может создать вторую генерацию, хотя первая задача всё ещё находится в очереди. Сохраняйте ID задачи, ограничивайте параллельность, повторяйте только временные сбои и сверяйте биллинг провайдера перед повторной отправкой неоднозначного запроса.

Для первого теста, приближенного к продакшену, запустите одну 5-секундную тихую задачу Standard, залогируйте весь жизненный цикл и только затем добавляйте Pro, аудио, multi-shot или параллельность — после того как убедитесь в корректной обработке дублирующих воркеров.