Skip to main content
В этой статье описан способ интеграции HappyHorse Videos API. Этот интерфейс поддерживает генерацию видео по тексту, генерацию видео по изображению первого кадра, генерацию видео по референсному изображению и редактирование видео через единый вход /happyhorse/videos и параметр action.

Процесс получения

Чтобы использовать HappyHorse Videos API, сначала получите ваш API Token в консоли Ace Data Cloud и сохраните его для дальнейшего использования. Если вы ещё не вошли в систему или не зарегистрировались, вы будете автоматически перенаправлены на страницу входа, где вам будет предложено зарегистрироваться и войти в систему, после завершения вы автоматически вернётесь на текущую страницу. Один API Token позволяет вызывать все сервисы платформы, нет необходимости подавать отдельную заявку для каждого сервиса. При первом получении предоставляется бесплатная квота для бесплатного ознакомления; при недостаточной квоте можно пополнить общий баланс в консоли.
📘 Полная документация: HappyHorse Videos API →

Типы операций

action определяет режим генерации для данного запроса:
  • generate: генерация видео по тексту, action по умолчанию, поддерживает happyhorse-1.0-t2v и happyhorse-1.1-t2v, необходимо передать prompt.
  • image_to_video: генерация видео по изображению первого кадра, поддерживает happyhorse-1.0-i2v и happyhorse-1.1-i2v, необходимо передать image_url.
  • reference_to_video: генерация видео по референсному изображению, поддерживает happyhorse-1.0-r2v и happyhorse-1.1-r2v, необходимо передать prompt и 1–9 изображений image_urls.
  • video_edit: редактирование видео, поддерживает happyhorse-1.0-video-edit, необходимо передать prompt и video_url, дополнительно можно передать 0–5 референсных изображений image_urls.
Для всех действий по умолчанию используется модель 1.1; для video_edit в настоящее время доступна только happyhorse-1.0-video-edit.

Базовое использование

Для генерации видео по тексту достаточно предоставить prompt, также можно указать такие параметры, как resolution, ratio, duration:
Пример возвращаемого результата:
Описание полей:
  • success: успешно ли выполнен данный запрос.
  • task_id: ID задачи на стороне Ace Data Cloud, может использоваться для запроса статуса задачи.
  • trace_id: ID отслеживания данного запроса, используется для диагностики проблем.
  • data: список результатов видео.
    • id: ID задачи на стороне HappyHorse.
    • video_url: адрес CDN-ссылки на сгенерированное видео.
    • state: статус задачи, возможные значения: pending / succeeded / error.
    • duration: оплачиваемая длительность видео в секундах; для video_edit это суммарная длительность входного и выходного видео.
    • resolution: выходное разрешение.
    • ratio: соотношение сторон выходного видео.
Соответствующий код CURL выглядит следующим образом:
Соответствующий код Python выглядит следующим образом:

Генерация видео по изображению первого кадра

При использовании image_to_video параметр image_url будет использоваться как первый кадр видео. Соотношение сторон выходного видео будет по возможности соответствовать изображению первого кадра, поэтому для этого действия не нужно передавать ratio.

Генерация видео по референсному изображению

При использовании reference_to_video в image_urls можно передать 1–9 референсных изображений. В промпте можно ссылаться на изображения в соответствующем порядке, используя character1, character2 и другие обозначения.

Редактирование видео

При использовании video_edit необходимо передать редактируемое видео video_url и намерение редактирования prompt. Необязательный параметр image_urls будет использоваться в качестве референсных изображений, например для смены одежды, переноса стиля или локальной замены. audio_setting может принимать значения auto или origin, где origin означает сохранение аудио исходного видео.

Асинхронный обратный вызов

Генерация видео требует определённого времени обработки. Если вы не хотите поддерживать длительное соединение в ожидании, можно передать callback_url, в этом случае API немедленно вернёт task_id, а после завершения задачи отправит окончательный результат методом POST по этому адресу:
Немедленно возвращаемый результат выглядит следующим образом:
Если требуется только опрос без обратного вызова, также можно передать "async": true, а затем запросить результат задачи через HappyHorse Tasks API.

Описание тарификации

HappyHorse тарифицируется по количеству секунд выходного видео и разрешению:
  • 720P: от примерно $0.105 / секунда.
  • 1080P: от примерно $0.18 / секунда.
  • video_edit: тарифицируется по суммарной длительности входного и выходного видео; фактическая тарифицируемая длительность определяется статистикой после завершения задачи.
Неудачные задачи не тарифицируются и не занимают бесплатную квоту.

Обработка ошибок

Когда при запросе возникает проблема, API возвращает соответствующий код ошибки и описание; распространённые варианты:
  • 400: неверные параметры запроса, например action и model не совпадают, отсутствует prompt / image_url / video_url или duration выходит за пределы диапазона 3–15 секунд.
  • 401: ошибка аутентификации, token недействителен или не соответствует API.
  • 403: недостаточно средств либо запрос был отклонён из-за проверки содержимого подсказки.
  • 429: слишком частые запросы, сработало ограничение частоты; повторите попытку позже.
  • 500: внутренняя ошибка сервера или ошибка генерации.