Перейти к содержанию

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 Неизвестный статус.

Типовой сценарий

  1. Создайте задачу через POST /happyhorse/v1/video-synthesis.
  2. Сохраните output.task_id из ответа.
  3. Опрашивайте GET /happyhorse/v1/tasks/{taskId} до статуса SUCCEEDED.
  4. Скачайте видео по 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.