Kling 4.0 API: первое видео на Python и cURL — пошаговое руководство

Kling 4.0 API в PoYo использует один идентификатор модели, kling-4.0, для генерации видео по тексту, по первому/последнему кадру, по визуальным референсам и для редактирования видео. Отправьте запрос, сохраните ID задачи и опрашивайте её статус, пока она не завершится. Руководство опирается на актуальную схему PoYo, проверенную 24 октября 2026 года; названия полей у других провайдеров не взаимозаменяемы.

Откройте песочницу Kling 4.0, чтобы попробовать параметры в визуальном интерфейсе, или загляните в документацию API.

Первое видео через cURL

Задайте переменную POYO_API_KEY в окружении оболочки и отправьте этот пятисекундный запрос. Храните ключ на сервере, а не в браузерном коде.

curl --fail-with-body https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "kling-4.0",
    "input": {
      "prompt": "A paper boat floats beneath a stone bridge. One continuous low tracking shot, soft morning light, gentle water sounds, no speech or on-screen text.",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

Возьмите data.task_id из JSON-ответа: успешная отправка ещё не означает готовое видео. Подставьте это значение вместо YOUR_TASK_ID:

curl --fail-with-body \
  https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

Документированные статусы: not_started, running, finished и failed. После завершения ищите в data.files видео с полем file_url. При ошибке смотрите error_message и сохраните ID задачи для диагностики. Чтобы опрашивать существующую задачу, отправлять её повторно не нужно.

Цикл опроса на Python с ограничением по времени

Установите requests и запускайте код на бэкенде. Он проверяет и HTTP-ошибки, и ошибки приложения, останавливается на неудачной задаче и ограничивает ожидание 30 минутами. Тайм-аут означает, что ту же задачу нужно проверить позже: автоматическая повторная отправка может создать вторую платную задачу.

import os
import time
import requests

base = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]

def checked(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") not in (0, 200):
        raise RuntimeError(body.get("message") or "PoYo API error")
    return body["data"]

task = checked(session.post(base + "/api/generate/submit", json={
    "model": "kling-4.0",
    "input": {
        "prompt": "A paper boat floats beneath a stone bridge. Slow tracking shot.",
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9",
    },
}, timeout=60))
task_id = task["task_id"]
print("Task:", task_id, flush=True)
deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    task = checked(session.get(
        base + "/api/generate/status/" + task_id, timeout=60))
    if task["status"] == "failed":
        raise RuntimeError(task.get("error_message") or "Generation failed")
    if task["status"] == "finished":
        videos = [f["file_url"] for f in task.get("files", [])
                  if f.get("file_type") == "video"]
        if not videos:
            raise RuntimeError("Finished task returned no video")
        print(videos[0])
        break
    time.sleep(10)
else:
    raise TimeoutError("Check the saved task ID again: " + task_id)

Выбор правильного режима ввода

Поле исходного видео включает режим редактирования, даже если в запросе есть и референсные изображения. В режиме «изображение в видео» первое изображение задаёт стартовый кадр, второе — финальный. Референсные изображения управляют внешностью или стилем и не равнозначны граничным кадрам.

Лимиты, которые стоит проверить до отправки

Генерация поддерживает целочисленную длительность от 3 до 30 секунд в разрешении 720p или 1080p. Обычный промпт в этой схеме PoYo ограничен 26 000 символов. Каждый шот в multi_prompt принимает до 512 символов; если длительность шота не указана, по умолчанию она составляет пять секунд. Суммарная длительность шотов должна быть 3–30 секунд, а явно заданная длительность верхнего уровня должна совпадать с этой суммой.

Референсы допускают до 10 изображений, пяти видео и семи субъектов при общем лимите в 15 ассетов. Первый кадр учитывается и в лимите изображений, и в общем лимите. Каждое референсное видео или видео субъекта должно длиться 3–30 секунд; их суммарная реальная длительность не может превышать 30 секунд. Не округляйте длительность вниз, чтобы слишком длинный ввод прошёл валидацию.

Разберитесь в первом счёте

Пятисекундный запрос в 720p без видеоввода стоит 142,5 кредита, или $0.7125 по текущему указанному курсу. Видеоввод меняет и тариф, и тарифицируемую длительность. Прежде чем оценивать сценарий с референсным видео или редактированием, посмотрите примеры расчёта стоимости.

Официальный продукт для креаторов рекламирует дополнительные возможности, включая несколько ключевых кадров. Схема PoYo здесь предоставляет до двух граничных кадров и промпты для отдельных шотов; не отправляйте на этот эндпоинт выдуманные поля keyframes, seed, negative_prompt или generate_audio. Рабочие примеры — в руководстве по промптам и туториале по Omni Reference.

Часто задаваемые вопросы

ID модели в API — kling-4-0? Нет, это слаг страницы. В запросе используется ID модели kling-4.0.

Можно ли запросить 4K? Этот эндпоинт PoYo сейчас принимает только 720p и 1080p. Сверяйтесь со схемой провайдера, а не с маркетинговыми характеристиками приложения для креаторов.

Можно ли использовать callback? Запрос на отправку поддерживает поле верхнего уровня callback_url. Как обрабатывать callback, смотрите в актуальной документации; пример с опросом выше от него не зависит.

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