Skip to main content
У цій статті описано спосіб інтеграції HappyHorse Videos API. Цей інтерфейс через уніфіковану точку входу /happyhorse/videos і параметр action підтримує генерацію відео з тексту, генерацію відео із зображення першого кадру, генерацію відео з референсних зображень і редагування відео.

Процес подання заявки

Щоб використовувати HappyHorse Videos API, спочатку перейдіть до консолі Ace Data Cloud, щоб отримати ваш API Token і зберегти його про запас. Якщо ви ще не увійшли або не зареєструвалися, вас буде автоматично перенаправлено на сторінку входу із запрошенням зареєструватися та увійти, після завершення ви автоматично повернетеся на поточну сторінку. Один 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: внутрішня помилка сервера або помилка генерації.