> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Інструкція з інтеграції HappyHorse Videos API

> HappyHorse Video API guide - Ace Data Cloud

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

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

Щоб використовувати HappyHorse Videos API, спочатку перейдіть до [консолі Ace Data Cloud](https://platform.acedata.cloud/console/applications), щоб отримати ваш API Token і зберегти його про запас.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

Якщо ви ще не увійшли або не зареєструвалися, вас буде автоматично перенаправлено на сторінку входу із запрошенням зареєструватися та увійти, після завершення ви автоматично повернетеся на поточну сторінку.

**Один API Token дає змогу викликати всі сервіси платформи, не потрібно подавати окрему заявку для кожного сервісу.** Під час першого подання заявки надаються безкоштовні кредити для безкоштовного ознайомлення; коли кредитів недостатньо, ви можете поповнити загальний баланс у [консолі](https://platform.acedata.cloud/console/coin).

> 📘 Повна документація: [HappyHorse Videos API →](https://platform.acedata.cloud/documents/happyhorse-videos)

## Типи операцій

`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` тощо:

```json theme={null}
{
  "action": "generate",
  "model": "happyhorse-1.1-t2v",
  "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 5
}
```

Приклад результату, що повертається:

```json theme={null}
{
  "success": true,
  "task_id": "27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1",
  "trace_id": "6071ab5e-2f37-46f0-9e07-f1e378112e69",
  "data": [
    {
      "id": "9650580f-6d9e-4bc1-823a-29011790c5cb",
      "video_url": "https://cdn.acedata.cloud/assets/examples/happyhorse/27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1-2c108ce23554.mp4",
      "state": "succeeded",
      "duration": 5,
      "resolution": "720P",
      "ratio": null
    }
  ]
}
```

Опис полів:

* `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-код наведено нижче:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/happyhorse/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "happyhorse-1.1-t2v",
  "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 5
}'
```

Відповідний Python-код наведено нижче:

```python theme={null}
import requests

url = "https://api.acedata.cloud/happyhorse/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json",
}

payload = {
    "action": "generate",
    "model": "happyhorse-1.1-t2v",
    "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
    "resolution": "720P",
    "ratio": "16:9",
    "duration": 5,
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

## Генерація відео із зображення першого кадру

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

```json theme={null}
{
  "action": "image_to_video",
  "model": "happyhorse-1.1-i2v",
  "image_url": "https://cdn.acedata.cloud/b1c82e4937.png",
  "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
  "resolution": "1080P",
  "duration": 5
}
```

## Генерація відео з референсних зображень

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

```json theme={null}
{
  "action": "reference_to_video",
  "model": "happyhorse-1.1-r2v",
  "prompt": "character1 walks forward through a sunrise meadow with the warm leather and gold trim style from character2",
  "image_urls": [
    "https://cdn.acedata.cloud/b1c82e4937.png",
    "https://cdn.acedata.cloud/eb75d88a3f.png"
  ],
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 5
}
```

## Редагування відео

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

```json theme={null}
{
  "action": "video_edit",
  "model": "happyhorse-1.0-video-edit",
  "prompt": "Apply the warm leather and gold trim style from the reference image while preserving the original camera motion",
  "video_url": "https://cdn.acedata.cloud/assets/examples/happyhorse/27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1-2c108ce23554.mp4",
  "image_urls": [
    "https://cdn.acedata.cloud/eb75d88a3f.png"
  ],
  "resolution": "720P",
  "audio_setting": "auto"
}
```

## Асинхронний зворотний виклик

Генерація відео потребує певного часу на обробку. Якщо ви не хочете підтримувати довге з’єднання в очікуванні, можна передати `callback_url`, у такому разі API негайно поверне `task_id`, а після завершення завдання надішле фінальний результат методом POST на цю адресу:

```json theme={null}
{
  "action": "generate",
  "prompt": "A horse running through a snowy forest",
  "duration": 5,
  "callback_url": "https://your-domain.com/callback/happyhorse"
}
```

Результат, що повертається негайно, виглядає так:

```json theme={null}
{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}
```

Якщо потрібне лише опитування без зворотного виклику, також можна передати `"async": true`, а потім через [HappyHorse Tasks API](https://platform.acedata.cloud/documents/happyhorse-tasks) отримати результат завдання.

## Опис тарифікації

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`: внутрішня помилка сервера або помилка генерації.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.