happyhorse-1.0
happyhorse-1.0 — семейство моделей для генерации, референсной генерации и редактирования видео через CDNvideo AI Hub media API.
Base URL
https://api.cdnvideo.ru/app/aihub-router/v1/media
Для работы используется обычный ключ AI Hub в заголовке Authorization. Модель для маршрутизации передаётся в X-Model:
Authorization: Bearer ${AIHUB_API_KEY}
X-Model: happyhorse-1.0
Внутри тела запроса конкретный сценарий выбирается через поле model.
Асинхронная обработка
Happy Horse возвращает output.task_id, а не готовое видео. После создания задачи опрашивайте GET /happyhorse/v1/tasks/{taskId} до статуса SUCCEEDED, затем скачайте видео по output.video_url. Ссылка на видео хранится 24 часа.
Возможности happyhorse-1.0
| Backend model | Text-to-video | Image-to-video | Reference-to-video | Edit video |
|---|---|---|---|---|
happyhorse-1.0-t2v |
✅ | — | — | — |
happyhorse-1.0-i2v |
— | ✅ | — | — |
happyhorse-1.0-r2v |
— | — | ✅ | — |
happyhorse-1.0-video-edit |
— | — | — | ✅ |
Создание video-задачи
POST /happyhorse/v1/video-synthesis
Единый метод создаёт задачу для text-to-video, image-to-video, reference-to-video и video editing. Сценарий определяется значением model и содержимым input.media.
Параметры запроса
| Поле | Тип | Обязательное | По умолчанию | Описание |
|---|---|---|---|---|
model |
string |
Да | — | Backend model ID: happyhorse-1.0-t2v, happyhorse-1.0-i2v, happyhorse-1.0-r2v, happyhorse-1.0-video-edit. По умолчанию на стороне провайдера используется happyhorse-1.0-t2v. |
input |
object |
Да | — | Входные данные задачи. |
input.prompt |
string |
Зависит от сценария | — | Текстовый промпт. Поддерживает любые языки. Максимум 5000 не-китайских символов или 2500 китайских символов; лишний текст будет обрезан. |
input.media |
array<object> |
Зависит от сценария | — | Список входных медиа: первый кадр, референс-изображения или видео для редактирования. |
input.media[].type |
string |
Да, если передан input.media |
— | Тип медиа: first_frame, reference_image, video. |
input.media[].url |
string |
Да, если передан input.media |
— | Публичный URL медиа по HTTP или HTTPS. |
parameters |
object |
Нет | — | Параметры генерации. |
parameters.resolution |
string |
Нет | 1080P |
Разрешение результата: 720P или 1080P. |
parameters.ratio |
string |
Нет | 16:9 |
Соотношение сторон: 16:9, 9:16, 1:1, 4:3, 3:4. Используется для text-to-video и reference-to-video. |
parameters.duration |
integer |
Нет | 5 |
Длительность в секундах от 3 до 15. Используется для text-to-video, image-to-video и reference-to-video. |
parameters.watermark |
boolean |
Нет | true |
Добавлять водяной знак Happy Horse в правом нижнем углу. |
parameters.audio_setting |
string |
Нет | auto |
Только для video editing: auto — модель управляет аудио, origin — сохранить исходное аудио входного видео. |
parameters.seed |
integer |
Нет | — | Random seed от 0 до 2147483647. Даже при одинаковом seed результат не гарантируется полностью идентичным. |
Text-to-video
Для text-to-video используйте model: happyhorse-1.0-t2v. Поле input.prompt обязательно.
curl https://api.cdnvideo.ru/app/aihub-router/v1/media/happyhorse/v1/video-synthesis \
-H "Authorization: Bearer ${AIHUB_API_KEY}" \
-H "Content-Type: application/json" \
-H "X-Model: happyhorse-1.0" \
-d '{
"model": "happyhorse-1.0-t2v",
"input": {
"prompt": "A miniature city built of cardboard and bottle caps comes to life at night. A cardboard train moves slowly through it, dotted with small lights that illuminate the way."
},
"parameters": {
"resolution": "720P",
"ratio": "16:9",
"duration": 5,
"watermark": false
}
}'
Image-to-video
Для image-to-video используйте model: happyhorse-1.0-i2v. Промпт опционален, но нужно передать ровно одно изображение с type: first_frame.
curl https://api.cdnvideo.ru/app/aihub-router/v1/media/happyhorse/v1/video-synthesis \
-H "Authorization: Bearer ${AIHUB_API_KEY}" \
-H "Content-Type: application/json" \
-H "X-Model: happyhorse-1.0" \
-d '{
"model": "happyhorse-1.0-i2v",
"input": {
"prompt": "The scene comes alive with a slow cinematic camera move.",
"media": [
{
"type": "first_frame",
"url": "https://example.com/first-frame.png"
}
]
},
"parameters": {
"resolution": "1080P",
"duration": 5,
"watermark": false
}
}'
Требования к первому кадру
| Требование | Описание |
|---|---|
| Количество | Ровно 1 изображение с type: first_frame. |
| Форматы | JPEG, JPG, PNG, WEBP. |
| Размеры | Ширина и высота не меньше 300px. |
| Соотношение сторон | От 1:2.5 до 2.5:1. |
| Размер файла | До 10MB. |
Reference-to-video
Для reference-to-video используйте model: happyhorse-1.0-r2v. Промпт обязателен, а input.media должен содержать от 1 до 9 изображений с type: reference_image.
В промпте используйте character1, character2 и так далее, чтобы ссылаться на изображения из массива input.media в том же порядке.
curl https://api.cdnvideo.ru/app/aihub-router/v1/media/happyhorse/v1/video-synthesis \
-H "Authorization: Bearer ${AIHUB_API_KEY}" \
-H "Content-Type: application/json" \
-H "X-Model: happyhorse-1.0" \
-d '{
"model": "happyhorse-1.0-r2v",
"input": {
"prompt": "character1 walks through a neon-lit street and looks into the camera, cinematic lighting, smooth motion.",
"media": [
{
"type": "reference_image",
"url": "https://example.com/character1.jpg"
}
]
},
"parameters": {
"resolution": "1080P",
"ratio": "9:16",
"duration": 6,
"watermark": false
}
}'
Требования к reference image
| Требование | Описание |
|---|---|
| Количество | От 1 до 9 изображений с type: reference_image. |
| Форматы | JPEG, JPG, PNG, WEBP. |
| Размеры | Короткая сторона не меньше 400px; рекомендуются чёткие изображения выше 720P. |
| Размер файла | До 10MB. |
| URL | Публично доступный URL по HTTP или HTTPS. |
Video editing
Для редактирования видео используйте model: happyhorse-1.0-video-edit. Нужно передать ровно одно видео с type: video и опционально от 0 до 5 reference image.
curl https://api.cdnvideo.ru/app/aihub-router/v1/media/happyhorse/v1/video-synthesis \
-H "Authorization: Bearer ${AIHUB_API_KEY}" \
-H "Content-Type: application/json" \
-H "X-Model: happyhorse-1.0" \
-d '{
"model": "happyhorse-1.0-video-edit",
"input": {
"prompt": "Change the scene into a rainy cyberpunk night while preserving the main motion and camera framing.",
"media": [
{
"type": "video",
"url": "https://example.com/input-video.mp4"
},
{
"type": "reference_image",
"url": "https://example.com/style-reference.png"
}
]
},
"parameters": {
"resolution": "1080P",
"audio_setting": "origin",
"watermark": false
}
}'
Требования к видео для редактирования
| Требование | Описание |
|---|---|
| Количество | Ровно 1 видео с type: video. |
| Форматы | MP4, MOV; рекомендуется H.264. |
| Длительность | От 3 до 60 секунд. Если видео длиннее 15 секунд, используется первый 15-секундный сегмент. |
| Размеры | Длинная сторона не больше 2160px, короткая сторона не меньше 320px. |
| Соотношение сторон | От 1:2.5 до 2.5:1. |
| Размер файла | До 100MB. |
| Частота кадров | Больше 8fps. |
Требования к reference image для редактирования
| Требование | Описание |
|---|---|
| Количество | От 0 до 5 изображений с type: reference_image. |
| Форматы | JPEG, JPG, PNG, WEBP. |
| Размеры | Ширина и высота не меньше 300px. |
| Соотношение сторон | От 1:2.5 до 2.5:1. |
| Размер файла | До 10MB. |
Параметры ответа создания задачи
| Поле | Тип | Описание |
|---|---|---|
output |
object |
Информация о созданной задаче. |
output.task_id |
string |
ID задачи для запроса результата. |
output.task_status |
string |
Статус задачи: PENDING, RUNNING, SUCCEEDED, FAILED, CANCELED, UNKNOWN. |
request_id |
string |
Уникальный идентификатор запроса. |
code |
string |
Код ошибки. Возвращается только при неуспешном запросе. |
message |
string |
Текст ошибки. Возвращается только при неуспешном запросе. |
Ответ создания задачи
{
"output": {
"task_status": "PENDING",
"task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
},
"request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}
Получение результата
GET /happyhorse/v1/tasks/{taskId}
Метод возвращает статус задачи и URL готового видео при успешном завершении. Статус задачи доступен в течение 24 часов.
Path-параметры
| Параметр | Тип | Обязательное | Описание |
|---|---|---|---|
taskId |
string |
Да | ID задачи из поля output.task_id. |
Параметры ответа
| Поле | Тип | Описание |
|---|---|---|
output |
object |
Информация о задаче. |
output.task_id |
string |
ID задачи. Статус задачи доступен для запроса 24 часа. |
output.task_status |
string |
Статус задачи. |
output.submit_time |
string |
Время отправки задачи в формате YYYY-MM-DD HH:mm:ss.SSS, часовой пояс UTC+8. |
output.scheduled_time |
string |
Время начала выполнения в формате YYYY-MM-DD HH:mm:ss.SSS, часовой пояс UTC+8. |
output.end_time |
string |
Время завершения в формате YYYY-MM-DD HH:mm:ss.SSS, часовой пояс UTC+8. |
output.video_url |
string |
URL готового видео. Возвращается только при task_status: SUCCEEDED; ссылка действует 24 часа. |
output.orig_prompt |
string |
Исходный промпт из запроса. |
output.code |
string |
Код ошибки. Возвращается только при неуспешной задаче. |
output.message |
string |
Текст ошибки. Возвращается только при неуспешной задаче. |
usage |
object |
Информация для расчёта использования: длительность, разрешение, соотношение сторон и количество видео. |
usage.input_video_duration |
integer |
Длительность входного видео в секундах. |
usage.output_video_duration |
integer |
Длительность выходного видео в секундах. |
usage.duration |
integer |
Итоговая длительность видео для биллинга. |
usage.SR |
integer |
Уровень разрешения результата, например 720 или 1080. |
usage.ratio |
string |
Соотношение сторон результата. |
usage.video_count |
integer |
Количество выходных видео. Сейчас фиксировано 1. |
request_id |
string |
Уникальный идентификатор запроса. |
Пример curl
curl https://api.cdnvideo.ru/app/aihub-router/v1/media/happyhorse/v1/tasks/0385dc79-5ff8-4d82-bcb6-xxxxxx \
-H "Authorization: Bearer ${AIHUB_API_KEY}" \
-H "Content-Type: application/json" \
-H "X-Model: happyhorse-1.0"
Ответ завершённой задачи
{
"request_id": "99243b47-ec5f-9413-9993-xxxxxx",
"output": {
"task_id": "4673458e-28be-4a05-bf2a-xxxxxx",
"task_status": "SUCCEEDED",
"submit_time": "2026-04-20 17:55:17.075",
"scheduled_time": "2026-04-20 17:55:17.129",
"end_time": "2026-04-20 17:56:36.658",
"orig_prompt": "A miniature city built of cardboard and bottle caps comes to life at night. A cardboard train moves slowly through it, dotted with small lights that illuminate the way.",
"video_url": "https://example.com/result.mp4?Expires=xxx"
},
"usage": {
"duration": 5,
"input_video_duration": 0,
"output_video_duration": 5,
"video_count": 1,
"SR": 720,
"ratio": "16:9"
}
}
Статусы задачи
| Статус | Описание |
|---|---|
PENDING |
Задача ожидает обработки. |
RUNNING |
Задача выполняется. |
SUCCEEDED |
Задача успешно завершена. |
FAILED |
Задача завершилась ошибкой. Подробности возвращаются в output.code и output.message. |
CANCELED |
Задача отменена. |
UNKNOWN |
Неизвестный статус. |
Типовой сценарий
- Создайте задачу через
POST /happyhorse/v1/video-synthesis. - Сохраните
output.task_idиз ответа. - Опрашивайте
GET /happyhorse/v1/tasks/{taskId}до статусаSUCCEEDED. - Скачайте видео по
output.video_urlв течение24часов.
Ограничения
- Для
happyhorse-1.0указывайтеX-Model: happyhorse-1.0. - Видео URL хранится
24часа после генерации. - Статус задачи можно запрашивать в течение
24часов. - Результат возвращается в MP4 с H.264 и частотой
24fps. parameters.durationпринимает целые значения от3до15секунд.- Для video editing длительность результата составляет от
3до15секунд. - Для video editing входное видео длиннее
15секунд автоматически обрезается до первых15секунд. - Водяной знак по умолчанию включён и содержит текст
Happy Horse.