> ## 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.

# Генерация видео MiniMax-H3

> Руководство по генерации видео с помощью MiniMax H3 (Hailuo 3.0): единый эндпоинт для видео по тексту, первому/последнему кадру и референсным изображениям/видео/аудио, нативное стереоаудио, 768P, 4–15 с, тарификация: $0.03 за секунду.

## Обзор

MiniMax H3 (Hailuo 3.0) — это омнимодальная видеомодель, выпущенная MiniMax 2026-07-31 (UTC+8). Одна модель принимает текст, изображения, видео и аудио и генерирует видео **со стереоаудиодорожкой**. APIYI предоставляет доступ к `MiniMax-H3` на базе собственного развёртывания открытых весов с разрешением 768P, длительностью от 4 до 15 секунд на клип и посекундной тарификацией.

<Note>
  **Особенности**: один эндпоинт охватывает text-to-video, видео по первому кадру / последнему кадру / первому и последнему кадрам, а также генерацию по смешанным референсам с использованием до 9 изображений, 3 видео и 3 аудиоклипов. Каждый клип создаётся с музыкой и звуковыми эффектами. **\$0.03 в секунду** (в официальном API MiniMax — \$0.08), поэтому 10-секундный клип стоит \$0.30, а средства за неудачные задачи возвращаются автоматически.
</Note>

<CardGroup cols={2}>
  <Card title="Справочник по API генерации видео" icon="video" href="/ru/api-capabilities/minimax-h3/video-generation">
    Создание задачи и опрос её статуса по task\_id с примерами для Python / cURL / Node.js и интерактивным Playground
  </Card>

  <Card title="Бонусы при пополнении" icon="gift" href="/ru/faq/recharge-promotions">
    Бонусы при пополнении дополнительно снижают эффективную цену
  </Card>
</CardGroup>

## Поручите интеграцию ИИ-агенту

<Note>
  Если вы ведете разработку с помощью Codex / Claude Code / Cursor, скопируйте приведенный ниже prompt в него. Сначала агент загрузит текстовую версию этой страницы (добавьте `.md` к любому URL документации), а затем напишет код под ваш стек. Распространенные ошибки уже учтены: путь должен содержать `/hailuo`, результаты находятся внутри `task`, а `duration` должно быть целым числом от 4 до 15.
</Note>

<Prompt description="Поручите кодинг-агенту интеграцию или отладку генерации видео MiniMax-H3. Скопируйте и вставьте это в Codex, Claude Code, Cursor и аналогичные инструменты." icon="bot" actions={["copy"]}>
  Интегрируйте или отладьте генерацию видео MiniMax-H3 (text-to-video / видео по первому и последнему кадрам / видео по референсу) в этом проекте.

  Ознакомьтесь с документацией перед написанием кода: загрузите [https://docs.apiyi.com/en/api-capabilities/minimax-h3/overview.md](https://docs.apiyi.com/en/api-capabilities/minimax-h3/overview.md) для получения текстовой версии этой страницы; параметры и примеры кода находятся по адресу [https://docs.apiyi.com/en/api-capabilities/minimax-h3/video-generation.md](https://docs.apiyi.com/en/api-capabilities/minimax-h3/video-generation.md) .

  Требования:

  1. Эндпоинты: отправка с помощью `POST https://api.apiyi.com/hailuo/v2/video_generation`, запрос статуса с помощью `GET https://api.apiyi.com/hailuo/v2/query/video_generation/{task_id}`. **Путь должен начинаться с `/hailuo`**; без этого вы получите веб-страницу вместо JSON.

  2. Опрос и статус: отправка возвращает только `{"task_id": ...}`. Опрашивайте каждые 10 секунд и прекращайте опрос через 15 минут. Результат запроса обернут в объект **`task`**; статус принимает значения `queued` / `running` / `succeeded` / `failed`, а **успешное завершение — `succeeded`**. Значение `progress` может быть только 0 или 1, поэтому не стройте индикатор выполнения на его основе.

  3. Сохранение видео: URL находится в **`task.content.url`** и не требует заголовка авторизации. Скачивайте его на стороне сервера и сохраняйте у себя. Проверяйте URL методом GET; на запросы HEAD возвращается ошибка 403.

  4. Тело запроса и типы данных: обязательны все пять полей `{ model, content[], resolution, duration, ratio }`. Поле `model` всегда имеет значение `MiniMax-H3` (с учетом регистра); **`duration` — целое число**, строки вроде `"5"` или десятичные дроби отклоняются; **`resolution` должно быть в верхнем регистре `768P`**, а значения `768p` и `2K` отклоняются.

  5. Ограничения параметров: `duration` от 4 до 15 секунд; `ratio` — одно из значений `21:9` `16:9` `4:3` `1:1` `3:4` `9:16` `adaptive`; **запросы только с текстом или только с аудио не могут использовать `adaptive`**. Поле `content` должно содержать ровно один текстовый элемент длиной не более 7000 символов. Не добавляйте недокументированные поля (такие как `seed` или `prompt`); они отклоняются.

  6. Входные медиафайлы: изображения передаются в `{"type":"image_url","image_url":{"url":...},"role":...}`, видео используют `video_url` + `reference_video`, аудио использует `audio_url` + `reference_audio`. Каждый URL должен быть **публичной ссылкой https**; Base64, data URI и приватные адреса не поддерживаются. Первый и последний кадры (`first_frame` / `last_frame`) **нельзя** смешивать с референсными медиафайлами, а при передаче более чем одного изображения каждому требуется `role`. Лимиты: 9 референсных изображений, 3 референсных видео (суммарно не более 15 секунд), 3 референсных аудиоклипа. В prompt ссылайтесь на медиафайлы как `<Picture 1>` `<Video 1>` `<Audio 1>` с нумерацией по порядку внутри каждого типа.

  7. Тарификация и идемпотентность: тарифицируется посекундно по 0,03 доллара США, без дополнительной платы за референсные изображения, видео или аудио; средства за задачи со статусом `failed` возвращаются автоматически, а ошибки отправки не тарифицируются. **Заголовок `Idempotency-Key` в настоящее время не действует, поэтому каждая повторная отправка тарифицируется повторно.** Ведите собственное сопоставление между бизнес-ID и task\_id и повторяйте попытки только при ошибках HTTP 500 и сетевых сбоях при отправке, используя задержку (5 с / 10 с / 20 с). При ошибках 400 исправляйте параметры, а не повторяйте запрос.

  8. Token: подходит группа `default` или группа `svip`; установите модель тарификации на **Pay-as-you-go Priority**. Ошибка «no available channel» означает, что группа Token выбрана неверно или имя модели написано с ошибкой.

  9. Считывайте ключ из переменной окружения `APIYI_API_KEY`. Не зашивайте его в код жестко и не коммитьте в git.

  10. По завершении выполните один реальный 5-секундный запрос text-to-video и отправьте мне URL видео и стоимость вызова. Весь процесс занимает от 2 до 4 минут; если вы работаете в песочнице, установите таймаут команды более 600 секунд или запустите ее в фоновом режиме.
</Prompt>

<Accordion title="От чего защищает этот prompt">
  | Требование | Предотвращаемая ошибка |
  | - | - |
  | Путь начинается с `/hailuo` | Обычный `/v2/...` возвращает веб-страницу, парсинг JSON завершается ошибкой, и кажется, что сервис недоступен |
  | Результаты находятся в `task` | Поиск `status` на верхнем уровне никогда не дает совпадений, поэтому опрос продолжается до истечения таймаута |
  | `duration` — целое число 4–15 | Строки или десятичные дроби отклоняются, а сообщение об ошибке обманчиво сообщает о невалидном JSON |
  | Без `adaptive` для запросов только с текстом | Для text-to-video требуется фиксированное соотношение сторон |
  | Ключ идемпотентности не действует | Предполагается, что `Idempotency-Key` делает повторные запросы безопасными, но каждый повторный запрос тарифицируется заново |
  | Проверяйте URL методом GET | URL видео возвращает 403 на запрос HEAD, что выглядит как неработающая ссылка |
</Accordion>

## Почему MiniMax-H3 от APIYI?

<CardGroup cols={2}>
  <Card title="Полный набор возможностей" icon="layers">
    Доступны генерация по тексту, по первому/последнему кадру, а также смешанная референсная генерация по изображениям / видео / аудио с теми же лимитами на референсы, что и у официальной модели (9 изображений + 3 видео + 3 аудиоклипа)
  </Card>

  <Card title="Посекундная тарификация, возврат средств при сбое" icon="receipt">
    \$0.03 в секунду, и вы платите только за успешные видео; за неудачные задачи средства возвращаются в полном объеме, а ошибки отправки бесплатны
  </Card>

  <Card title="Бонусы за пополнение суммируются" icon="gift">
    Сочетайте с [бонусами за пополнение](/ru/faq/recharge-promotions) для снижения фактических затрат
  </Card>

  <Card title="Глобальный доступ без барьеров" icon="globe">
    Подключайтесь напрямую к `api.apiyi.com` с помощью одного API-ключа; зарубежный аккаунт не требуется
  </Card>

  <Card title="Полная линейка видеомоделей" icon="clapperboard">
    Тот же ключ работает и с [Seedance 2.0 / 2.5](/ru/api-capabilities/seedance2/overview), [Wan2.7](/ru/api-capabilities/wan/overview), [VEO 3.1](/ru/api-capabilities/veo-3-1-official/overview) и другими
  </Card>

  <Card title="Профессиональная поддержка" icon="headset">
    Обращайтесь в службу поддержки по вопросам интеграции; корпоративные клиенты получают индивидуальное сопровождение при подключении
  </Card>
</CardGroup>

## Ключевые возможности

<CardGroup cols={2}>
  <Card title="Встроенный стереозвук" icon="music">
    Каждый ролик включает музыку и звуковые эффекты, создаваемые на основе prompt и любого референсного аудио, без отдельного этапа дубляжа
  </Card>

  <Card title="7 соотношений сторон" icon="ratio">
    Шесть фиксированных соотношений от `21:9` до `9:16`, а также `adaptive` для соответствия референсному изображению
  </Card>

  <Card title="Любая целая длительность от 4 до 15 с" icon="timer">
    Тарификация по фактическому количеству запрошенных секунд, поэтому короткие ролики стоят дешевле
  </Card>

  <Card title="Длинные prompt" icon="text">
    До 7000 символов на prompt — достаточно для покадровых описаний
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Управление первым/последним кадром" icon="image">
    Передайте только первый кадр, только последний кадр или оба, чтобы задать начало и завершение ролика
  </Card>

  <Card title="Несколько референсных изображений" icon="images">
    До 9 референсных изображений; отмечайте персонажей и объекты в prompt с помощью `<Picture 1>` и так далее
  </Card>

  <Card title="Перенос движения из видео" icon="film">
    До 3 референсных видео для копирования движений камеры и ритма движения
  </Card>

  <Card title="Видео на основе аудио" icon="audio-lines">
    До 3 референсных аудиоклипов; изображение следует за музыкой или голосом
  </Card>
</CardGroup>

## Тарифы

Этот канал использует открытые веса MiniMax H3 на нашем собственном развертывании. Он **не является релеем официального API MiniMax**, поэтому для него действует собственная тарификация:

| Позиция | APIYI (собственное развертывание, 768P) | Официальный API MiniMax (768P) |
| - | - | - |
| Выходное видео | **\$0.03 / сек** | \$0.08 / сек |
| Референсные изображения | Бесплатно (до 9) | Первые 5 бесплатно, далее \$0.04 за изображение |
| Референсные видео | Бесплатно | \$0.08 за секунду входных данных |
| Референсное аудио | Бесплатно | Бесплатно |
| Пример: 10 с text-to-video | **\$0.30** | \$0.80 |

<Note>Этот канал представляет собой собственное развертывание открытых весов и тарифицируется независимо от официального API MiniMax, а цены могут изменяться; приведенная выше таблица носит справочный характер, а приоритет имеет вкладка **Тарифы моделей** в верхнем меню навигации: [Тарифы моделей](/en/models/index). Официальные цены взяты из `platform.minimax.io/docs/guides/pricing-paygo` (по состоянию на 2026-09-29).</Note>

<Info>
  **Детали тарификации**:

  * Тарифицируется по запрошенному `duration` в секундах, предварительное списание происходит при принятии задачи
  * **Без дополнительной платы за референсные медиа**: референсные изображения (до 9), видео и аудио не меняют стоимость; тарифицируется только длительность
  * За завершившиеся сбоем задачи (ошибка скачивания медиа, неподдерживаемый формат, ошибка выполнения и т. д.) средства **автоматически возвращаются в полном объеме**
  * Запросы, возвращающие ошибки 4xx / 5xx при отправке, не тарифицируются; проверка статуса и скачивание бесплатны
  * Ознакомьтесь с [бонусами за пополнение](/ru/faq/recharge-promotions), чтобы снизить фактические затраты
</Info>

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

MiniMax-H3 **работает в группе `default`**, и группа `svip` также подходит; выделенная группа не требуется. Мы рекомендуем установить модель тарификации Token на **Pay-as-you-go Priority**. Если при вызове возвращается «no available channels for the current group», значит, группа Token не включает эту модель или значение `model` указано с ошибкой (оно чувствительно к регистру).

| Параметр | Требование |
| - | - |
| Группа | `default` или `svip` |
| Модель тарификации | Pay-as-you-go Priority (рекомендуется) |
| Название модели | `MiniMax-H3`, с учётом регистра |

## Технические характеристики

| Параметр | Спецификация |
| - | - |
| ID модели | `MiniMax-H3` |
| Разрешение | Только `768P` |
| Длительность | Целое число 4–15 с (готовый клип обычно на 0,1–0,5 с длиннее) |
| Соотношение сторон | `21:9` 1536×672 / `16:9` 1344×768 / `4:3` 1024×768 / `1:1` 768×768 / `3:4` 768×1024 / `9:16` 768×1344 / `adaptive` |
| Аудио | Стереодорожка включена всегда, переключателя нет |
| Prompt | 1 текстовый элемент, 1–7000 символов |
| Референсные медиафайлы | Изображения ≤ 9, видео ≤ 3 (суммарно ≤ 15 с), аудио ≤ 3; всего ≤ 12 медиафайлов |
| Входные медиаданные | Только публичные HTTPS URL |
| Выходной формат | MP4, через `task.content.url` |
| Время генерации | Измеренная медиана около 3 минут (2–6 минут) |

<Warning>
  Официальная модель MiniMax H3 поддерживает 2K, но этот канал **предлагает только 768P**; `2K` отклоняется.
</Warning>

## Эндпоинты API

| Назначение | Метод | Путь | Content-Type |
| - | - | - | - |
| Создание задачи | `POST` | `/hailuo/v2/video_generation` | `application/json` |
| Запрос задачи | `GET` | `/hailuo/v2/query/video_generation/{task_id}` | — |

<Tip>
  Основной хост — `https://api.apiyi.com`, резервный хост — `https://vip.apiyi.com`, пути совпадают. Обратите внимание, что пути **начинаются с `/hailuo`**, а не с `/v1`.
</Tip>

## Режимы генерации

Режим генерации определяется по медиафайлам в `content[]`:

| Режим | `content[]` | `ratio` |
| - | - | - |
| Текст в видео | Только 1 текстовый элемент | Требуется фиксированное соотношение сторон |
| Видео по первому кадру | Текст + 1 изображение `first_frame` | Фиксированное или `adaptive` |
| Видео по последнему кадру | Текст + 1 изображение `last_frame` | Фиксированное или `adaptive` |
| Видео по первому и последнему кадрам | Текст + `first_frame` + `last_frame` | Фиксированное или `adaptive` |
| Референсное видео | Текст + любая комбинация `reference_image` / `reference_video` / `reference_audio` | Фиксированное или `adaptive`; **только для аудио требуется фиксированное соотношение** |

### Ссылки на медиафайлы в prompt

Каждый тип медиа нумеруется в соответствии с его порядком в `content[]`: первое и второе референсные изображения — это `<Picture 1>` и `<Picture 2>`, первое референсное видео — `<Video 1>`, первое референсное аудио — `<Audio 1>`. Например:

```text theme={null}
<Picture 1> dances with the moves from <Video 1>, in time with <Audio 1>
```

<Warning>
  * Первый/последний кадры **нельзя** комбинировать ни с какими референсными медиафайлами
  * Если используется одно изображение, `role` можно опустить (оно обрабатывается как первый кадр); **при наличии двух и более изображений укажите `role` для каждого**
  * **Общая длительность** референсных видео не может превышать 15 секунд, иначе задача завершится с ошибкой (средства будут возвращены); отдельный клип длительностью более 15 секунд обрезается до первых 15 секунд
</Warning>

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

<Steps>
  <Step title="Сначала протестируйте на 4–5 секундах">
    Тарификация посекундная, поэтому перед рендерингом 10–15 секунд проверьте композицию и стиль на коротком ролике
  </Step>

  <Step title="Используйте фиксированное соотношение сторон для text-to-video">
    `16:9` для альбомной ориентации, `9:16` для портретной, `21:9` для широкоформатной; при наличии первого кадра `adaptive` сохраняет соотношение сторон изображения
  </Step>

  <Step title="Размещайте медиафайлы в стабильном публичном хранилище">
    Используйте прямые ссылки из собственного объектного хранилища или CDN, чтобы защита от хотлинкинга или истекшие подписи не прерывали скачивание медиафайлов
  </Step>

  <Step title="Описывайте движения камеры и звук">
    Опишите объект, действие, движение камеры, освещение, а также желаемую музыку и звуковые эффекты — модель сгенерирует их вместе
  </Step>

  <Step title="Опрашивайте статус каждые 10 секунд">
    Генерация обычно занимает 2–4 минуты; установите общий клиентский таймаут на 15 минут
  </Step>

  <Step title="Обеспечьте идемпотентность самостоятельно">
    Сохраняйте сопоставление бизнес-ID с task\_id; если время ожидания отправки истекло, проверьте наличие существующей задачи перед повторной отправкой
  </Step>

  <Step title="Сразу сохраняйте видео">
    Скачайте `task.content.url` с помощью GET и раздавайте его из собственного хранилища
  </Step>
</Steps>

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

| Этап | Что отображается | Причина | Что делать |
| - | - | - | - |
| Отправка | 400, `type: invalid_request`, сообщение на китайском языке | Недопустимые параметры (duration, ratio, counts, roles и т. д.) | Исправьте параметр; не повторяйте запрос |
| Отправка | 400, `bad_request_error` | Отклонено вышестоящим сервисом (например, `resolution must be 768P`, неподдерживаемое поле) | Исправьте параметр |
| Отправка | 500, `Unknown Error` | Некоторые недопустимые параметры (несколько текстовых элементов, ссылки `http://`, неизвестные поля и т. д.) или временная перегрузка | Сначала сверьте тело запроса с режимами генерации; если оно корректно, повторите попытку с задержкой |
| Отправка | 503, нет доступного канала | Группа Token не содержит эту модель, или в `model` допущена ошибка | Проверьте группу Token и название модели |
| Выполнение | `status: failed`, `input_download_failed` | Не удается загрузить медиа по URL (например, 404) | Замените ссылку на общедоступную и отправьте запрос повторно |
| Выполнение | `status: failed`, `input_format_unsupported` | Неверный формат медиа (например, аудио в поле для изображения) | Проверьте типы и форматы медиа |
| Выполнение | `status: failed`, `task_execution_failed` | Сбой генерации | Отправьте запрос повторно позже (средства за неудачную задачу были возвращены) |

<Info>
  **Советы для клиента**: установите таймаут отправки на 60 секунд (в пиковые периоды только отправка может занимать более 10 секунд); повторяйте попытки только при ошибках HTTP 500 и сетевых сбоях, с постепенным увеличением интервала. Средства за любой сбой на этапе выполнения возвращаются автоматически, а повторная отправка тарифицируется как новый запрос.
</Info>

## Часто задаваемые вопросы

<AccordionGroup>
  <Accordion title="Почему вместо JSON возвращается веб-страница?">
    В пути отсутствует префикс `/hailuo`. Корректные пути: `/hailuo/v2/video_generation` и `/hailuo/v2/query/video_generation/{task_id}`.
  </Accordion>

  <Accordion title="Поддерживается ли 2K или 1080P?">
    Этот канал поддерживает только `768P`. Официальная модель MiniMax поддерживает 2K, но в данном канале она не предоставляется.
  </Accordion>

  <Accordion title="Можно ли задать 1–3 секунды?">
    Нет. `duration` должно быть целым числом от 4 до 15.
  </Accordion>

  <Accordion title="Есть ли в видео звук? Можно ли его отключить?">
    Каждый клип содержит стереодорожку, и параметра для ее отключения нет. Если она вам не нужна, удалите аудиодорожку на этапе постобработки.
  </Accordion>

  <Accordion title="Предотвращает ли заголовок Idempotency-Key повторную тарификацию?">
    На данный момент нет. Повторная отправка с тем же `Idempotency-Key` все равно создает новую задачу, которая тарифицируется отдельно. Отслеживайте отправленные задачи на стороне своего приложения.
  </Accordion>

  <Accordion title="Тарифицируются ли неудачные задачи?">
    Нет. Как только задача переходит в статус `failed`, средства возвращаются в полном объеме автоматически; отклоненные при отправке запросы также не тарифицируются.
  </Accordion>

  <Accordion title="Можно ли отправлять Base64 или локальные файлы?">
    Нет. Все медиафайлы должны быть общедоступными HTTPS URL. Сначала загрузите их в собственное объектное хранилище и передайте ссылку.
  </Accordion>

  <Accordion title="Какой размер выдает adaptive?">
    Разрешение соответствует соотношению сторон исходного изображения, например, 768×768 для квадратного изображения и 1344×768 для изображения 16:9. Запросы, содержащие только текст или только аудио, не могут использовать `adaptive`.
  </Accordion>

  <Accordion title="Считается ли ошибкой референсное видео длительностью более 15 секунд?">
    Одиночный клип длительностью более 15 секунд автоматически обрезается до первых 15 секунд, но если суммарная длительность нескольких референсных видео превышает 15 секунд, задача завершается ошибкой (а средства возвращаются).
  </Accordion>

  <Accordion title="Сколько времени занимает генерация?">
    По замерам медианное время составляет около 3 минут, обычно 2–4 минуты; клипы длительностью 10–15 секунд обрабатываются чуть дольше.
  </Accordion>

  <Accordion title="Сколько времени действителен URL видео?">
    Мы не сталкивались с быстрым истечением срока его действия, однако долговременная доступность не гарантируется, поэтому своевременно скачивайте и сохраняйте видео. Проверяйте URL с помощью запроса GET; запросы HEAD возвращают 403.
  </Accordion>

  <Accordion title="Что делать, если при отправке иногда возвращается 500 Unknown Error?">
    Сначала убедитесь, что тело запроса соответствует правилам (ровно один текстовый элемент, никаких лишних полей, медиассылки по HTTPS). Если все верно, обычно это временная перегрузка: подождите несколько секунд и повторите попытку. Запросы с ошибкой отправки не тарифицируются.
  </Accordion>
</AccordionGroup>

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

* [Справочник по API генерации видео MiniMax-H3](/ru/api-capabilities/minimax-h3/video-generation)
* [Генерация видео Seedance 2.0 / 2.5](/ru/api-capabilities/seedance2/overview)
* [Генерация видео Wan2.7](/ru/api-capabilities/wan/overview)
* [Генерация видео VEO 3.1](/ru/api-capabilities/veo-3-1-official/overview)
* [Бонусы за пополнение](/ru/faq/recharge-promotions)