Как использовать happyhorse-1.1 через API hiapi: текст в видео, изображение в видео и референс в видео

Если вы ищете, как использовать happy horse 1.1, вот краткая версия: happyhorse-1.1 — это не один эндпоинт модели, а три, и все они доступны через единый асинхронный task API hiapi:

Эндпоинт (ID модели)	Функция	Обязательные входные данные
happyhorse-1.1/text-to-video	Генерация видео по текстовому промпту	prompt
happyhorse-1.1/image-to-video	Оживление статичного изображения	image_urls
happyhorse-1.1/reference-to-video	Генерация видео под управлением референсных изображений и промпта	prompt, reference_image

Все три эндпоинта используют одинаковый жизненный цикл: POST /v1/tasks для отправки → получение taskId → опрос GET /v1/tasks/<id> (или получение callback) → скачивание output[0].url. Каждая таблица параметров и каждое сообщение об ошибке ниже проверены на живом API — ничего не взято из догадок.

Предварительные условия

Вам нужно только одно: API-ключ hiapi. Получите его в консоли hiapi — он выглядит как sk-... и передаётся в заголовке Authorization: Bearer. Генерация видео тарифицируется по секундам выходного видео; актуальные ставки за секунду для каждого эндпоинта смотрите на странице цен.

export HIAPI_KEY="sk-your-key-here"

Минимальный рабочий пример (текст в видео)

Отправьте задачу:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/text-to-video",
    "input": {
      "prompt": "A golden retriever puppy runs through a sunlit meadow, slow motion, cinematic",
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "duration": 5
    }
  }'

Ответ вернёт вам ID задачи в поле data.taskId. Опрашивайте его:

curl -s https://api.hiapi.ai/v1/tasks/<taskId> \
  -H "Authorization: Bearer $HIAPI_KEY"

Когда data.status станет success, URL видео будет находиться в data.output[0].url.Скачайте его сразу — URL вывода содержит метку времени expireAt и хранится во временном хранилище, поэтому относитесь к ним как к окну для получения файла, а не как к постоянному хостингу.

Ниже полный скрипт Python для того же процесса (используется только стандартная библиотека):

import json
import time
import urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-your-key-here"

def api(method, url, payload=None):
    req = urllib.request.Request(url, method=method)
    req.add_header("Authorization", f"Bearer {KEY}")
    req.add_header("Content-Type", "application/json")
    data = json.dumps(payload).encode() if payload else None
    with urllib.request.urlopen(req, data=data) as resp:
        return json.loads(resp.read())

# 1. Submit
task = api("POST", API, {
    "model": "happyhorse-1.1/text-to-video",
    "input": {
        "prompt": "A golden retriever puppy runs through a sunlit meadow, cinematic",
        "aspect_ratio": "16:9",
        "resolution": "720p",
        "duration": 5,
    },
})
task_id = task["data"]["taskId"]
print("submitted:", task_id)

# 2. Poll until terminal state
while True:
    data = api("GET", f"{API}/{task_id}")["data"]
    status = data["status"]
    if status == "success":
        video_url = data["output"][0]["url"]
        break
    if status == "fail":
        raise RuntimeError(f"task failed: {data.get('error')}")
    time.sleep(5)

# 3. Download before the URL expires
urllib.request.urlretrieve(video_url, "output.mp4")
print("saved output.mp4")

Параметры каждого эндпоинта

Схема входных данных строгая: неизвестные поля отклоняются с ошибкой 400, а не игнорируются молча. Поля вроде size, seed, negative_prompt и audio возвращают additional properties ... not allowed. Ниже приведены параметры, которые каждый эндпоинт действительно принимает.

happyhorse-1.1/text-to-video

Поле	Обязательно	Тип	Допустимые значения
prompt	✅	string	Описание вашей сцены
aspect_ratio	—	string	16:9, 9:16, 3:4, 4:3, 4:5, 5:4, 1:1, 9:21, 21:9
resolution	—	string	720p, 1080p
duration	—	integer	3–15 (секунд)

Полное руководство с приёмами составления промптов: руководство по тексту в видео happyhorse-1.1.

happyhorse-1.1/image-to-video

Поле	Обязательно	Тип	Допустимые значения
image_urls	✅	массив строк	ровно 1 общедоступный URL изображения (maxItems: 1)
prompt	—	string	Управление движением/сценой для анимации
resolution	—	string	720p, 1080p
duration	—	integer	3–15 (секунд)

Здесь есть две типичные ловушки. Во-первых, image_urls — это массив, но сейчас принимается только один элемент: передавайте ["https://..."], а не голую строку и не несколько URL. Во-вторых, у этого эндпоинта нет aspect_ratio (API его отклонит); формат вывода наследуется от исходного изображения.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/image-to-video",
    "input": {
      "image_urls": ["https://your-cdn.example.com/product-shot.jpg"],
      "prompt": "slow camera push-in, soft studio lighting",
      "resolution": "720p",
      "duration": 5
    }
  }'

Подробнее: руководство по изображению в видео happyhorse.

happyhorse-1.1/reference-to-video

Поле	Обязательно	Тип	Допустимые значения
prompt	✅	string	Описание сцены
reference_image	✅	массив строк	1–9 общедоступных URL изображений (maxItems: 9)
aspect_ratio	—	string	Те же 9 соотношений, что и в тексте в видео
resolution	—	string	720p, 1080p
duration	—	integer	3–15 (секунд)

Это эндпоинт для «сохранить моего персонажа/продукт неизменным»: референсные изображения задают идентичность и стиль, а промпт управляет движением. В отличие от изображения в видео, здесь снова доступно управление aspect_ratio, и можно передать до 9 референсных изображений.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/reference-to-video",
    "input": {
      "prompt": "the character waves at the camera and smiles, city street at dusk",
      "reference_image": ["https://your-cdn.example.com/character-front.jpg",
                          "https://your-cdn.example.com/character-side.jpg"],
      "aspect_ratio": "9:16",
      "resolution": "720p",
      "duration": 5
    }
  }'

Подробнее: руководство по референсу в видео happyhorse-1.1.

Какой эндпоинт выбрать?

• У вас есть только идея → text-to-video. Самый быстрый путь от текста к движению.
• У вас есть конкретный кадр, который нужно оживить (фото продукта, иллюстрация, фотография) → image-to-video. Исходное изображение и есть первый кадр.
• Вам нужно сохранить один и тот же субъект в нескольких фрагментах (персонаж, маскот, продукт под разными углами) → reference-to-video. Референсы фиксируют идентичность; промпт меняется от фрагмента к фрагменту.

Паттерны для продакшена

Используйте callback вместо опроса

Для любого использования, выходящего за рамки скрипта, регистрируйте webhook при создании задачи — генерация видео занимает долго, а опрос внутри обработчика веб-запросов рано или поздно приведёт к тайм-ауту:

{
  "model": "happyhorse-1.1/text-to-video",
  "input": { "prompt": "..." },
  "callback": { "url": "https://your-app.example.com/hooks/hiapi", "when": "final" }
}

Поддерживается только "when": "final" — когда задача достигает терминального состояния, вы получаете ровно один POST (любое другое значение вернёт invalid callback.when: only 'final' is supported). Проектируйте обработчик идемпотентным по taskId: сохраняйте ID задачи при отправке и считайте повторные или уже обработанные callback'и пустой операцией. Оставьте низкочастотный опрос в качестве запасного механизма на случай потери callback из-за сетевых сбоев.

Обработка ошибок: три класса сбоев

1. Ошибки валидации (HTTP 400, INVALID_REQUEST). Сообщения очень точные — прочитайте их, они укажут конкретное поле:

{
  "code": 400,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: duration: maximum: got 99, want 15; resolution: value must be one of '720p', '1080p'"
}

2. Ошибки аутентификации/прав доступа (HTTP 401, permission_denied). Ключ неверен или у ключа нет доступа к этой модели:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key cannot use the selected model. ...",
    "request_id": "2026..."
  }
}

Проверьте ключ в консоли, а если обращаетесь в поддержку, приложите request_id.

3. Ошибки генерации (задача в состоянии status: "fail"). Отправка прошла успешно, но генерация не удалась; при опросе или получении callback подробности ошибки находятся в поле error объекта задачи. Такие ошибки стоит повторять с экспоненциальной задержкой — ошибки валидации и аутентификации повторять не стоит.

Контроль затрат

Тарификация идёт по секундам сгенерированного видео, поэтому duration — ваш главный рычаг затрат: 15-секундный фрагмент стоит в 3 раза дороже 5-секундного, а resolution влияет меньше. Итеративно работайте над промптом с duration: 3 и 720p, а затем рендерите финальную версию на полную длину. Актуальные ставки смотрите на странице цен.

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

• happyhorse-1.1 текст в видео — страница модели и песочница
• happyhorse-1.1 изображение в видео — страница модели и песочница
• happyhorse-1.1 референс в видео — страница модели и песочница
• Рабочий процесс коротких видео с happyhorse-1.1
• Документация hiapi

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

Можно ли использовать изображение и текстовый промпт одновременно? Да — image-to-video принимает необязательный prompt в дополнение к обязательному image_urls, а reference-to-video требует одновременно prompt и reference_image. Только text-to-video работает исключительно по промпту.

Сколько изображений можно передать? image-to-video: ровно одно (image_urls ограничен 1 элементом). reference-to-video: до девяти в reference_image. Оба принимают массивы общедоступных URL, а не загруженные файлы или base64.

Поддерживает ли happyhorse-1.1 параметры seed, negative_prompt или audio? Нет. Схема входных данных строгая и отклоняет все три с ошибкой 400 additional properties not allowed. Если вам нужна воспроизводимость, сохраняйте промпты и параметры в точности одинаковыми и ведите их версионирование на своей стороне.

Какие доступны разрешения и длительности? Все три эндпоинта: 720p или 1080p, а также от 3 до 15 секунд (целое число). Если опустить, применяются значения по умолчанию.

Почему я получаю 401 permission_denied с ключом, который кажется действительным? Ключ существует, но не может использовать эту модель — это часто бывает с ключами с ограниченной областью или пробными ключами. Проверьте права ключа на модели в консоли или создайте новый неограниченный ключ.

Как узнать, что видео готово, без опроса? Передайте при отправке callback: {"url": "...", "when": "final"}. Когда задача достигает success или fail, hiapi один раз отправляет POST на ваш URL. Помните, что URL вывода истекают — скачивайте файл в обработчике callback, не используйте горячие ссылки.