Документация API HappyHorse
Полное руководство по интеграции API генерации видео HappyHorse 1.0 в ваши приложения.
Быстрый старт
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-ключ
Authorization: Bearer YOUR_API_KEYКак работают Generate и Status
Видео-задачи HappyHorse выполняются асинхронно: создайте задачу через POST /api/generate, сохраните возвращенный task_id и проверяйте GET /api/status до финального статуса.
Создать задачу
Отправьте prompt, model, mode, duration и необязательные изображения в /api/generate. Успешный ответ сразу вернет task_id.
Опрашивать статус
Используйте task_id с /api/status. Пока status равен IN_PROGRESS, видео еще рендерится, а response остается null.
Прочитать результат
Когда status станет SUCCESS, data.response.resultUrls[0] будет URL видео. Если статус FAILED, покажите error_message и остановите опрос.
Доступные модели
HappyHorse 1.0
Высококачественная генерация видео с ИИ на базе HappyHorse
| Тип | Описание | Длительность | Кредиты |
|---|---|---|---|
pro (text-to-video) | Текст в видео, качество Pro | 3-15s | 54/s (no audio) · 80/s (with audio) |
pro (image-to-video) | Изображение в видео, качество Pro | 3-15s | 54/s (no audio) · 80/s (with audio) |
std (text-to-video) | Текст в видео, стандартное качество | 3-15s | 40/s (no audio) · 60/s (with audio) |
std (image-to-video) | Изображение в видео, стандартное качество | 3-15s | 40/s (no audio) · 60/s (with audio) |
Конечные точки API
Создаёт задачу генерации видео. Поле model должно быть 'happyhorse-1.0/video'.
Тело запроса
Имя модели — 'happyhorse-1.0/video'
Текстовое описание видео (до 2500 символов). Не обязательно, если multi_shots равно true.
Режим качества: 'pro' или 'std' (по умолчанию: std) Defaults to std.
Длительность в секундах (3–15). В multi-shot режиме итоговая длительность вычисляется из multi_prompt; если передаёте duration явно, она должна совпадать с суммой длительностей всех сцен. Defaults to 5 / sum(multi_prompt).
Соотношение сторон (16:9, 9:16, 1:1) Defaults to 16:9.
Массив URL изображений для image-to-video
Включить нативное аудио (по умолчанию: true). Для multi-shot запросов передавайте это поле явно как true или false. Defaults to true.
Сила следования промпту (0-1, по умолчанию: 0.5). Более высокие значения точнее следуют промпту. Defaults to 0.5.
Режим нескольких кадров с несколькими промптами Defaults to false.
Массив объектов 'prompt, duration' для multi-shot
Массив объектов элементов. В тексте промпта пишите @ и сразу значение поля name (например name 'element_dog' → в промпте @element_dog). Каждый элемент: name, description, element_input_urls (2-4 URL изображений). Не более 3 элементов на задачу.
Текст в видео
{
"model": "happyhorse-1.0/video",
"prompt": "A majestic eagle soaring through clouds at sunset",
"mode": "pro",
"duration": 5,
"aspect_ratio": "16:9",
"sound": true
}Изображение в видео
{
"model": "happyhorse-1.0/video",
"prompt": "The character slowly turns and smiles",
"mode": "pro",
"image_urls": ["https://example.com/my-image.jpg"],
"duration": 5
}Мультикадровое видео
{
"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.
Параметры запроса
Уникальный ID задачи из generate (префикс n92)
Пример запроса
curl -X GET 'https://happyhorse.app/api/status?task_id=n92abc123hh10' \
-H 'Authorization: Bearer YOUR_API_KEY'Подсказка: Поле response содержит массив resultUrls. URL видео: data.response.resultUrls[0].
// 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 или кредиты.
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 на свой ключ.
Коды ошибок
| HTTP-статус | Код | Описание |
|---|---|---|
| 400 Неверный запрос | INVALID_PROMPT | Промпт недействителен или пуст |
| 400 Неверный запрос | INVALID_DURATION | Длительность вне допустимого диапазона (3–15 с) |
| 400 Неверный запрос | INVALID_MODEL | Модель должна быть 'happyhorse-1.0/video' |
| 401 Не авторизован | INVALID_API_KEY | API-ключ отсутствует или недействителен |
| 402 Требуется оплата | INSUFFICIENT_CREDITS | Недостаточно кредитов для операции |
| 429 Слишком много запросов | RATE_LIMITED | Слишком много запросов, снизьте частоту |
| 500 Внутренняя ошибка сервера | INTERNAL_ERROR | Ошибка сервера, повторите позже |