Как использовать API kling-3.0-omni/transformation: перерисовка видео с помощью curl и Python

kling-3.0-omni/transformation — это модель видео-в-видео от Kling 3.0 Omni: вы передаёте исходное видео и текстовый промпт, и она переписывает внешний вид этого видео — сцену, стиль, субъект — сохраняя при этом исходное движение и тайминг. На hiapi вы вызываете её через тот же унифицированный асинхронный эндпоинт, что и все остальные генеративные модели: POST /v1/tasks. В этом руководстве приведены проверенная на практике таблица параметров, готовые к копированию curl-запросы, полный Python-клиент (который опрашивает статус и скачивает результат), а также производственные паттерны (колбэки, идемпотентность, обработка ошибок), необходимые перед интеграцией в реальное приложение.

Каждое имя поля, значение перечисления и структура ответа ниже сверены с реальным API.

Что вы построите + предварительные требования

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

1. API-ключ hiapi. Создайте его в консоли hiapi — он имеет вид sk-.... Каждый запрос использует Authorization: Bearer sk-<your-key>.
2. Публично доступный URL исходного видео. Модель скачивает ваше видео на сервере, поэтому это должен быть публичный http(s) URL (ваш собственный CDN, R2/S3 с публичным объектом и т. п.), а не локальный путь к файлу. Допускается только один URL.

Модель и её параметры

Внешняя структура запроса — {"model": ..., "input": {...}}. Схема input строгая — принимаются только три поля ниже, любые лишние поля отклоняются с 400.

Поле	Тип	Обязательно	Описание
prompt	string	Да	Описывает целевой стиль/сцену/субъект. Здесь же регулируется сила перерисовки — нет числовых параметров strength/fidelity.
video_urls	array	Да	Ровно один публичный URL исходного видео (minItems равно 1, maxItems равно 1).
resolution	string, перечисление	Да	Одно из: 720p, 1080p, 4k.

Несколько моментов, где легко ошибиться:

• Нет параметра duration. Длительность и соотношение сторон выходного видео берутся из исходного видео (3–15,5 секунд), а оплата взимается по итоговой длительности выходного видео.
• Сам id модели содержит -omni: kling-3.0-omni/transformation (некоторые другие эндпоинты Omni используют kling-3.0/...). Передавайте этот id напрямую как значение model.
• Сила перерисовки управляется промптом. Для лёгкого изменения напишите «слегка перерисовать, сохранив черты лица и освещение»; для сильного изменения — «полностью переосмыслить как 2D-мультфильм в стиле сел-шейдинг».

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

# 1) Создать задачу перерисовки
curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-omni/transformation",
    "input": {
      "prompt": "Перерисуй эту сцену в стиле рисованной акварельной анимации с мягкой текстурой бумаги и тёплым сумеречным светом; сохрани исходное движение камеры и субъект.",
      "video_urls": ["https://your-cdn.example.com/source-clip.mp4"],
      "resolution": "720p"
    }
  }'
# -> {"code":200,"data":{"taskId":"tk-hiapi-01..."},"message":"success"}

# 2) Опрашивать задачу до достижения терминального состояния
curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01... \
  -H "Authorization: Bearer sk-<your-key>"
# data.status по порядку: queued -> handling -> archiving -> success
# После успеха data.output[0].url — это перерисованный .mp4

Id задачи, который вы опрашиваете, берётся из data.taskId в ответе на создание — не из верхнеуровневого id. Строки статуса: queued / handling / archiving / success (терминальное) или fail; не предполагайте, что там succeeded/completed.

Полный Python-клиент (создание → опрос → скачивание)

import os
import time
import requests

API_KEY = os.environ["HIAPI_KEY"]            # ваш ключ sk-...
BASE = "https://api.hiapi.ai"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def create_restyle(source_video_url: str, prompt: str, resolution: str = "720p") -> str:
    body = {
        "model": "kling-3.0-omni/transformation",
        "input": {
            "prompt": prompt,
            "video_urls": [source_video_url],   # ровно один публичный URL
            "resolution": resolution,           # "720p" | "1080p" | "4k"
        },
    }
    r = requests.post(f"{BASE}/v1/tasks", json=body, headers=HEADERS, timeout=30)
    r.raise_for_status()
    data = r.json()
    if data.get("code") != 200:
        raise RuntimeError(f"Отправка отклонена: {data}")
    return data["data"]["taskId"]


def wait_for_video(task_id: str, poll_s: int = 10, timeout_s: int = 900) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()["data"]
        status = data["status"]
        if status == "success":
            return data["output"][0]["url"]
        if status == "fail":
            raise RuntimeError(f"Задача не выполнена: {data.get('error')}")
        time.sleep(poll_s)                      # queued / handling / archiving
    raise TimeoutError(f"{task_id} не завершилась за {timeout_s} секунд")


if __name__ == "__main__":
    task_id = create_restyle(
        source_video_url="https://your-cdn.example.com/source-clip.mp4",
        prompt=(
            "Перерисуй эту сцену в стиле рисованной акварельной анимации, с мягкой текстурой бумаги, "
            "тёплым сумеречным светом; сохрани исходное движение камеры и субъект."
        ),
        resolution="720p",
    )
    print("Задача:", task_id)

    url = wait_for_video(task_id)
    print("URL видео:", url)

    # Выходной файл находится на temp.hiapi.ai и истекает (около 7 дней). Скачайте его сразу.
    clip = requests.get(url, timeout=120).content
    with open("restyled.mp4", "wb") as f:
        f.write(clip)
    print("Сохранено restyled.mp4", len(clip), "байт")

Поместите ключ в переменную окружения и запустите:

export HIAPI_KEY=sk-<your-key>
python restyle.py

Производственные паттерны

Используйте колбэки вместо частого опроса

Для любого сценария за пределами скрипта зарегистрируйте вебхук, чтобы не поддерживать цикл опроса. callback — это верхнеуровневое поле, на одном уровне с model и input, и его ни в коем случае нельзя помещать внутрь input:

{
  "model": "kling-3.0-omni/transformation",
  "input": {
    "prompt": "Перерисуй эту сцену в стиле 2D-мультфильма с сел-шейдингом, с толстыми контурами; сохрани исходное движение.",
    "video_urls": ["https://your-cdn.example.com/source-clip.mp4"],
    "resolution": "1080p"
  },
  "callback": { "url": "https://your-app.example.com/hooks/hiapi", "when": "final" }
}

• callback.when принимает только final (значение по умолчанию). Когда задача достигает терминального состояния, он ставится в очередь один раз и срабатывает как при успехе, так и при неудаче. Семантика доставки — как минимум одна доставка, поэтому один и тот же колбэк всё равно может прийти несколько раз (см. ниже).
• Тело POST-запроса при доставке идентично объекту data, получаемому через GET /v1/tasks/<id> — поэтому ваш обработчик может читать status, output[].url и error без повторного запроса.
• Если поместить callback внутрь input, при отправке возникает ошибка additional properties 'callback' not allowed (схема input каждого модели строгая).

Идемпотентность и семантика доставки

Колбэки доставляются как минимум один раз, а не ровно один раз — один и тот же taskId может прийти несколько раз. Используйте taskId в качестве ключа обработчика и сделайте шаг «пометить выполненным + сохранить видео» идемпотентным. hiapi повторяет колбэки, завершившиеся не с 2xx/таймаутом, по расписанию сразу → +1 минута → +5 минут → +20 минут, максимум 4 попытки; ваш эндпоинт должен возвращать HTTP 2xx, чтобы остановить повторные попытки.

Немедленно скачивайте результат

data.output[0].url указывает на temp.hiapi.ai и содержит expireAt (Unix-временная метка, TTL около 7 дней). После истечения объект удаляется, и этот URL возвращает 404 — повторный опрос задачи вернёт тот же URL, но не пересоздаст файл. Как только задача успешно завершится, сразу скопируйте байты в собственное хранилище.

Обработка ошибок

Три формы сбоев, которые нужно обрабатывать отдельно:

• Ошибка запроса (HTTP 400) — плоская структура, задача не создана: {"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: resolution: value must be one of '720p', '1080p', '4k'"}
• Ошибка аутентификации (HTTP 401) — вложенная структура: {"error":{"code":"permission_denied","type":"hiapi_error", ...}}
• Сбой задачи — отправка возвращает 200 и taskId, но последующий опрос показывает data.status == "fail" с data.error. За неудачные задачи плата не взимается (при окончательном сбое задачи зарезервированная сумма возвращается). Недоступность или невозможность скачать исходный URL проявляется именно здесь.

Стоимость

kling-3.0-omni/transformation тарифицируется по секундам выходного видео, а ставка зависит от запрошенного разрешения (720p — $0,143 в секунду, 1080p — $0,193 в секунду, 4k — $0,479 в секунду, проверено 21 октября 2026 года). Перед пакетной обработкой видео посмотрите актуальные ставки за секунду на странице цен hiapi — расходы на видеозадачи накапливаются гораздо быстрее, чем на задачи с изображениями.

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

• Страница модели и спецификации: kling-3.0-omni/transformation на hiapi
• Справочник по эндпоинту: Создание задачи — унифицированный асинхронный API
• Руководство той же серии по тому же эндпоинту: API Kling AI для видео-из-изображения на Python

Частые вопросы

Как управлять силой перерисовки? Через промпт, а не через параметры. Нет полей strength, fidelity или creativity. Для лёгкого изменения напишите «слегка перерисовать, сохранив лицо и освещение», для сильного — «полностью переосмыслить как