Перейти к основному содержанию
В этой статье описывается способ интеграции 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 наследуются от исходного видео, передача duration или ratio не изменит их; формат кадра видео, созданного по изображению, также наследуется от исходного изображения. Стоимость редактирования рассчитывается по суммарной длительности входного и выходного видео. При использовании 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: внутренняя ошибка сервера или сбой генерации.