Руководство

Как использовать Kling 2.5 Turbo Image-to-Video API (curl + Python)

Рабочий пример генерации видео из первого кадра: создание задачи, опрос задачи, скачивание MP4 — и полная строгая схема входных данных.

Oct 21, 2026

TL;DR

kling-2.5-turbo/image-to-video преобразует одно изображение первого кадра в видеоклип длительностью 5 или 10 секунд; передав URL второго изображения, можно зафиксировать последний кадр. Модель работает на асинхронном API задач HiAPI — сначала POST /v1/tasks создаёт задачу, затем опрос GET /v1/tasks/{taskId} возвращает сгенерированный MP4.
Стоимость выходных данных — $0.06 за секунду: 5-секундный клип — $0.30, 10-секундный клип — $0.60. Оплата взимается за каждую завершённую секунду выходных данных; задачи, завершившиеся ошибкой из-за недопустимых входных данных, не создают выходных данных и не оплачиваются.
Схема входных данных строгая и закрытая. Обязательные: image_urls (массив, 1–2 элемента — обратите внимание, множественное число), prompt, duration (только 5 или 10). Необязательные: aspect_ratio, negative_prompt, cfg_scale. Форма единственного числа image_url отклоняется сразу.
Модель уже доступна на HiAPI: откройте страницу модели, чтобы сначала попробовать в браузере, а затем подключить API, описанный ниже.

Что вы создадите и что потребуется

После прочтения этой статьи у вас будет рабочий вызов «первый кадр → видео»: отправка изображения и промпта движения, опрос задачи, скачивание MP4. Сначала нужно подготовить две вещи:

Получите API Key в панели HiAPI — каждый запрос должен отправляться с Authorization: Bearer sk-.... Если вы ещё не создали его, см. документацию по аутентификации.
Публично доступный URL изображения первого кадра. Вызов создания проверяет только структуру входных данных; изображение фактически загружается во время выполнения задачи, поэтому localhost или приватный URL создаст задачу, которая затем завершится ошибкой (подробности ниже).

Это генерация видео из изображения, поэтому идентификатор модели — kling-2.5-turbo/image-to-video. Если вы хотите генерировать видео только по промпту, существует отдельная конечная точка текст-в-видео.

Минимальный рабочий пример (curl)

Создайте задачу. Имя модели указывается на верхнем уровне; всё, что читает модель, помещается в input:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-2.5-turbo/image-to-video",
    "input": {
      "prompt": "Флакон духов медленно вращается на мраморной подставке, свет играет на стекле, лепестки кружатся в воздухе, медленный облёт камерой",
      "image_urls": ["https://static.hiapi.ai/gallery/2026/10/4852c542c4447593.jpg"],
      "duration": 5,
      "aspect_ratio": "9:16"
    }
  }'

Успешное создание возвращает идентификатор задачи — а не видео:

{ "code": 200, "data": { "taskId": "tk-hiapi-01M5CW..." }, "message": "success" }

Затем опрашивайте конечную точку деталей, пока status не перейдёт в конечное состояние:

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M5CW... \
  -H "Authorization: Bearer sk-YOUR_KEY"

Во время выполнения задачи вы будете видеть промежуточные состояния; после завершения URL MP4 можно получить в data.output[0].url:

{
  "code": 200,
  "data": {
    "status": "success",
    "model": "kling-2.5-turbo/image-to-video",
    "storage": "temp",
    "output": [{ "url": "https://temp.hiapi.ai/kling-i2v/tk-hiapi-01M5CW.mp4?expireAt=1761350400" }]
  },
  "message": "success"
}

Этот output[0].url — временная ссылка; скачивайте файл сразу, а не используйте прямую ссылку в вашем приложении (см. замечания по эксплуатации).

Минимальный рабочий пример (Python)

SDK не нужен — API задач HiAPI является чистым HTTP-интерфейсом, поэтому достаточно стандартной библиотеки:

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY", "Content-Type": "application/json"}


def create(image_url: str, prompt: str, duration: int = 5) -> str:
    payload = {
        "model": "kling-2.5-turbo/image-to-video",
        "input": {
            "prompt": prompt,
            "image_urls": [image_url],   # 1–2 items; 2nd = last frame
            "duration": duration,        # 5 or 10 only
        },
    }
    r = requests.post(API, json=payload, headers=HEADERS, timeout=60)
    body = r.json()
    task_id = (body.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {body}")
    return task_id


def wait(task_id: str, timeout_s: int = 600, interval: int = 5) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30)
        task = r.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task["output"][0]["url"]
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(interval)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


task_id = create(
    "https://static.hiapi.ai/gallery/2026/10/4852c542c4447593.jpg",
    "медленный облёт вокруг продукта, свет играет на стекле, лепестки кружатся в воздухе",
    duration=5,
)
mp4_url = wait(task_id)

# Download immediately — the URL is short-lived.
with requests.get(mp4_url, stream=True, timeout=120) as resp:
    resp.raise_for_status()
    with open("clip.mp4", "wb") as f:
        for chunk in resp.iter_content(1 << 16):
            f.write(chunk)
print("saved clip.mp4")

Замечания по эксплуатации

Опрос или колбэк. Опрос каждые 5 секунд (как показано выше) — самый простой путь, и именно он используется в примере. Если вы предпочитаете получать результаты push-уведомлением, вызов создания принимает объект callback верхнего уровня — {"url": "https://you/webhook", "when": "final"} — и после перехода задачи в конечное состояние HiAPI отправит POST на вашу конечную точку. Точный контракт webhook см. в документации по созданию задачи; для большинства задач с одним клипом опроса конечной точки деталей задачи достаточно.

Всегда ветвитесь по data.status, никогда по HTTP-коду ответа вызова создания. Возврат 200 при создании означает принято, а не отрендерено. Клип действительно существует только тогда, когда конечная точка деталей возвращает status: "success".

Считайте выходной URL временной ссылкой. storage имеет значение temp, URL истекает, поэтому скачивайте MP4 сразу после успешного выполнения задачи (или копируйте его в собственное хранилище). Не передавайте URL HiAPI напрямую конечным пользователям.

Контроль затрат. Вы платите за каждую завершённую секунду выходных данных — $0.06/сек — поэтому 5-секундный клип стоит $0.30, а 10-секундный — $0.60. Во время итераций с промптами и первым кадром сначала рендерите 5 секунд, а после достижения нужного результата повторно запускайте с 10 секундами. Актуальные цены см. на странице тарифов.

Практические заметки и предостережения

Всё в этой статье получено из реальных запросов к рабочей конечной точке (схема перепроверена 2026-10-21), а не только из таблицы параметров:

Поле называется image_urls (множественное число), и схема закрытая. Отправка кажущегося естественным image_url завершится ошибкой до создания задачи:
```
{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: image_urls: missing required field \"image_urls\"; <root>: additional properties 'image_url' not allowed" }
```
Любое нераспознанное поле (mode, опечатка и т. п.) будет отклонено так же — не существует дополнительных полей, которые молча игнорируются.
duration — это перечисление, а не диапазон. Принимаются только 5 и 10; 7 вернёт duration: value must be one of 5, 10.
image_urls содержит 1 или 2 элемента. Один URL — это первый кадр; второй URL фиксирует последний кадр для контролируемого перехода. Три URL вернут maxItems: got 3, want 2; пустой массив вернёт minItems: got 0, want 1.
Необязательные поля, которые действительно существуют: aspect_ratio принимает только 16:9, 9:16, 1:1, 4:3, 3:4, 21:9; cfg_scale ограничен значением 1 (передача 99 вернёт cfg_scale: maximum: got 99, want 1); negative_prompt должен быть строкой. Если опустить aspect_ratio, модель будет следовать вашему первому кадру.
Вызов создания проверяет только структуру, но не доступность — это самый частый подводный камень. Синтаксически корректный, но недоступный URL изображения вернёт 200 и taskId, после чего задача асинхронно перейдёт в состояние ошибки:
```
{ "data": { "status": "fail",
  "error": { "code": "INVALID_REQUEST",
    "message": "The image URL is not readable. Please provide a valid public HTTP(S) URL or an accessible file path and try again." } } }
```
Эта задача не создала output и не была оплачена — ошибка не влечёт затрат — но если вы проверяете только ответ на создание, вы ошибочно решите, что всё успешно. Именно поэтому цикл опроса должен ветвиться по data.status.

Связанные материалы

Страница модели Kling 2.5 Turbo Image-to-Video — попробуйте в браузере без кода.
Kling 2.5 Turbo Text-to-Video — без начального кадра, генерация непосредственно по промпту.
6 шаблонов промптов для Kling 2.5 Turbo — готовые к копированию промпты для продуктов, вертикального видео, путешествий, еды, питомцев и переходов.
Документация Создание задачи и Детали задачи — полный справочник по асинхронным задачам, включая колбэки.
Быстрый старт — если это ваш первый вызов HiAPI, здесь пятиминутная версия.

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

Какова максимальная длительность клипа? 5 или 10 секунд — это единственные два значения duration, которые принимает схема.

Могу ли я контролировать концовку? Да. Поместите два URL в image_urls: первый — начальный кадр, второй — последний кадр. Модель интерполирует движение между ними.

Почему создание возвращает 200, а задача показывает fail? Вызов создания проверяет только соответствие вашего JSON схеме. Изображение загружается во время выполнения задачи, поэтому недоступный или приватный URL создаст задачу, а затем приведёт к её ошибке. Всегда читайте data.status из конечной точки деталей и убедитесь, что URL первого кадра публично доступен.

Берётся ли плата за неудачные задачи? Нет. Вы платите за каждую завершённую секунду выходных данных, поэтому задачи, завершившиеся ошибкой из-за недопустимых входных данных, не создают output и не оплачиваются.

Есть ли управление соотношением сторон? aspect_ratio необязателен и принимает 16:9, 9:16, 1:1, 4:3, 3:4 или 21:9. Если оставить пустым, модель будет следовать вашему первому кадру.