> ## 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, сначала получите ваш API Token в [консоли Ace Data Cloud](https://platform.acedata.cloud/console/applications) и сохраните его для дальнейшего использования.

![](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.