HiAPI
Блог

Руководство

Как вызывать happyhorse-1.1/text-to-video через API HiAPI: рабочие примеры на curl и Python

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

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

Что охватывает эта интеграция

Это руководство проведёт вас через весь процесс вызова happyhorse-1.1/text-to-video через единый API HiAPI. После прочтения у вас будет рабочий запрос: отправка текстового промпта, опрос до завершения и сохранение сгенерированного видео с его встроенной звуковой дорожкой. Сначала мы рассмотрим структуру запроса, чтобы вы поняли полезную нагрузку ещё до написания кода; затем приведём готовый к копированию вызов curl; после объясним асинхронную схему опроса, необходимую для генерации видео; и наконец перенесём всё это в Python с базовой обработкой ошибок. Опыт работы с видео-API не требуется — вам понадобится только ключ API HiAPI и терминал или окружение Python. Цель — дать минимальный, но полный пример интеграции, который вы сможете адаптировать под свой пайплайн.

Структура запроса к happyhorse-1.1/text-to-video

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

{
  "model": "happyhorse-1.1/text-to-video",
  "prompt": "На рассвете камера медленно панорамирует над лесом в лёгком тумане"
}

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

Первый запрос через curl

Когда полезная нагрузка готова, задачу можно отправить с помощью curl. Вы отправите POST-запрос с JSON-телом и ключом API в заголовке Authorization. Ответ обычно содержит идентификатор задачи, который позже понадобится для опроса статуса. Вот рабочий пример:

curl -X POST https://api.hiapi.ai/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -d '{
    "model": "happyhorse-1.1/text-to-video",
    "prompt": "На рассвете камера медленно панорамирует над лесом в лёгком тумане"
  }'

Замените $HIAPI_API_KEY на ваш реальный ключ или экспортируйте его в оболочке. Ответ будет в формате JSON и содержать поле id (или аналогично названный идентификатор) и статус, означающий, что задача принята. Внимательно прочитайте ответ: если статус не означает принятие, сначала проверьте сообщение об ошибке, прежде чем продолжать. Не предполагайте, что видео уже готово; задача только что встала в очередь.

Обработка асинхронного опроса

Генерация видео не происходит мгновенно, поэтому HiAPI в первоначальном ответе возвращает идентификатор задачи, а не готовое видео. Вам нужно опрашивать эндпоинт статуса, пока задача не достигнет терминального состояния. Общая схема такова: отправить задачу, получить ID, затем с небольшими интервалами многократно запрашивать статус задачи. Остановитесь, когда статус означает успех или ошибку. Вот логика в виде псевдокода:

  1. Отправить задачу и прочитать id задачи.
  2. Подождать несколько секунд.
  3. Запросить статус задачи по этому id.
  4. Если статус "completed" или "succeeded", получить URL вывода и выйти из цикла.
  5. Если статус "failed", залогировать ошибку и выйти.
  6. Иначе снова подождать и повторить до разумного максимального числа попыток.

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

Встроенное аудио в выводе

Видео, сгенерированные happyhorse-1.1/text-to-video, содержат встроенное аудио прямо в выводе. Когда задача завершается, ответ указывает на сгенерированный видеофайл, который уже включает звуковую дорожку. Вам не нужно отдельно генерировать или извлекать аудио. Чтобы сохранить и проверить результат, скачайте видеофайл по предоставленному URL и сохраните его формат контейнера. Если вы обрабатываете файл программно, проверьте наличие аудиопотока, например с помощью медиаутилиты. Не удаляйте и не перекодируйте аудио, если этого не требует нижестоящий пайплайн, так как это может ухудшить качество или полностью удалить дорожку. Рассматривайте возвращённый файл как полноценный аудиовизуальный актив.

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

Перенести вызов curl на Python несложно: повторно используйте ту же JSON-полезную нагрузку и добавьте цикл опроса. В следующем примере используется requests, ожидание между попытками и выброс исключения при ошибке. Замените путь эндпоинта и имена полей статуса на те, что указаны в документации к happyhorse-1.1/text-to-video на HiAPI.

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 = {
    "model": "happyhorse-1.1/text-to-video",
    "prompt": "На рассвете камера медленно панорамирует над лесом в лёгком тумане",
}

resp = requests.post(f"{BASE}/video/generations", headers=HEADERS, json=payload)
resp.raise_for_status()
job = resp.json()
job_id = job["id"]

for attempt in range(60):
    status_resp = requests.get(f"{BASE}/video/generations/{job_id}", headers=HEADERS)
    status_resp.raise_for_status()
    status = status_resp.json()
    state = status.get("status")
    if state in ("completed", "succeeded"):
        video_url = status["output"]["url"]
        print("Видео готово:", video_url)
        break
    if state == "failed":
        raise RuntimeError(status.get("error", "Генерация не удалась"))
    time.sleep(5)
else:
    raise TimeoutError("Тайм-аут опроса")

Это следует описанной выше логике «опрашивать до завершения». Используйте raise_for_status(), чтобы быстро выявлять ошибки HTTP, и соблюдайте разумные интервалы ожидания, чтобы избежать лишних запросов.

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

Большинство проблем интеграции сводится к нескольким категориям. Неверно сформированная полезная нагрузка, например отсутствие поля model или неверный тип JSON, отклоняется сразу; внимательно сверяйте ваш JSON с документацией к модели. Слишком частый опрос может привести к ограничению скорости или ненужной нагрузке; увеличьте интервал ожидания. Принятие первоначального ответа за готовое видео — ещё одна распространённая ошибка; обязательно проводите опрос до терминального состояния. Ошибки аутентификации обычно означают отсутствующий или неверно сформированный заголовок Authorization, поэтому проверьте, правильно ли экспортирован ваш ключ API. Наконец, если задача завершилась с ошибкой после опроса, проверьте сообщение об ошибке в ответе о статусе; оно обычно указывает на недействительный промпт или неподдерживаемые параметры. Устранив эти проблемы, повторите попытку с минимальной валидной нагрузкой.

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

Все статьи →

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

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

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