Документация API HappyHorse

Полное руководство по интеграции API генерации видео HappyHorse 1.0 в ваши приложения.

API v1.0 Base URL: https://happyhorse.app

Быстрый старт

bash
curl -X POST 'https://happyhorse.app/api/generate' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "happyhorse-1.0/video",
    "prompt": "A cinematic shot of mountains at sunrise",
    "mode": "pro",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

Аутентификация

Все запросы к API требуют токена Bearer в заголовке Authorization.

Получить API-ключ: API-ключ можно получить на странице API Keys в панели управления. → Получить API-ключ

http
Authorization: Bearer YOUR_API_KEY

Как работают Generate и Status

Видео-задачи HappyHorse выполняются асинхронно: создайте задачу через POST /api/generate, сохраните возвращенный task_id и проверяйте GET /api/status до финального статуса.

1

Создать задачу

Отправьте prompt, model, mode, duration и необязательные изображения в /api/generate. Успешный ответ сразу вернет task_id.

2

Опрашивать статус

Используйте task_id с /api/status. Пока status равен IN_PROGRESS, видео еще рендерится, а response остается null.

3

Прочитать результат

Когда status станет SUCCESS, data.response.resultUrls[0] будет URL видео. Если статус FAILED, покажите error_message и остановите опрос.

Доступные модели

HappyHorse 1.0

HappyHorse 1.0

Высококачественная генерация видео с ИИ на базе HappyHorse

ТипОписаниеДлительностьКредиты
pro (text-to-video)Текст в видео, качество Pro3-15s54/s (no audio) · 80/s (with audio)
pro (image-to-video)Изображение в видео, качество Pro3-15s54/s (no audio) · 80/s (with audio)
std (text-to-video)Текст в видео, стандартное качество3-15s40/s (no audio) · 60/s (with audio)
std (image-to-video)Изображение в видео, стандартное качество3-15s40/s (no audio) · 60/s (with audio)

Конечные точки API

Создаёт задачу генерации видео. Поле model должно быть 'happyhorse-1.0/video'.

Тело запроса

Параметры телаJSON
model:string

Имя модели — 'happyhorse-1.0/video'

prompt:optional string

Текстовое описание видео (до 2500 символов). Не обязательно, если multi_shots равно true.

mode:optional string

Режим качества: 'pro' или 'std' (по умолчанию: std) Defaults to std.

duration:optional number

Длительность в секундах (3–15). В multi-shot режиме итоговая длительность вычисляется из multi_prompt; если передаёте duration явно, она должна совпадать с суммой длительностей всех сцен. Defaults to 5 / sum(multi_prompt).

aspect_ratio:optional string

Соотношение сторон (16:9, 9:16, 1:1) Defaults to 16:9.

image_urls:optional string[]

Массив URL изображений для image-to-video

sound:optional boolean

Включить нативное аудио (по умолчанию: true). Для multi-shot запросов передавайте это поле явно как true или false. Defaults to true.

cfg_scale:optional number

Сила следования промпту (0-1, по умолчанию: 0.5). Более высокие значения точнее следуют промпту. Defaults to 0.5.

multi_shots:optional boolean

Режим нескольких кадров с несколькими промптами Defaults to false.

multi_prompt:optional array

Массив объектов 'prompt, duration' для multi-shot

happyhorse_elements:optional array

Массив объектов элементов. В тексте промпта пишите @ и сразу значение поля name (например name 'element_dog' → в промпте @element_dog). Каждый элемент: name, description, element_input_urls (2-4 URL изображений). Не более 3 элементов на задачу.

Текст в видео

json
{
  "model": "happyhorse-1.0/video",
  "prompt": "A majestic eagle soaring through clouds at sunset",
  "mode": "pro",
  "duration": 5,
  "aspect_ratio": "16:9",
  "sound": true
}

Изображение в видео

json
{
  "model": "happyhorse-1.0/video",
  "prompt": "The character slowly turns and smiles",
  "mode": "pro",
  "image_urls": ["https://example.com/my-image.jpg"],
  "duration": 5
}

Мультикадровое видео

json
{
  "model": "happyhorse-1.0/video",
  "mode": "pro",
  "multi_shots": true,
  "sound": true,
  "duration": 10,
  "multi_prompt": [
    { "prompt": "A woman walks into a coffee shop", "duration": 3 },
    { "prompt": "She orders a latte and sits by the window", "duration": 4 },
    { "prompt": "She looks outside and smiles", "duration": 3 }
  ],
  "aspect_ratio": "16:9"
}

Ответы

Task created successfully

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "n92abc123hh10",
    "status": "IN_PROGRESS"
  }
}

Проверка статуса генерации по task_id из ответа generate.

Параметры запроса

Параметры запроса
task_id:string

Уникальный ID задачи из generate (префикс n92)

Пример запроса

bash
curl -X GET 'https://happyhorse.app/api/status?task_id=n92abc123hh10' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Подсказка: Поле response содержит массив resultUrls. URL видео: data.response.resultUrls[0].

javascript
// Extract video URL after the task is complete
const task = payload.data;
const videoUrl = task.status === "SUCCESS"
  ? task.response?.resultUrls?.[0]
  : null;

Ответы

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "n92abc123hh10",
    "status": "SUCCESS",
    "consumed_credits": 400,
    "created_at": "2026-04-08T10:30:00Z",
    "type": "text-to-video",
    "request": {
      "model": "happyhorse-1.0/video",
      "prompt": "A majestic eagle soaring through clouds at sunset",
      "mode": "pro",
      "duration": 5,
      "aspect_ratio": "16:9"
    },
    "response": {
      "resultUrls": [
        "https://cdn.example.com/videos/abc123.mp4"
      ]
    },
    "error_message": null
  }
}

Лучшие практики опроса

Генерация видео может занять время, поэтому проверяйте статус как спокойную фоновую задачу, а не как частый цикл запросов.

Начните с короткой паузы

Подождите около 8-10 секунд перед первой проверкой, затем опрашивайте каждые 10-20 секунд. Более частый опрос не ускорит готовность видео.

Останавливайтесь на финальных статусах

SUCCESS и FAILED являются финальными. Остановите опрос сразу после любого из них и сохраните task_id для поддержки или последующей проверки.

Используйте таймаут клиента

Через 10-15 минут остановите активное ожидание и дайте пользователю проверить статус вручную позже. Не оставляйте вкладку браузера опрашивать бесконечно.

При ошибках снижайте частоту

Если получен 429 или временная сетевая ошибка, подождите дольше перед следующим запросом. При 401 или 402 попросите пользователя проверить API Key или кредиты.

javascript
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function waitForHappyHorseVideo(taskId) {
  const deadline = Date.now() + 15 * 60 * 1000;
  let delayMs = 8000;

  while (Date.now() < deadline) {
    const res = await fetch(
      `${BASE_URL}/api/status?task_id=${encodeURIComponent(taskId)}`,
      { headers: { Authorization: `Bearer ${API_KEY}` } }
    );

    if (res.status === 429) {
      await sleep(Math.min(delayMs * 2, 30000));
      continue;
    }

    const payload = await res.json();
    if (!res.ok) {
      throw new Error(payload.message || `Status request failed: ${res.status}`);
    }

    const task = payload.data;
    if (task.status === "SUCCESS") {
      return task.response?.resultUrls?.[0];
    }
    if (task.status === "FAILED") {
      throw new Error(task.error_message || "Generation failed");
    }

    await sleep(delayMs);
    delayMs = Math.min(delayMs + 2000, 20000);
  }

  throw new Error("Timed out. Keep the task_id and check again later.");
}

Песочница API

Тестируйте API прямо в браузере. Замените YOUR_API_KEY на свой ключ.

Песочница APIPOST

Коды ошибок

HTTP-статусКодОписание
400 Неверный запросINVALID_PROMPTПромпт недействителен или пуст
400 Неверный запросINVALID_DURATIONДлительность вне допустимого диапазона (3–15 с)
400 Неверный запросINVALID_MODELМодель должна быть 'happyhorse-1.0/video'
401 Не авторизованINVALID_API_KEYAPI-ключ отсутствует или недействителен
402 Требуется оплатаINSUFFICIENT_CREDITSНедостаточно кредитов для операции
429 Слишком много запросовRATE_LIMITEDСлишком много запросов, снизьте частоту
500 Внутренняя ошибка сервераINTERNAL_ERRORОшибка сервера, повторите позже