API Kling 3.0 Turbo для преобразования изображения в видео на Python: схема, полный скрипт и обработка ошибок

Схема kling-3.0-turbo/image-to-video компактна и строга: один общедоступный URL изображения, обязательный промпт с описанием движения, целочисленная длительность от 3 до 15 секунд и вывод в 720p или 1080p. Эта страница — справочник по данной версии для валидации тела запроса и различения ошибок HTTP 400 и асинхронных результатов TASK_FAILED.

Об общем процессе создания, опроса, обратных вызовов и скачивания см. руководство по запуску задач Kling на Python и выбору Omni/Turbo.

Входная схема Turbo

Поле	Тип	Обязательно	Допустимые значения
prompt	string	да	описывает движение и поведение камеры
image_urls	массив строк	да	ровно один общедоступный URL изображения
duration	integer	нет	от 3 до 15 секунд
resolution	string	нет	720p или 1080p

Turbo не принимает sound, aspect_ratio, negative_prompt, seed, mode, а также второй URL изображения. Строгая схема отклоняет дополнительные свойства, а не игнорирует их молча.

Входное изображение определяет форму кадра. Перед созданием задачи загрузите его в публичный бакет или CDN; рендерер не может получить localhost, приватные панели управления и истёкшие подписанные URL.

Минимальный рабочий запрос

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-turbo/image-to-video",
    "input": {
      "prompt": "The runner accelerates as the camera tracks from the side",
      "image_urls": ["https://cdn.example.com/first-frame.jpg"],
      "duration": 6,
      "resolution": "1080p"
    }
  }'

Успешный ответ содержит data.taskId. HTTP 200 означает только успешное создание, а не завершение; рендеринг видео всё ещё выполняется асинхронно.

Предварительная валидация на Python

Проверяйте ограничения до сетевого вызова, чтобы очевидные ошибки никогда не создавали задачу:

from urllib.parse import urlparse

import requests


def turbo_input(prompt: str, image_url: str, duration: int, resolution: str) -> dict:
    if not prompt.strip():
        raise ValueError("prompt is required")
    if type(duration) is not int or not 3 <= duration <= 15:
        raise ValueError("duration must be an integer from 3 to 15")
    if resolution not in {"720p", "1080p"}:
        raise ValueError("resolution must be 720p or 1080p")
    parsed = urlparse(image_url)
    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
        raise ValueError("image_url must be a public HTTP(S) URL")

    return {
        "prompt": prompt,
        "image_urls": [image_url],
        "duration": duration,
        "resolution": resolution,
    }


payload = {
    "model": "kling-3.0-turbo/image-to-video",
    "input": turbo_input(
        prompt="The runner accelerates as the camera tracks from the side",
        image_url="https://cdn.example.com/first-frame.jpg",
        duration=6,
        resolution="1080p",
    ),
}

response = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer sk-your-key"},
    json=payload,
    timeout=30,
)
response.raise_for_status()
task_id = response.json()["data"]["taskId"]
print(task_id)

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

Полный скрипт на Python: отправка, опрос, скачивание

Приведённый выше фрагмент заканчивается на task ID. Эта версия выполняет полную задачу и сохраняет MP4. Она отправляет заголовок Idempotency-Key, поэтому повторная отправка той же заявки после тайм-аута вернёт исходную задачу, а не создаст и не спишет оплату за вторую:

import os
import time
import uuid

import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}


def run_turbo(prompt: str, image_url: str, duration: int = 5,
              resolution: str = "720p", out_path: str = "turbo.mp4") -> str:
    body = {
        "model": "kling-3.0-turbo/image-to-video",
        "input": turbo_input(prompt, image_url, duration, resolution),
    }
    key = str(uuid.uuid4())  # reuse this key if you retry the same submission
    r = requests.post(API, json=body, headers={**HEADERS, "Idempotency-Key": key}, timeout=30)
    if r.status_code == 400:
        raise ValueError(f"schema error, no task created: {r.text}")
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    deadline = time.time() + 900
    while time.time() < deadline:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        if data["status"] == "success":
            video = requests.get(data["output"][0]["url"], timeout=120)
            video.raise_for_status()
            with open(out_path, "wb") as f:
                f.write(video.content)  # the output URL is temporary, so save it now
            return out_path
        if data["status"] == "fail":
            raise RuntimeError(f"TASK_FAILED {task_id}: {data.get('error')}")
        time.sleep(10)
    raise TimeoutError(task_id)


print(run_turbo(
    "The runner accelerates as the camera tracks from the side",
    "https://cdn.example.com/first-frame.jpg",
))

Такой пятисекундный фрагмент в 720p стоит $0.65. В рабочей среде замените цикл опроса на верхнеуровневый "callback": {"url": "https://your-app.example.com/hiapi/callback"} и дедуплицируйте уведомления по task ID.

HTTP 400: задача не была создана

Ответ HTTP 400 — результат синхронной проверки схемы. Типичные причины:

Недопустимый ввод	Почему происходит сбой	Как исправить
"duration": "5"	передана строка вместо целого числа	передайте 5
"duration": 20	максимум — 15	выберите от 3 до 15
два image_urls	Turbo принимает только один	оставьте только начальный кадр
"resolution": "4K"	Turbo поддерживает 720p и 1080p	используйте 720p или 1080p, либо выберите Omni
"sound": true	sound отсутствует в схеме Turbo	удалите поле или выберите Omni
отсутствует prompt	Turbo требует промпт	добавьте непустой промпт движения

Поскольку проверка не прошла до создания, опрашивать нечего — нет task ID. Запишите тело ответа и request ID, исправьте тело запроса и отправьте новый запрос.

TASK_FAILED: создание успешно, но рендеринг не удался

Если POST /v1/tasks возвращает HTTP 200 и task ID, последующий сбой относится к жизненному циклу асинхронной задачи и его следует отличать от 400.

Типичные причины:

• URL изображения требует Cookie или заголовка авторизации;
• подписанный URL изображения истёк до того, как рендерер его загрузил;
• хост блокирует серверные загрузки или перенаправляет на HTML-страницу;
• файл повреждён или его медиатип не соответствует содержимому;
• провайдер не смог выполнить данный рендеринг.

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

Общее руководство на Python содержит общий цикл опроса терминального состояния и код скачивания вывода; оставьте его там, чтобы не дублировать логику жизненного цикла на странице справочника по версии.

Цены Turbo и выбор модели

Текущие производственные тарифы:

Режим Turbo	Цена за секунду	5-секундная задача
720p	$0.130	$0.65
1080p	$0.160	$0.80

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

Когда нужны конечный кадр, аудио или 4K, выбирайте стандартный Kling 3.0 (kling-3.0/image-to-video): он принимает одно или два изображения (начальный и конечный кадры), имеет переключатель sound, стоит $0.10/s в 720p без аудио и $0.129/s в 1080p без аудио. Когда нужны референсное изображение или референсное видео, выбирайте Omni. Для одного входного кадра в 720p или 1080p протестируйте эти варианты со своим промптом движения и оцените качество вывода, время в очереди и общую стоимость.

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

Сколько изображений принимает Kling 3.0 Turbo для преобразования изображения в видео?

Ровно один общедоступный URL изображения. Второе изображение вызывает ошибку схемы (image_urls: maxItems: got 2, want 1); для управления начальным и конечным кадрами используйте стандартный Kling 3.0 для преобразования изображения в видео.

Какие значения длительности допустимы?

Передавайте целое число от 3 до 15. Число в кавычках, например "5", является строкой и не пройдёт проверку.

Поддерживает ли Turbo 4K или аудио?

4K не поддерживается: этот эндпоинт принимает 720p или 1080p. Поля sound нет, но фрагменты Turbo содержат аудио, и отключить его нельзя. Когда нужно 4K или вывод без звука, используйте стандартный Kling 3.0 или Omni.

В чём разница между HTTP 400 и TASK_FAILED?

HTTP 400 означает, что запрос нарушает схему, поэтому задача не создана. TASK_FAILED возникает после допустимого ответа о создании, на этапе загрузки ввода или генерации.

Почему внешне общедоступный URL изображения приводит к TASK_FAILED?

Этот URL может зависеть от Cookie, иметь истёкшую подпись, блокировать серверные загрузки или возвращать HTML вместо байтов изображения. Перед повторной попыткой проверьте его без браузерной аутентификации.