Перейти до основного вмісту
У цій статті описано спосіб інтеграції 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 успадковуються від вихідного відео, передача 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: внутрішня помилка сервера або помилка генерації.