Как вызвать API преобразования текста в видео Kling 2.5 Turbo: руководство по curl и Python

Что вам даёт эндпоинт kling-2.5-turbo/text-to-video

kling-2.5-turbo/text-to-video — это модель преобразования текста в видео, доступная через HiAPI. Вы даёте ей текстовый запрос, а она возвращает сгенерированное видео. Слово «turbo» в названии говорит о направлении оптимизации: более быстрый оборот по сравнению со стандартным качеством за счёт потери части деталей. Для черновых рендеров, превью раскадровок, нарезок для соцсетей и творческих итераций этот компромисс обычно оправдан.

Прежде чем писать первую строку кода, важнее всего усвоить одно: это асинхронный эндпоинт. Генерация видео занимает от секунд до минут — гораздо больше любого разумного HTTP-таймаута. Поэтому API разделён на две операции:

1. Отправка — вы POST-запросом передаёте запрос и параметры и сразу получаете идентификатор задачи.
2. Опрос — вы многократно выполняете GET-запрос задачи по этому идентификатору, пока она не достигнет терминального состояния, а затем читаете результат видео из payload завершённого ответа.

Если вы попытаетесь смоделировать это как один блокирующий вызов, вы столкнётесь с таймаутами, повторной генерацией при повторах и сбросами соединения под высокой нагрузкой. Шаблон «сначала отправить, потом опрашивать» — это не досадная помеха, которую нужно обойти; это правильная ментальная модель. Каждый пример кода ниже построен вокруг неё, и как только вы это усвоите, остальная часть интеграции окажется простой.

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

Структура запроса: запрос, быстрый пресет и гибкая длительность

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

Запрос

Запрос — это основной творческий ввод. Относитесь к нему как к описанию кадра, а не как к поисковому запросу. Хороший запрос для этой модели обычно включает:

• Субъект — кто или что находится на экране.
• Действие — что субъект делает в течение фрагмента.
• Камера — композиция и движение, например slow dolly in, static wide shot, handheld follow.
• Окружение и свет — сцена, время, атмосфера.
• Стиль — если вы хотите направить восприятие, можно указать cinematic, anime, product photography и т. п.

Будьте конкретны и ставьте субъект в начало. Расплывчатые запросы порождают расплывчатое движение, и режим turbo усиливает это, поскольку оставляет меньше пространства для интерпретации.

Пресет fast/turbo

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

Гибкая длительность

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

Дисциплина полей

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

Отправка запроса с помощью curl

Каждый вызов HiAPI использует одну и ту же схему аутентификации: bearer-токен в заголовке Authorization. Храните ключ в переменной окружения, чтобы он не попадал в историю оболочки или в закоммиченные скрипты.

export HIAPI_API_KEY="your_api_key_here"

Затем отправьте задачу. Точные имена полей и путь эндпоинта следует брать из справки по модели; ниже приведена каноническая форма:

curl -X POST "https://api.hiapi.ai/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-2.5-turbo/text-to-video",
    "prompt": "A slow dolly-in on a ceramic coffee cup on a wooden table, morning light raking across the surface, steam rising, shallow depth of field, cinematic",
    "duration": 5,
    "fast": true
  }'

В ответ вы должны получить не видео, а подтверждение с идентификатором задачи и её начальным состоянием — обычно состоянием queued или processing плюс поле id. Сохраните этот ID; это дескриптор для всех последующих операций.

Минимальный ответ выглядит примерно так:

{
  "id": "job_abc123",
  "status": "queued",
  "model": "kling-2.5-turbo/text-to-video"
}

Вызов отправки должен возвращаться быстро — при нормальных условиях значительно меньше секунды. Если он зависает, проблема в соединении или аутентификации, а не в модели. Если возвращается 401, проверьте формат заголовка (префикс Bearer важен). Если возвращается 422, ваше JSON-тело имеет неверный формат или в нём отсутствуют обязательные поля.

Не добавляйте к этому вызову -L, повторы или длинные таймауты. Шаг отправки либо быстро завершается успехом, либо быстро завершается ошибкой. Всё ожидание происходит в цикле опроса, о котором речь пойдёт далее.

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

Версия на Python — это тонкая обёртка над тем же HTTP-контрактом. Используйте requests с общим Session, чтобы пул соединений работал как при отправке, так и при каждом опросе. Оберните это в функции, чтобы остальной ваш код никогда не касался сырого HTTP напрямую.

import os
import time
import requests

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

session = requests.Session()

def submit_video(prompt: str, duration: int = 5, fast: bool = True) -> str:
    body = {
        "model": "kling-2.5-turbo/text-to-video",
        "prompt": prompt,
        "duration": duration,
        "fast": fast,
    }
    resp = session.post(f"{BASE}/video/generations", json=body, headers=HEADERS, timeout=15)
    resp.raise_for_status()
    return resp.json()["id"]

def poll_video(job_id: str, timeout_s: int = 600, interval_s: float = 3.0) -> dict:
    deadline = time.monotonic() + timeout_s
    delay = interval_s
    while time.monotonic() < deadline:
        resp = session.get(f"{BASE}/video/generations/{job_id}", headers=HEADERS, timeout=15)
        resp.raise_for_status()
        data = resp.json()
        status = data.get("status")
        if status in ("succeeded", "failed", "cancelled"):
            return data
        time.sleep(delay)
        delay = min(delay * 1.5, 15.0)
    raise TimeoutError(f"job {job_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    job = submit_video("A slow dolly-in on a ceramic coffee cup, morning light, steam rising, cinematic")
    result = poll_video(job)
    print(result)

Несколько деталей стоит сохранить, а не вырезать: timeout на каждом запросе, чтобы зависший сокет не подвешивал ваш worker; экспоненциальная задержка с разумным上限ом; и отдельный TimeoutError, чтобы вызывающий код мог отличить «всё ещё выполняется» от «сломалось».

Если вы предпочитаете httpx, перевод прямолинеен — те же методы, URL и JSON-тело. Транспортный слой — не самая интересная часть; контракт важнее. Прежде чем начинать опрос, сохраните job_id в надёжном месте, чтобы перезапуск не осиротил выполняющуюся генерацию.

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

Цикл опроса — место, где обитает большинство багов интеграции. Три правила делают его надёжным.

Правило 1: цикл завершается только по терминальному состоянию

Вы увидите переходные состояния — queued, processing — и терминальные, такие как succeeded, failed и cancelled. Только терминальное состояние завершает цикл. Не считайте неизвестную строку состояния успехом и не прерывайтесь на processing. Логируйте состояние на каждой итерации; когда в два часа ночи что-то пойдёт не так, эта запись будет единственным доказательством.

Правило 2: делайте задержку, а не холостой ход

Для задачи, занимающей минуту, опрос раз в секунду — это расточительство; а при запуске пакетных задач агрессивный опрос может упереться в ограничения скорости. Начинайте примерно с двух-трёх секунд, умножайте примерно на 1,5 каждый раз с上限ом в десять-пятнадцать секунд. Общее число запросов для минуты падает с шестидесяти до менее пятнадцати, а худшая задержка обнаружения остаётся равной значению上限а.

Правило 3: разделяйте актив и метаданные

Payload завершённого ответа содержит и то, и другое. Само видео доставляется в виде URL (и обычно с сроком действия), а всё остальное — ID задачи, модель, длительность, состояние, затраченное время — это метаданные о том, как вы его получили. Прочитайте URL, скачайте своевременно и сохраните у себя. URL сгенерированных активов — не постоянный CDN; относитесь к ним как к передаче, а не как к дому. Сохраняйте ID задачи вместе со своей копией, чтобы вы могли проследить любой фрагмент до точного запроса, который его породил.

Замечание о failed

Состояние failed — это результат уровня задачи, а не транспортная ошибка. HTTP-вызов успешен; генерация — нет. Прочитайте payload ошибки — он может указывать на отказ по политике контента, неподдерживаемую комбинацию параметров или внутренний сбой. Повторный запрос при отказе по политике снова провалится, поэтому перед рассмотрением повтора разветвляйтесь по причине.

Обработка ошибок, таймаутов и повторов

Различайте два мира ошибок и обрабатывайте их по отдельности.

Транспортные ошибки — это HTTP-сбои: сброс соединения, ответы 5xx, ограничение скорости 429 и клиентские таймауты. Они ничего не говорят о том, выполнялась ли задача. Повторяйте с экспоненциальной задержкой и джиттером, ограничивая число попыток.

Ошибки уровня задачи — это терминальные состояния в успешном HTTP-ответе. Задача выполнилась и дала определённый результат. Повтор опроса не поможет; если вы хотите повторить, это будет новая отправка, и только если причина сбоя временная.

Повторяйте правильные вещи

Это тонкая часть. Если ваш вызов отправки истёк по времени, вы не знаете, принял ли сервер задачу. Слепой повторный запрос может породить две генерации и два списания. Более безопасный шаблон — сделать отправку идемпотентной с помощью client-side ключа запроса, который вы отправляете как заголовок или поле тела, чтобы повторная отправка возвращала исходную задачу, а не запускала новую. Если используемый вами API не предоставляет этого, то при таймауте отправки логируйте хэш запроса и длительность и проверяйте свои недавние задачи перед повторной отправкой.

Таймауты на каждом уровне

Задайте три разных таймаута и не смешивайте их:

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

Практическая стратегия повторов

Повторяйте 429 и 5xx с задержкой и небольшим上限ом. Никогда не повторяйте 400, 401, 403 или 422 — это баги в вашем запросе, их повтор лишь сжигает квоту. Логируйте тело каждого неудачного ответа; payload ошибок HiAPI обычно указывает на проблемное поле.

Безопасность при пакетной обработке

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

Производственный чек-лист перед запуском

Прежде чем это покинет ноутбук, зафиксируйте эти решения.

• Таймауты и дедлайны. Для каждого вызова есть таймаут на запрос, есть общий дедлайн задачи и явная политика на случай, когда задача становится осиротевшей. Запишите их как константы, а не магические числа.
• Сохранение ID. Сохраняйте job_id и хэш запроса до начала опроса. Это ключ, делающий возможными перезапуски и аудит.
• Хранение активов. При успехе скачивайте готовое видео в свой собственный бакет. Никогда не отправляйте во фронтенд или в базу данных URL, который вы не контролируете, как постоянную ссылку.
• Логирование. Логируйте каждый переход состояния с ID задачи, моделью, длительностью, пресетом и затраченным временем. Когда появятся вопросы о стоимости или качестве, это будет набор данных для ответов на них.
• Осознание стоимости. Оплата рассчитывается по выходным секундам, поэтому длительность — ваш главный рычаг стоимости. Пресет turbo удерживает задержку (а значит, и занятость воркеров) низкой. Отслеживайте сгенерированные секунды по каждой функции, чтобы обсуждение стоимости опиралось на реальные цифры, а не на догадки.
• Идемпотентность. Используйте client-side ключ запроса при отправке и определите правила, что считается безопасной повторной отправкой.
• UX при сбоях. Решите сейчас, что видит пользователь при сбое уровня задачи: кнопку повтора, резервный запрос или просто текстовое сообщение. Молчаливый холостой ход — худший вариант.
• Версионирование запросов. Храните запросы в конфигурации, а не инлайном в обработчиках, чтобы вы могли сравнивать вывод разных вариантов без повторного развёртывания.

Сам эндпоинт мал — одна отправка, один опрос. Почти все инженерные усилия находятся в жизненном цикле вокруг него, и именно там решается производственное качество. Начните со справки по модели kling-2.5-turbo/text-to-video на HiAPI, а затем постройте вокруг неё описанные здесь строительные леса.