API Kling AI для преобразования изображения в видео на Python

Работайте с API Kling AI для преобразования изображения в видео на Python через асинхронные эндпоинты задач HiAPI. Приведённое ниже руководство по быстрому старту использует актуальный доступный ID модели kling-3.0-omni/image-to-video, опрашивает задачу до достижения терминального состояния и скачивает сгенерированный MP4.

Чтобы узнать точные поля, откройте документацию API Kling 3.0 Omni для преобразования изображения в видео. На странице актуальной модели Omni можно посмотреть модель и Playground, а перед запуском в продакшене сверьте актуальные цены API Kling.

Быстрый старт: запуск Kling изображение-в-видео на Python

Установите requests командой python -m pip install requests, задайте в окружении HIAPI_API_KEY и замените IMAGE_URL на публичный URL JPEG, PNG или WebP. Полный скрипт — это первый блок кода, который можно скопировать:

import os
import time
from pathlib import Path

import requests

API_BASE = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]
IMAGE_URL = "https://cdn.example.com/first-frame.jpg"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "kling-3.0-omni/image-to-video",
    "input": {
        "image_urls": [IMAGE_URL],
        "prompt": "The camera slowly pushes in as leaves move in a light breeze",
        "duration": 5,
        "resolution": "1080p",
        "sound": False,
    },
}

created = requests.post(
    f"{API_BASE}/tasks",
    headers=HEADERS,
    json=payload,
    timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"]["taskId"]

deadline = time.time() + 900
while time.time() < deadline:
    response = requests.get(
        f"{API_BASE}/tasks/{task_id}",
        headers=HEADERS,
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()["data"]

    if task["status"] == "success":
        output_url = task["output"][0]["url"]
        break
    if task["status"] == "fail":
        raise RuntimeError(task.get("error") or f"Task {task_id} failed")

    time.sleep(8)
else:
    raise TimeoutError(f"Task {task_id} did not finish within 15 minutes")

with requests.get(output_url, stream=True, timeout=180) as download:
    download.raise_for_status()
    with Path("kling-output.mp4").open("wb") as video:
        for chunk in download.iter_content(1024 * 1024):
            if chunk:
                video.write(chunk)

print("Saved kling-output.mp4")

Запрос на создание возвращает taskId и не ждёт завершения генерации видео. Скрипт опрашивает GET /v1/tasks/{taskId}, останавливается при success или fail и как можно скорее скачивает первый результат, поскольку URL результата истекает.

Откройте модель Kling Omni и попробуйте этот payload.

Выбор актуальной доступной модели Kling изображение-в-видео

ID модели	Сценарий применения	Входные и выходные параметры
kling-3.0-omni/image-to-video	Нужен контроль первого/последнего кадра, опциональный нативный звук или 4K	Один или два публичных URL изображений; 3–15 секунд; 720p, 1080p или 4K
kling-3.0-turbo/image-to-video	Достаточно одного начального кадра, а более простая схема 720p/1080p покрывает потребности	Ровно один публичный URL изображения; prompt обязателен; 3–15 секунд; 720p или 1080p

Полный справочник полей Omni см. в документации Omni I2V. У Turbo есть отдельный справочник схемы Turbo I2V. Обе модели используют одинаковый рабочий процесс создания и опроса через /v1/tasks, поэтому можно сохранить один исполнитель и менять только model и input.

Тело запроса, соответствующее требованиям модели

Omni с первым и последним кадром

Передайте один URL для первого кадра или два URL в порядке [first, last]:

{
  "model": "kling-3.0-omni/image-to-video",
  "input": {
    "image_urls": [
      "https://cdn.example.com/first-frame.jpg",
      "https://cdn.example.com/last-frame.jpg"
    ],
    "prompt": "The camera arcs around the subject as the light changes from dawn to noon",
    "duration": 8,
    "resolution": "1080p",
    "sound": true
  }
}

Omni принимает один или два image_urls. Его prompt необязателен, duration — целое число от 3 до 15, resolution — 720p, 1080p или 4K, sound необязателен.

Turbo с одним начальным кадром

{
  "model": "kling-3.0-turbo/image-to-video",
  "input": {
    "prompt": "The subject turns toward the camera while leaves move in a light breeze",
    "image_urls": ["https://cdn.example.com/first-frame.jpg"],
    "duration": 8,
    "resolution": "1080p"
  }
}

Turbo требует prompt и ровно один элемент в image_urls. Не отправляйте поля, поддерживаемые только Omni (например, sound), и не добавляйте поля для преобразования текста в видео (например, aspect_ratio); кадр определяется исходным изображением.

Цены Kling AI: используйте актуальные тарифы, не копируйте цены

Цены Kling AI на HiAPI оплачиваются по факту использования. Обе текущие модели преобразования изображения в видео тарифицируются по количеству сгенерированных секунд, конкретная ставка зависит от модели и разрешения; у Omni также есть отдельный тариф при включённом звуке. Более длинные фрагменты, более высокое разрешение или нативный звук изменяют стоимость задачи.

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

Бесплатен ли Kling AI?

Нет: в HiAPI генерация через API Kling изображение-в-видео не является безлимитным бесплатным API. Успешные задачи расходуют баланс по актуальной ставке для выбранной модели, длительности, разрешения и настроек звука. Промоакции аккаунта или бонусы для новых пользователей могут меняться и могут иметь условия, поэтому не считайте их гарантированным бесплатным тарифом Kling; перед отправкой задачи проверьте в аккаунте действующие предложения и ваш баланс.

Проверки в продакшене, предотвращающие сбой или дублирование задач

1. Используйте HTTPS-URL изображений, доступные для непосредственного скачивания. localhost, страницы, требующие входа, HTML-страницы с общим доступом и просроченные подписанные URL могут привести к сбою после создания задачи.
2. Сохраняйте taskId перед повторной попыткой worker. Повторный вызов создания может создать и оплатить вторую задачу.
3. Считайте success и fail терминальными состояниями. В продакшене используйте callback.url верхнего уровня и сохраняйте опрос как резервную сверку.
4. Своевременно скачивайте output[].url и копируйте результаты для долгосрочного хранения в подконтрольное вам хранилище.
5. Проверяйте схему выбранной модели перед отправкой. Строгие модели отклоняют неизвестные поля.

Распространённые ошибки

• HTTP 400: запрос не соответствует схеме; проверьте указанное поле, значения перечислений, длину массива и тип JSON.
• HTTP 401: bearer-ключ отсутствует, недействителен или не может использовать выбранную модель.
• Задача переходит в fail: запрос на создание прошёл валидацию, но рендерер не смог получить входные данные или завершить генерацию. Записывайте taskId и возвращённую ошибку отдельно от ответа на создание.
• URL результата истёк: рендеринг мог успеть завершиться, но временный URL выдачи не был скачан вовремя.

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

Какую модель Kling изображение-в-видео использовать в Python?

Используйте kling-3.0-omni/image-to-video, когда нужен контроль одного-двух кадров, опциональный нативный звук или 4K. Используйте kling-3.0-turbo/image-to-video, когда достаточно одного начального кадра и вывода 720p/1080p. Код создания, опроса и скачивания на Python остаётся неизменным.

Какие сейчас ID моделей Kling AI изображение-в-видео?

Актуальные доступные ID, рассматриваемые в этой статье, — kling-3.0-omni/image-to-video и kling-3.0-turbo/image-to-video. Отправьте любой из них в поле model верхнего уровня запроса POST /v1/tasks.

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

Omni принимает одно изображение в качестве первого кадра или два изображения в порядке [first, last]. Turbo принимает ровно одно изображение начального кадра.

Сколько стоит API Kling AI?

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

Бесплатен ли Kling AI через API?

Безлимитный бесплатный тариф Kling API не гарантируется. Генерация расходует баланс аккаунта по актуальной ставке за задачу. Проверьте, есть ли в аккаунте действующее стартовое предложение с условиями, и не предполагайте фиксированный бесплатный лимит.

Почему задача завершается сбоем, хотя запрос на создание успешен?

JSON прошёл начальную валидацию, но рендерер мог не получить изображение или не завершить генерацию. Убедитесь, что изображение публичное и не просрочено, затем проверьте терминальную ошибку по сохранённому taskId.

Как получить сгенерированное видео?

Прочитайте data.taskId из ответа на создание. Локальный скрипт может опрашивать GET /v1/tasks/{taskId}, а в продакшене можно использовать callback.url. При success скачайте data.output[0].url до истечения его срока.

Далее прочитайте полный справочник API Kling Omni, а затем, когда будете готовы протестировать запрос, откройте страницу актуальной модели.