HiAPI
Блог

Руководство

Как вызывать kling-3.0-omni/transformation через HiAPI API: руководство по curl и Python

Полный разбор рабочего запроса для преобразования стиля видео на HiAPI

Nov 12, 2026
Обложка блога HiAPI: вложенные широкие стрелки на тёмно-синем фоне образуют ступенчатое продвижение, абрикосовый передний край обозначает поток сигнала.
На этой странице

Функции конечной точки transformation и сценарии применения

kling-3.0-omni/transformation — это конечная точка преобразования стиля видео на HiAPI. Вы передаёте ей две вещи: исходное видео и инструкцию по стилю на естественном языке. Она возвращает новое видео, в котором содержимое исходного видео сохраняется, но представлено в запрошенном визуальном стиле.

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

Сценарии, для которых подходит эта конечная точка

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

Сценарии, для которых она не подходит

  • Вам нужно генерировать видео с нуля (генерация видео по тексту — это другая задача).
  • Вам нужен покадрово точный монтаж, редактирование или композитинг. Преобразование только перестраивает стиль, но не редактирует.
  • Ваш исходный материал — это только аудио или статичное изображение.

В остальной части этого руководства шаг за шагом объясняются структура запроса, готовый к запуску вызов curl, соответствующая версия на Python, а также операционные детали вокруг вывода 4K и длительных задач.

Разбор запроса: исходное видео, инструкция по стилю и параметры вывода

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

Исходное видео

Конечной точке нужен доступ к вашему входному файлу. На практике вы передаёте URL, который платформа может получить, или идентификатор, возвращённый шагом загрузки файла в HiAPI. Практическое правило: исходный файл должен быть доступен со стороны сервера, а не с вашего ноутбука. Путь localhost или файл за вашим VPN не подойдут.

Исходный формат должен быть консервативным — используйте широко поддерживаемые контейнеры и кодеки. Если ваше видео создано необычным процессом и не проходит проверку, сначала перекодируйте его в стандартный H.264 MP4. Этот шаг устраняет значительную часть ошибок ввода.

Инструкция по стилю

Это описание целевого визуального эффекта на естественном языке. Это самое влиятельное поле запроса и то, над которым стоит работать больше всего.

  • Описывайте визуальную обработку, а не содержание. Содержание берётся из видео; сообщать модели о том, что уже есть на экране, — лишь тратить бюджет промпта.
  • Будьте конкретны в отношении среды и текстуры: «покадровая пластилиновая анимация с видимыми отпечатками пальцев» передаёт гораздо больше, чем «анимация».
  • Явно указывайте, что нужно сохранить, если это важно: «сохранить узнаваемость лиц, движение камеры без изменений».
  • Укладывайтесь в один абзац с акцентом. Длинные, противоречивые промпты часто усредняются в заурядный результат.

Параметры вывода

Настройки вывода управляют разрешением и другими деталями доставки. Главное решение — запрашивать 4K или стандартное разрешение. Более высокое разрешение потребляет больше вычислений и занимает больше времени, поэтому к нему следует относиться как к осознанному решению, а не выбору по умолчанию. Конечная точка в общем случае работает как асинхронная задача, поэтому ваш запрос обычно возвращает ссылку на задачу, которую нужно опрашивать или ожидать, а не сразу готовый файл.

Сопоставив входные данные с этими тремя группами полей, вы сделаете фактическое тело JSON-запроса понятным.

Рабочий запрос curl с нуля

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

curl -X POST "https://api.hiapi.ai/v1/kling-3.0-omni/transformation" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://your-cdn.example.com/clips/source.mp4",
    "prompt": "Преобразовать в нарисованную от руки акварельную анимацию, мягкие растушёванные края, видимая текстура бумаги, тёплая ограниченная палитра. Сохранить лица и движение камеры.",
    "resolution": "1080p"
  }'

Что делает каждая часть

  • URL-путь указывает конечную точку. Он должен быть абсолютно точным; опечатка здесь вернёт ошибку маршрутизации, а не ошибку валидации.
  • Заголовок Authorization несёт ваш ключ HiAPI. Экспортируйте его как переменную окружения, а не вставляйте в историю оболочки.
  • video_url — это исходное видео. Оно должно быть доступно со стороны сервера.
  • prompt — это инструкция по стилю. Это поле вы будете менять чаще всего.
  • resolution — это настройка вывода. Начинайте с низкого разрешения при итерации и повышайте его, когда результат определён.

Как интерпретировать ответ

Успешный ответ возвращает объект задачи. Запишите идентификатор задачи и любые поля состояния:

{
  "id": "job_abc123",
  "status": "queued"
}

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

Тот же запрос на Python

Версия на Python — это тот же вызов curl, где тело JSON-запроса выражено как словарь. Использование requests сохраняет читаемость и лёгкость зависимостей.

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "video_url": "https://your-cdn.example.com/clips/source.mp4",
    "prompt": (
        "Преобразовать в нарисованную от руки акварельную анимацию, мягкие растушёванные края, "
        "видимая текстура бумаги, тёплая ограниченная палитра. Сохранить лица и движение камеры."
    ),
    "resolution": "1080p",
}

resp = requests.post(
    f"{BASE}/kling-3.0-omni/transformation",
    headers=HEADERS,
    json=payload,
    timeout=60,
)
resp.raise_for_status()
job = resp.json()
job_id = job["id"]
print("submitted", job_id, job.get("status"))

Опрос до завершения задачи

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

def wait_for_job(job_id, max_attempts=60, interval=10):
    for _ in range(max_attempts):
        r = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status == "succeeded":
            return data
        if status == "failed":
            raise RuntimeError(data.get("error") or "job failed")
        time.sleep(interval)
    raise TimeoutError(f"job {job_id} did not finish in time")

result = wait_for_job(job_id)
print(result.get("output") or result)

Сделайте его безопасным для производственной среды

  • Читайте путь конечной точки и маршрут опроса из документации ответов API, а не жёстко кодируйте предположения, которые могут измениться.
  • Записывайте идентификатор задачи при отправке. Если в дальнейшем что-то пойдёт не так, это ваша единственная зацепка.
  • Рассматривайте failed и тайм-аут как разные результаты. Неудачные задачи обычно связаны с параметрами; тайм-ауты обычно связаны с ёмкостью или длительностью.

Работа с выводом 4K и длительными задачами

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

Вывод 4K

4K — это решение о доставке, а не значение по умолчанию. Каждый выходной пиксель потребляет вычисления, и относительный скачок от стандартного разрешения до 4K велик. Разумный рабочий процесс:

  1. Итерируйте инструкцию по стилю при более низком разрешении. Качество промпта не зависит от разрешения, поэтому сначала добейтесь правильного эффекта с низкими затратами.
  2. Зафиксируйте промпт и исходное видео.
  3. Повторно запустите один раз в 4K для доставки.

Избегайте генерации вариантов 4K в тесном цикле при настройке формулировок — это самый распространённый способ потратить бюджет на рендеры, которые в конечном итоге будут выброшены.

Длительные задачи

Более длинные исходные видео преобразуются дольше, и конечная точка возвращает ссылку на задачу, а не готовый файл. Стройте клиент с учётом этой реальности:

  • Никогда не блокируйте веб-запрос на рендеринге. Отправьте, сохраните идентификатор задачи и сразу верните управление вызывающей стороне.
  • Разделяйте отправку и получение. Рабочий процесс с очередью и опросом более устойчив, чем ожидание внутри процесса, и переживает перезапуск процесса.
  • Сохраняйте состояние задачи. Если рабочий процесс умирает посреди опроса, задача не исчезает; вы можете восстановиться по сохранённому идентификатору.
  • Используйте webhook, если ваш аккаунт его поддерживает, и сохраняйте опрос как резервный путь.
  • Задайте общий бюджет ожидания, отражающий ваше ожидаемое максимальное видео, а не произвольное число.

Практический шаблон

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

Диагностика типичных сбоев

Большинство сбоев относится к трём категориям: исходное видео не читается, параметры отклонены или задача никогда не завершается. Прежде чем что-либо менять, определите категорию проблемы.

Ошибки загрузки и доступа к источнику

Симптом: отправка завершается неудачей или задача почти сразу завершается ошибкой ввода.

  • URL недоступен публично. Проверьте его с машины вне вашей сети. Типичный виновник — истечение срока действия подписанного URL между отправкой и получением.
  • Формат не поддерживается. Перекодируйте в стандартный H.264 MP4 и повторите попытку.
  • Файл усечён или повреждён. Скачайте его сами и воспроизведите от начала до конца.
  • Запрос слишком большой. Если вы отправляете байты файла встроенно, а не по URL, используйте процесс загрузки и передавайте возвращённый идентификатор.

Ошибки параметров

Симптом: ответ 4xx при отправке.

  • Некорректный JSON. Проверьте тело запроса линтером. Завершающие запятые и неэкранированные кавычки — частые ошибки в рукописных вызовах curl.
  • Неверное имя поля или тип. Сверьтесь с текущей схемой запроса; передача разрешения как числа, когда ожидается строка, приведёт к сбою.
  • Пустой или противоречивый промпт. Если инструкция ничего не описывает или требует взаимоисключающих стилей, ожидайте слабый результат или отклонение. Перепишите её вокруг одного чёткого визуального направления.
  • Ключ API отсутствует или недействителен. Проверьте значение заголовка и действует ли ключ для этой конечной точки.

Тайм-ауты и зависшие задачи

Симптом: задача остаётся в очереди или в работе после вашего бюджета ожидания, или ваш клиент сдаётся.

  • Различайте тайм-аут клиента и сбой задачи. Короткий HTTP-тайм-аут при отправке не означает, что задача не началась; проверьте наличие идентификатора задачи, прежде чем повторно отправлять, иначе можно выполнить рендеринг дважды.
  • Длинный вход и вывод 4K увеличивают время выполнения. Если вы постоянно получаете тайм-ауты, снизьте разрешение или сократите видео, чтобы убедиться, что процесс работает, а затем постепенно возвращайтесь обратно.
  • Если задача сообщает failed, прочитайте сообщение об ошибке перед повторной попыткой. Слепой повтор при детерминированной ошибке параметров только умножит затраты.

Эффективный порядок отладки

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

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

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

Разрешение

Разрешение вывода — самый крупный единичный рычаг. Биллинг привязан к объёму работы, выполняемой при рендеринге, а вывод более высокого разрешения означает больше работы. Эмпирическое правило: итерируйте в низком разрешении, доставляйте в высоком. Никогда не запускайте эксперименты со стилем в 4K.

Длительность входа

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

Повторные попытки

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

Пакетная обработка и параллелизм

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

Контрольный список бюджета

  • Зафиксируйте промпт в низком разрешении перед любым рендерингом для доставки.
  • Кэшируйте завершённые результаты; не выполняйте повторный рендеринг одинаковых входных данных.
  • Задайте ожидания по расходам на задачу и на пакет и оповещайте при превышении пакетом лимита.
  • Отслеживайте зависимость длительности задачи от разрешения и длительности входа, чтобы прогнозировать новую работу по прошлым запускам.
  • Рассматривайте 4K как последний шаг процесса, а не как интерактивный режим.

Цены на эту конечную точку указаны на сайте HiAPI, поэтому перед планированием размера пакета проверьте текущие тарифы там. Сначала добейтесь работы минимального запроса, а затем осознанно масштабируйте разрешение и длительность — такой порядок позволяет держать и задержку, и счета предсказуемыми.

Похожие статьи

Все статьи →

Начните работать с постоянными артефактами ИИ

Получите API-ключ и вызывайте модели изображений, видео и аудио через один API на основе tasks.

Читать документацию API