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

# Генерация видео HappyHorse (Alibaba Cloud)

> Полное руководство по серии генерации видео HappyHorse-1.1 от Alibaba Cloud: Text-to-Video / Image-to-Video / Reference-to-Video (до 9 референсных изображений) / Video Edit, единый асинхронный эндпоинт DashScope, высокоточное сохранение субъекта.

## Обзор

**HappyHorse (快马)** — это серия моделей генерации видео Alibaba, ориентированная на **высокоточное динамическое создание видео** — она точно понимает семантику текста и выдает плавные, естественные, детализированные, высококачественные видео, в которых объекты остаются стабильными. APIYI подключается напрямую через **канал passthrough DashScope**, поэтому один APIYI Key позволяет вызывать все возможности HappyHorse. Текущая флагманская версия, **HappyHorse-1.1** (Video Edit по-прежнему 1.0), охватывает четыре основных сценария использования:

| Сценарий использования   | ID модели                   | Ваш ввод                                          | Вывод                                                              |
| ------------------------ | --------------------------- | ------------------------------------------------- | ------------------------------------------------------------------ |
| **Текст в видео**        | `happyhorse-1.1-t2v`        | Текстовый prompt                                  | Короткое видео                                                     |
| **Изображение в видео**  | `happyhorse-1.1-i2v`        | Изображение первого кадра + prompt                | Оживляет статичное изображение (**без поддержки на основе аудио**) |
| **Референс в видео**     | `happyhorse-1.1-r2v`        | До 9 референсных изображений + prompt             | Видео с высоким уровнем сохранения объекта и сцены                 |
| **Редактирование видео** | `happyhorse-1.0-video-edit` | Видео + до 5 референсных изображений + инструкция | Локально/глобально отредактированное видео                         |

<Note>
  **🐎 Ключевая особенность**: Все четыре возможности используют один и тот же асинхронный эндпоинт и одну и ту же структуру запроса — **при смене сценария использования изменяется только поле `model`**. HappyHorse ориентирован на «высокоточное динамическое видео»; Референс в видео поддерживает **до 9 референсных изображений**, а Редактирование видео поддерживает **до 5 референсных изображений**, обеспечивая высокую согласованность объекта. Он использует тот же эндпоинт, что и [серия Wan](/ru/api-capabilities/wan/overview), и является полностью взаимозаменяемым.
</Note>

<CardGroup cols={2}>
  <Card title="API Text-to-Video" icon="wand-sparkles" href="/ru/api-capabilities/happyhorse/text-to-video">
    `happyhorse-1.1-t2v`, генерирует видео из чистого text prompt.
  </Card>

  <Card title="API Image-to-Video" icon="image" href="/ru/api-capabilities/happyhorse/image-to-video">
    `happyhorse-1.1-i2v`, генерирует видео из изображения первого кадра (без поддержки на основе аудио).
  </Card>

  <Card title="API Reference-to-Video" icon="users" href="/ru/api-capabilities/happyhorse/reference-to-video">
    `happyhorse-1.1-r2v`, до 9 референсных изображений для сохранения объекта.
  </Card>

  <Card title="API Video Edit" icon="scissors" href="/ru/api-capabilities/happyhorse/video-edit">
    `happyhorse-1.0-video-edit`, редактирует видео с помощью до 5 референсных изображений.
  </Card>
</CardGroup>

## Почему стоит выбрать APIYI для HappyHorse

<CardGroup cols={2}>
  <Card title="Один ключ для всех возможностей" icon="key">
    Не нужна регистрация в Alibaba Cloud и настройка региона. Один ключ APIYI вызывает все четыре возможности HappyHorse, а также [серия Wan](/ru/api-capabilities/wan/overview).
  </Card>

  <Card title="Прямой доступ, VPN не нужен" icon="globe">
    Подключайтесь напрямую к `api.apiyi.com`, доступно из отечественных дата-центров и домашнего широкополосного интернета.
  </Card>

  <Card title="Без тарификации при сбое" icon="circle-check">
    Задачи, которые переходят в состояние `failed` (недоступный media URL, sensitive prompt и т. д.), **не тарифицируются**, поэтому вы можете спокойно повторить попытку.
  </Card>

  <Card title="Проксирование протокола DashScope" icon="plug">
    Использует тот же endpoint и схему, что и серия Wan; существующий код Wan может вызывать HappyHorse, просто изменив имя `model`.
  </Card>
</CardGroup>

## Основные возможности

<CardGroup cols={2}>
  <Card title="Асинхронный эндпоинт 4-в-1" icon="list-check">
    t2v / i2v / r2v / video-edit используют `POST /wan/api/v1/...video-synthesis`; после отправки он возвращает `task_id`, затем вы выполняете опрос и скачиваете.
  </Card>

  <Card title="Высокоточное сохранение субъекта" icon="target">
    Модель тяготеет к стилю «high-fidelity dynamic video», сохраняя людей/объекты более стабильными на протяжении движения.
  </Card>

  <Card title="До 9 референсных изображений" icon="images">
    `happyhorse-1.1-r2v` официально поддерживает до 9 `reference_image` записей, обеспечивая более высокую согласованность субъекта в сценариях с несколькими референсами.
  </Card>

  <Card title="Несколько разрешений и длительностей" icon="expand">
    Разрешения 720P / 1080P, целочисленные длительности от 2 до 15 секунд и `prompt_extend` интеллектуальное переписывание для улучшения качества коротких prompt.
  </Card>
</CardGroup>

## Поддерживаемые модели

| ID модели                   | Возможность          | Требуемый медиа-ввод               | Примечания                                   |
| --------------------------- | -------------------- | ---------------------------------- | -------------------------------------------- |
| `happyhorse-1.1-t2v`        | Текст в видео        | Нет                                | Генерация только из текста                   |
| `happyhorse-1.1-i2v`        | Изображение в видео  | `first_frame`                      | **Не поддерживает** `driving_audio`          |
| `happyhorse-1.1-r2v`        | Референс в видео     | `reference_image` (до 9)           | Сохранение субъекта по нескольким референсам |
| `happyhorse-1.0-video-edit` | Редактирование видео | `video` + `reference_image` (до 5) | Имя модели **содержит дефис**                |

## ⚠️ Выбор эндпоинта (Самое важное)

APIYI одновременно монтирует два пути, и **только эндпоинт DashScope passthrough полностью пригоден для всех возможностей HappyHorse**:

| Path                                                         | Стиль протокола                | Доступность i2v / r2v      | Вывод                       |
| ------------------------------------------------------------ | ------------------------------ | -------------------------- | --------------------------- |
| `/v1/videos`                                                 | Плоский стиль OpenAI           | ❌ Поля media отбрасываются | **Не используйте**          |
| `/wan/api/v1/services/aigc/video-generation/video-synthesis` | Нативный passthrough DashScope | ✅ Полностью пригоден       | **Всегда используйте этот** |

<Warning>
  HappyHorse и Wan используют один и тот же endpoint passthrough. Если вы видите в какой-либо документации/примере отправку задачи на видео через `/v1/videos`, **игнорируйте это**. Все запросы на создание проходят через `/wan/api/v1/...video-synthesis`, а все запросы на получение статуса — через `/v1/tasks/{task_id}`.
</Warning>

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

Весь поток асинхронный и состоит из трех шагов: **создать задачу → опросить статус → скачать видео**.

<Steps>
  <Step title="Создать задачу">
    `POST /wan/api/v1/services/aigc/video-generation/video-synthesis`, с заголовком запроса `X-DashScope-Async: enable`. Он сразу возвращает `task_id`.
  </Step>

  <Step title="Опросить статус">
    `GET /v1/tasks/{task_id}` (с `Authorization`), выполняя запрос каждые 5–10 секунд (**не реже чем раз в 3 секунды**), пока `status` не станет `completed`.
  </Step>

  <Step title="Скачать видео">
    Выполните GET для mp4 напрямую по `result_url` в ответе, **без заголовка `Authorization`** (это подписанная прямая ссылка OSS; если включить Auth, будет 403).
  </Step>
</Steps>

### Справка по статусам задачи

| Статус        | Значение              | Следующий шаг                                                                                                                  |
| ------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `submitted`   | Отправлено, в очереди | Продолжайте опрос                                                                                                              |
| `in_progress` | Генерация             | Продолжайте опрос (прогресс часто замирает на 30% — это грубая гранулярность отчета на стороне upstream, а не зависшая задача) |
| `completed`   | Успешно               | Скачайте из `result_url`                                                                                                       |
| `failed`      | Ошибка                | Проверьте `error.message` / `fail_reason`                                                                                      |

### Полный Python Client

```python theme={null}
import json, time, urllib.request

BASE = "https://api.apiyi.com"
KEY  = "sk-your-api-key"   # Your APIYI Key

def post(path, body):
    h = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json",
         "X-DashScope-Async": "enable"}
    req = urllib.request.Request(BASE + path, data=json.dumps(body).encode(), headers=h, method="POST")
    return json.loads(urllib.request.urlopen(req).read())

def get(path):
    req = urllib.request.Request(BASE + path, headers={"Authorization": f"Bearer {KEY}"})
    return json.loads(urllib.request.urlopen(req).read())

# 1. Create task (switching use cases only changes model and media)
r = post("/wan/api/v1/services/aigc/video-generation/video-synthesis", {
    "model": "happyhorse-1.1-t2v",
    "input": {"prompt": "A cat running across a meadow, bright sunshine, camera following"},
    "parameters": {"resolution": "720P", "duration": 5, "prompt_extend": True, "watermark": True}
})
task_id = r["output"]["task_id"]
print("task_id:", task_id)

# 2. Poll (every 5-10 seconds)
while True:
    info = get(f"/v1/tasks/{task_id}")
    status = info["status"]
    print("status:", status, "progress:", info.get("progress"))
    if status == "completed":
        url = info["result_url"]
        break
    if status == "failed":
        raise RuntimeError(info.get("error") or info.get("fail_reason"))
    time.sleep(10)

# 3. Download (do NOT include Authorization! result_url is a signed OSS direct link)
urllib.request.urlretrieve(url, "out.mp4")
print("saved out.mp4")
```

## Ключевые параметры: пояснение

При отправке тело использует вложенную структуру DashScope: `{ model, input: { prompt, media[] }, parameters: {...} }`.

### Типы `media[]`

| `type`            | Назначение                                                  | Применимые модели |
| ----------------- | ----------------------------------------------------------- | ----------------- |
| `first_frame`     | Изображение первого кадра (≤1)                              | i2v, r2v          |
| `reference_image` | Референсное изображение (до 9 для r2v, до 5 для video-edit) | r2v, video-edit   |
| `video`           | Входное видео                                               | video-edit        |

<Warning>
  i2v в HappyHorse **не поддерживает `driving_audio`** (audio-driven — это возможность, доступная только в [Wan2.7-i2v](/ru/api-capabilities/wan/image-to-video)). Для lip-sync / rap используйте Wan2.7.
</Warning>

### Поля `parameters`

| Поле            | Тип    | Значения         | Примечания                                                  |
| --------------- | ------ | ---------------- | ----------------------------------------------------------- |
| `resolution`    | string | `720P` / `1080P` | Рекомендуется указывать в верхнем регистре, явное задание   |
| `duration`      | int    | 2–15             | Секунды (целое число), обычно 5 / 10                        |
| `prompt_extend` | bool   | `true` / `false` | Умное переписывание prompt, **крайне рекомендуется `true`** |
| `watermark`     | bool   | `true` / `false` | Водяной знак "AI Generated" в правом нижнем углу            |
| `seed`          | int    | 0–2147483647     | Его фиксация повышает воспроизводимость                     |

<Tip>
  `duration` должен быть **целым числом** `5`, а не строкой `"5"`; запись `resolution` в **верхнем регистре** `720P` более надежна.
</Tip>

## Как выбрать HappyHorse или Wan

HappyHorse и [Wan](/ru/api-capabilities/wan/overview) — это обе видеомодели Alibaba, которые используют один и тот же эндпоинт и схему (их можно взаимозаменять, просто меняя имя `model`), но они делают акцент на разных вещах:

| Параметр                             | HappyHorse-1.1                                            | Wan2.7                                                       |
| ------------------------------------ | --------------------------------------------------------- | ------------------------------------------------------------ |
| Синхронизация губ под аудио (i2v)    | ❌ Не поддерживается, i2v работает только по первому кадру | ✅ `wan2.7-i2v` поддерживает `driving_audio`                  |
| Лимит Reference-to-Video             | До 9 изображений-референсов                               | Изображения-референсы + видео-референсы вместе ≤5            |
| Изображения-референсы для Video Edit | ≤5                                                        | ≤5                                                           |
| Акцент стиля                         | Высокоточное динамичное видео, стабильные субъекты        | Взаимодействие нескольких субъектов, reference тембра голоса |

<Tip>
  **Нужно несколько изображений-референсов, чтобы сохранить согласованность субъекта** → выберите `happyhorse-1.1-r2v` (до 9).
  **Нужны lip-sync / рэп / озвучка digital-human** → выберите [Wan2.7-i2v](/ru/api-capabilities/wan/image-to-video) (единственный, который поддерживает управление по аудио).
</Tip>

## Лучшие практики

<Steps>
  <Step title="Сначала итеративно работайте на 720P / 5 секунд">
    Во время разработки используйте короткие видео с низким разрешением, чтобы быстро проверять prompt и reference images, а затем повышайте разрешение и длительность после завершения настройки.
  </Step>

  <Step title="Всегда включайте prompt_extend">
    `prompt_extend: true` заметно повышает качество коротких prompt.
  </Step>

  <Step title="Проверяйте каждые 5–10 секунд">
    Не опускайтесь ниже 3 секунд (иначе вас ограничат по лимиту запросов). Каждая возможность HappyHorse на 720P / 5 секунд обычно занимает 105–115 секунд.
  </Step>

  <Step title="Установите клиентский тайм-аут 20 минут в качестве страховки">
    1080P или длинные видео значительно медленнее; установите запасной тайм-аут 20 минут для цикла опроса.
  </Step>

  <Step title="Скачивайте сразу после получения result_url">
    `result_url` **истекает через 24 часа** по умолчанию, и это подписанная прямая ссылка OSS — не включайте заголовок Authorization при скачивании.
  </Step>
</Steps>

## Коды ошибок и повторные попытки

| Источник                                                 | Характеристики                                                                                                                               | Обработка                                                                                             |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Этап создания (отклонён APIYI)**                       | HTTP 4xx/5xx, с `type` для `task_error` / `parse_request_failed` / `build_request_failed`                                                    | Исправьте тело запроса и повторите попытку (неверный тип поля, отсутствует media, неверный эндпоинт)  |
| **Этап выполнения (отклонён вышестоящим Alibaba Cloud)** | Задача `status=failed`, с `error.message`, перед которым стоит код в квадратных скобках, например `[InvalidParameter]` / `[InvalidImageUrl]` | Прочитайте подсказку в квадратных скобках; обычно это недоступный media URL или чувствительный prompt |

<Info>
  **Рекомендуемое поведение клиента**: используйте повторные попытки с экспоненциальной задержкой для HTTP 5xx / ошибок сети; сразу показывайте HTTP 4xx без повторной попытки; задачу `failed` с `[InvalidImageUrl]` можно повторить, тогда как сбои `[InvalidParameter]` / по чувствительным словам — нет.
</Info>

## Вопросы и ответы

<AccordionGroup>
  <Accordion title="Есть ли разница в том, как HappyHorse и Wan интегрированы?">
    **Нет.** Они используют один и тот же passthrough-эндпоинт DashScope, одну и ту же структуру запроса, один и тот же набор названий типов медиа и один и тот же query-эндпоинт. **При переключении изменяется только поле `model`** (например, `wan2.7-t2v` → `happyhorse-1.1-t2v`); остальная часть тела остается идентичной.
  </Accordion>

  <Accordion title="Почему i2v у HappyHorse не поддерживает синхронизацию губ?">
    `happyhorse-1.1-i2v` не поддерживает поле `driving_audio` (audio-driven); i2v принимает только `first_frame`. Для синхронизации губ / рэпа / озвучки цифрового человека используйте [Wan2.7-i2v](/ru/api-capabilities/wan/image-to-video).
  </Accordion>

  <Accordion title="Может ли happyhorse-1.1-r2v действительно принимать 9 референсных изображений?">
    Да. Официально поддерживается до 9 `reference_image` записей — просто поместите их в массив `media`. Чем больше референсных изображений, тем выше согласованность для объекта / одежды / сцены.
  </Accordion>

  <Accordion title="Почему я не могу отправить через /v1/videos?">
    `/v1/videos` имеет неполную поддержку поля `media` в i2v / r2v, из-за чего upstream возвращает `[InvalidParameter] Field required: input.media`. **Все запросы на создание проходят через `/wan/api/v1/services/aigc/video-generation/video-synthesis`**, а запросы на получение — через `/v1/tasks/{task_id}`.
  </Accordion>

  <Accordion title="Что делать, если при загрузке result_url возвращается 403?">
    Уберите заголовок `Authorization`. `result_url` уже является подписанной прямой ссылкой OSS; если добавить ваш APIYI Key, OSS вместо этого отклонит ее. `result_url` по умолчанию истекает через 24 часа, поэтому загрузите его как можно скорее.
  </Accordion>

  <Accordion title="Тарифицируются ли неудачные задачи?">
    `status=failed` не тарифицируется. Но повторная отправка той же задачи тарифицируется снова, поэтому учитывайте идемпотентность.
  </Accordion>
</AccordionGroup>

## Настройка группы

Серии HappyHorse и [Wan](/ru/api-capabilities/wan/overview) **используют одну общую `Wan&HappyHorse` группу** — один Token может вызывать обе серии. Для видеомоделей тарификация идет **за секунду**, поэтому Token должен соответствовать двум условиям, чтобы маршрутизация прошла успешно:

1. **Модель тарификации**: выберите **Pay-as-you-go Priority** или **Pay-as-you-go** — видео тарифицируется за секунду, поэтому **Token с оплатой за запрос не может быть маршрутизирован**
2. **Группа**: выберите группу, которая включает `Wan&HappyHorse`

<Frame caption="Create Token: set billing model to Pay-as-you-go Priority and group to Wan&HappyHorse (0.14x) to call every Wan2.7 and HappyHorse video model (the screenshot shows the group's former name Wan, since renamed to Wan&HappyHorse)">
  <img src="https://mintcdn.com/apiyillc/5-SttsT0c5VQwgVz/images/wan-token-group-setup-20260523.png?fit=max&auto=format&n=5-SttsT0c5VQwgVz&q=85&s=f46887cb88777eb34d70837983f1fc49" alt="Диалог создания Token: модель тарификации установлена на Pay-as-you-go Priority, в выпадающем списке группы показан Wan&HappyHorse (коэффициент тарифа 0.14x), один Token можно использовать и для Wan2.7, и для HappyHorse" width="1286" height="988" data-path="images/wan-token-group-setup-20260523.png" />
</Frame>

## Тарифы

### Базовая цена = 98％ от официальной цены Alibaba (легко понять)

**Цены моделей HappyHorse встроены в систему APIYI** — ручная настройка не нужна; групповая скидка применяется автоматически. В консоли группа `Wan&HappyHorse` показывает коэффициент тарифа **0.14x**, который выражается во встроенной единице тарификации **RMB**. Поскольку APIYI выставляет счета в **USD** по фиксированному курсу 1:7, фактический пересчет выглядит так:

```
0.14 (RMB pricing unit) × 7 (fixed exchange rate) = 0.98
```

Иными словами, **базовая цена = 98% от официальной цены Alibaba** — дешевле, чем покупать напрямую у Alibaba, и без необходимости самостоятельно настраивать зарубежный канал.

> Пересчет: **цена в USD за секунду = официальная цена в RMB × 0.14** (то есть `× 0.98 ÷ 7`).

### Подробности цены (базовая цена, тарификация по секундам)

HappyHorse-1.1 text-to-video / image-to-video / reference-to-video стоят одинаково, с двумя уровнями — `720P` / `1080P` (480P не поддерживается):

| Разрешение | Официальная цена | Наша базовая /с | 5 с    | 10 с   | 12 с   |
| ---------- | ---------------- | --------------- | ------ | ------ | ------ |
| `720P`     | ¥0.9/s           | \$0.126/s       | \$0.63 | \$1.26 | \$1.51 |
| `1080P`    | ¥1.6/s           | \$0.224/s       | \$1.12 | \$2.24 | \$2.69 |

<Info>
  * Длительность выходного видео в `happyhorse-1.0-video-edit` соответствует исходному видео и тарифицируется по фактическим секундам выхода, а не по `duration`.
  * Указанные цены — это **базовые (98% от официальной)**; при максимальном бонусе за пополнение эффективная цена составляет примерно значение из таблицы **÷ 1.2** (например, 1080P 5 с \$1.12 → примерно \$0.93).
</Info>

### Накопительные бонусы за пополнение для еще более низкой эффективной цены

После подключения к [программе бонусов за пополнение](/ru/faq/recharge-promotions) зачисленный баланс можно увеличить примерно до 1.2x, что еще сильнее снижает эффективную цену:

```
0.98 ÷ 1.2 ≈ 0.816
```

Так крупные клиенты могут опустить цену примерно до **\~81% от официальной цены** (0.98 ÷ 1.2 ≈ 0.816).

| Уровень                                                              | Эффективная цена (по сравнению с официальной ценой Alibaba) | Формула                                         |
| -------------------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------- |
| Базовый                                                              | **98%**                                                     | коэффициент 0.14x × фиксированный курс обмена 7 |
| С бонусами за пополнение (максимальный уровень для крупных клиентов) | **\~81.6%**                                                 | 0.98 ÷ 1.2                                      |

<Info>
  * Единица тарификации = **уровень разрешения × длительность (секунды)**; неудачные задания не тарифицируются.
  * 1:7 — это **фиксированный курс взаиморасчетов** (не льготный курс); он одинаково применяется ко всем пополнениям в USD.
  * Сведения о самых высоких уровнях бонусов и подходящих каналах см. в [бонусах за пополнение](/ru/faq/recharge-promotions). Актуальный курс указан в [консоли](https://api.apiyi.com/token).
</Info>

## Связанная документация

<CardGroup cols={2}>
  <Card title="Тестовая среда Text-to-Video" icon="wand-sparkles" href="/ru/api-capabilities/happyhorse/text-to-video">
    `happyhorse-1.1-t2v` онлайн-отладка
  </Card>

  <Card title="Тестовая среда Image-to-Video" icon="image" href="/ru/api-capabilities/happyhorse/image-to-video">
    `happyhorse-1.1-i2v` генерация первого кадра
  </Card>

  <Card title="Тестовая среда Reference-to-Video" icon="users" href="/ru/api-capabilities/happyhorse/reference-to-video">
    `happyhorse-1.1-r2v` до 9 референсных изображений
  </Card>

  <Card title="Тестовая среда Video Edit" icon="scissors" href="/ru/api-capabilities/happyhorse/video-edit">
    `happyhorse-1.0-video-edit` замена одежды / замена фона
  </Card>

  <Card title="Серия Wan" icon="video" href="/ru/api-capabilities/wan/overview">
    Также сравнение выбора модели Alibaba
  </Card>
</CardGroup>

<Info>
  Серия HappyHorse предоставляется через канал passthrough APIYI DashScope. По вопросам или предложениям, пожалуйста, создайте обращение в [консоли APIYI](https://api.apiyi.com).
</Info>