> ## 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.
# Посібник з інтеграції API генерації відео MiniMax H3
> Minimax API guide - Ace Data Cloud
У цій статті описано інтеграцію та використання API генерації відео MiniMax H3. Цей інтерфейс підтримує генерацію відео з тексту, керування першим і останнім кадрами та генерацію відео з мультимодальними референсами, використовуючи уніфіковану мультимодальну структуру `content` V2 для створення завдань.
## Процес подання заявки
Щоб використовувати API генерації відео MiniMax H3, спочатку перейдіть до [консолі Ace Data Cloud](https://platform.acedata.cloud/console/applications), щоб отримати ваш API Token, і збережіть його для подальшого використання.
Якщо ви ще не увійшли або не зареєструвалися, вас автоматично буде перенаправлено на сторінку входу із запрошенням зареєструватися та увійти, після завершення ви автоматично повернетеся на поточну сторінку.
**Один API Token може викликати всі сервіси платформи, не потрібно окремо подавати заявку для кожного сервісу.** Під час першого подання заявки надається безкоштовна квота для безкоштовного ознайомлення; коли квоти недостатньо, ви можете поповнити загальний баланс у [консолі](https://platform.acedata.cloud/console/coin).
> 📘 Повна документація: [API генерації відео MiniMax H3 →](https://platform.acedata.cloud/documents/minimax-videos-integration)
Рекомендується зберігати Token як змінну середовища, не записуйте його у вихідний код і не додавайте до репозиторію версій:
```bash theme={null}
export ACEDATACLOUD_API_KEY="YOUR_API_KEY"
```
## Огляд інтерфейсу
* **Base URL**：`https://api.acedata.cloud`
* **Endpoint**：`POST /minimax/videos`
* **Спосіб автентифікації**：передавайте `authorization: Bearer {token}` у HTTP Header
* **Заголовки запиту**：
* `accept: application/json`
* `content-type: application/json`
* **Модель (model)**：`MiniMax-H3`
* **Структура введення**：текст, зображення, відео та аудіо передаються уніфіковано через `content`
* **Режим виведення**：за замовчуванням синхронно очікує завершення генерації та повертає повний `task`; при передачі `async: true` або `callback_url` негайно повертає `task_id` і `trace_id`
* **Запит результату**：отримуйте статус і готове відео через [API запиту завдань MiniMax H3](https://platform.acedata.cloud/documents/minimax-tasks-integration)
* **Асинхронний callback**：необов’язково, отримуйте фінальний результат завдання через `callback_url`
Вам не потрібно передавати `action` для вибору режиму генерації, інтерфейс автоматично визначить призначення за типом матеріалів і `role` у `content`.
## Для яких сценаріїв підходить
| Сценарій | Комбінація введення | Типові застосування |
| - | - | - |
| Генерація відео з тексту | Текст | Рекламні ідеї, попередня візуалізація розкадровки, короткі відео, атмосферні кадри |
| Генерація відео із зображення першого кадру | Текст + зображення першого кадру | Природно оживити зображення товару, постер, фото людини або ілюстрацію |
| Відео з останнім кадром / першим і останнім кадрами | Текст + останній кадр, або текст + перший кадр + останній кадр | Керування початком і кінцем, переходами, змінами зростання та порівняннями до і після |
| Генерація відео з мультимодальними референсами | Текст + референсне зображення / відео / аудіо | Збереження узгодженості персонажа та продукту, відтворення рухів, руху камери, тембру або ритму монтажу |
## Процес виклику
Якщо за замовчуванням не передавати `async`, `/minimax/videos` очікуватиме завершення генерації та безпосередньо поверне повний `task`. Коли потрібно негайно звільнити з’єднання, передайте `async: true` або `callback_url`:
1. Збережіть `task_id` і `trace_id` з негайної відповіді.
2. Якщо callback не налаштовано, приблизно кожні 10 секунд викликайте `/minimax/tasks` для запиту.
3. Коли `task.status` зміниться на `succeeded`, отримайте відео з `task.content.url`.
4. Коли статус буде `failed` або `cancelled`, припиніть опитування та прочитайте `task.error`.
## Параметри запиту верхнього рівня
| Параметр | Тип | Обов’язковий | Значення за замовчуванням | Опис |
| - | - | - | - | - |
| `model` | string | Так | - | Фіксовано як `MiniMax-H3` |
| `content` | object\[] | Так | - | Масив мультимодального контенту, повинен містити один непорожній елемент `text` |
| `resolution` | string | Так | - | `768P` або `2K` |
| `duration` | integer | Так | - | Тривалість генерації, ціле число 4-15 секунд |
| `ratio` | string | Умовно обов’язковий | `adaptive` | `adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` |
| `async` | boolean | Ні | `false` | При `true` негайно повертає ідентифікатор завдання, отримуйте результат через інтерфейс завдань |
| `callback_url` | string | Ні | - | Загальнодоступний callback URL для отримання фінального результату завдання; після надання автоматично вмикається асинхронний режим |
Правила для `ratio` залежать від робочого процесу:
* **Генерація відео з тексту**：обов’язковий, і не може бути `adaptive`.
* **Відео з першим кадром, останнім кадром або першим і останнім кадрами**：співвідношення сторін визначається вхідним зображенням, рекомендується пропустити або передати `adaptive`.
* **Генерація відео з мультимодальними референсами**：можна пропустити, за замовчуванням `adaptive`; також можна явно вказати фіксоване співвідношення.
Інтерфейс не приймає застарілі або сумісні поля, наприклад `prompt`, `image_urls`, `audio_urls`, `messages` і `first_frame_image`. У разі отримання помилки таких параметрів видаліть старі поля та перенесіть їх до `content`; наприклад, змініть `"prompt": "一只猫挥手"` на `"content": [{"type": "text", "text": "一只猫挥手"}]`。Не надсилайте одночасно новий і старий формати.
## Параметри елементів контенту content
Кожен елемент контенту повинен мати `type`, інші поля визначаються типом:
| `type` | Поле даних | `role` | Опис |
| - | - | - | - |
| `text` | `text` | Не передається | Кожен запит повинен містити один непорожній текстовий елемент, максимум 7000 символів |
| `image_url` | `image_url.url` | `first_frame` | Зображення першого кадру; якщо є лише одне зображення і `role` пропущено, воно також обробляється як перший кадр |
| `image_url` | `image_url.url` | `last_frame` | Зображення останнього кадру; може використовуватися окремо або в комбінації з `first_frame` для керування початком і кінцем |
| `image_url` | `image_url.url` | `reference_image` | Референсний об’єкт, персонаж, продукт, одяг, сцена або стиль |
| `video_url` | `video_url.url` | `reference_video` | Референсні рухи, рух камери, виконання або структура монтажу |
| `audio_url` | `audio_url.url` | `reference_audio` | Референсний тембр, діалоги, музика або ритм |
Адреси медіафайлів підтримують три формати:
* Загальнодоступний HTTPS URL, рекомендовано для великих файлів.
* `mm_file://{file_id}`, посилання на вже завантажений файл або файл із наявним результатом.
* Base64 data URI відповідного медіатипу. Base64 збільшує розмір приблизно на одну третину, переконайтеся, що весь body запиту не перевищує 64 MB.
## Специфікації матеріалів і обмеження кількості
| Матеріали | Формат | Обмеження на один файл | Розмір / тривалість | Обмеження кількості |
| - | - | - | - | - |
| Зображення | JPG、JPEG、PNG、WEBP、HEIC、HEIF | Не більше 30 MB | Ширина й висота: 256-5760 px; співвідношення сторін: 0.4-2.5 | Не більше 1 першого кадру, 1 останнього кадру, 9 референсних зображень |
| Відео | MP4、MOV；H.264/AVC або H.265/HEVC；аудіодоріжка AAC або MP3 | Не більше 50 MB | Кожен фрагмент 2-15 секунд, загалом не більше 15 секунд; ширина й висота: 256-5760 px; співвідношення сторін: 0.4-2.5; 23.976-60 fps | Не більше 3 референсних відео |
| Аудіо | WAV、MP3 | Не більше 15 MB | Кожен фрагмент 2-15 секунд, загалом не більше 15 секунд | Не більше 3 референсних аудіо |
Загалом зображення, відео й аудіо в мультимодальному референсному сценарії можуть містити не більше 12 файлів. Сценарій першого й останнього кадрів та сценарій референсних матеріалів є взаємовиключними: щойно використано `reference_image`、`reference_video` або `reference_audio`, більше не можна використовувати `first_frame` або `last_frame`, і навпаки.
## Демонстрація можливостей виробничого рівня
Нижче наведено не концепт-арти чи матеріали-заповнювачі, а реальні референсні вхідні дані й фактичні відеовиходи офіційних зразків можливостей виробничого рівня MiniMax H3. Три групи прикладів відповідно охоплюють брендове коротке відео, художню оповідь із реальними людьми та модну електронну комерцію, що підходить для оцінювання найважливіших можливостей моделі в комерційному виробництві.
| Можливість | Ключові аспекти для спостереження |
| - | - |
| Узгодженість персонажів і облич | Чи залишаються стабільними риси обличчя, зачіска, макіяж і характер персонажа після перемикання між кількома кадрами |
| Мімічна гра | Погляд, мікровирази, емоційна напруга та природні рухи голови у крупному плані |
| Збереження структури товару | Контури, матеріали, спосіб носіння та дзеркальні відбиття таких продуктів, як окуляри й сумки |
| Реалізація брендового візуалу | Чи єдині атмосфера сцени, кінематографічне зерно, кольори, Logo та ритм монтажу |
| Кінематографічна оповідь | Чи можуть зміни планів, режисура персонажів, рух камери, ритм і звук утворити завершений епізод |
Тут «можливості обличчя» означають узгодженість зовнішності персонажа, деталі обличчя та контроль гри у генерації відео, а не розпізнавання особи, порівняння облич або інтерфейс заміни облич.
### Коротке відео преміального бренду: єдність персонажів, продуктів і бренд-активів
**Мета виробництва：** Брендове відео високої моди 16:9. Створити сувору атмосферу за допомогою пустельної дороги й ретроавтомобіля, зберегти зовнішність головної героїні та структуру чорної сумки, а також природно інтегрувати Logo бренду в завершення. Цей приклад зосереджений на перевірці узгодженості персонажів між кадрами, збереженні товару, кінематографічній якості та здатності завершити відео брендовим акцентом.
| Референс атмосфери й сцени | Референс персонажа |
| - | - |
| 
| 
|
| Референс продукту — сумки | Референс Logo бренду |
| - | - |
| 
| 
|
[Безпосередньо відкрити або завантажити брендове коротке відео](https://cdn.acedata.cloud/uploads/6845b11d-1a58-4478-afd8-29e7e117772a)
Відповідний спосіб організації `content`：
```json theme={null}
{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "15 秒、16:9 高级时装品牌片。荒漠公路旁停着复古汽车，女主从后备箱取出黑色手袋，与男主短暂对视后独自离开。保持人物、手袋与品牌视觉一致；冷峻高级，电影颗粒，剪辑利落，结尾自然呈现品牌 Logo。"
},
{
"type": "image_url",
"image_url": { "url": "https://cdn.acedata.cloud/uploads/6e65f865-f1c2-4f80-8b51-9a98d4d930b1" },
"role": "reference_image"
},
{
"type": "image_url",
"image_url": { "url": "https://cdn.acedata.cloud/uploads/88d89cc3-e6cb-42b4-ab4c-1bbbf6c9f7c8" },
"role": "reference_image"
},
{
"type": "image_url",
"image_url": { "url": "https://cdn.acedata.cloud/uploads/e91f7fff-f8e3-4da5-b882-87edbc3c9473" },
"role": "reference_image"
},
{
"type": "image_url",
"image_url": { "url": "https://cdn.acedata.cloud/uploads/b68dac43-fb14-42b5-bf8b-fd4d65506520" },
"role": "reference_image"
}
],
"resolution": "2K",
"duration": 15,
"ratio": "16:9"
}
```
### Вертикальна коротка драма з реальними людьми: узгодженість облич і емоційна гра
**Мета створення:** 15-секундний, 9:16 трейлер темної романтичної короткої драми. За допомогою референсних зображень головних чоловічого та жіночого персонажів зафіксувати зовнішність персонажів, а за допомогою референсного зображення стародавнього замку обмежити простір; використовувати середні крупні плани та крупні плани облич для передачі протистояння поглядів, страху, стриманості та відчуття небезпеки. Цей кейс підходить для спостереження за стабільністю рис обличчя реальних людей, мікровиразами, взаємозв’язком поглядів і безперервною акторською грою.
| Референс головних чоловічого та жіночого персонажів | Референс сцени стародавнього замку |
| - | - |
| 
| 
|
[Відкрити або завантажити коротку драму з реальними акторами безпосередньо](https://cdn.acedata.cloud/uploads/0f3e9bf2-5073-46f4-9a2d-7d8d912391cf)
Промпт має чітко визначати стосунки персонажів, емоції та крупність плану, а не лише описувати «діалог чоловіка й жінки»:
```text theme={null}
15 秒、9:16 真人暗黑浪漫短剧预告。女主误入禁忌古堡，唤醒沉睡的吸血鬼贵族；
他危险而克制地靠近，她恐惧但不屈服。保持两位角色的五官、发型与服装一致，
以中近景和面部特写表现眼神对峙与情绪张力，暗色电影光线，节奏紧凑。
```
### Реклама модних окулярів: збереження деталей обличчя та структури товару
**Мета створення:** Реклама преміальних модних окулярів у форматі 9:16. Зображення моделі в повний зріст відповідає за статуру та ходу, референс обличчя — за риси обличчя та макіяж, зображення продукту — за вигини оправи, відображення лінз, дужки та контур «котяче око». Цей кейс одночасно перевіряє крупні плани обличчя, узгодженість кількох людей, зв’язок носіння та геометричну структуру товару.
| Референс моделі та стилізації | Референс деталей обличчя | Референс продукту — окулярів |
| - | - | - |
| 
| 
| 
|
[Відкрити або завантажити рекламу модних окулярів безпосередньо](https://cdn.acedata.cloud/uploads/55715089-b6bd-4ef6-a3c2-e762a672f751)
У рекламі товарів промпт має чітко розділяти ролі референсів персонажів і референсів продукту: матеріали персонажів обмежують обличчя, макіяж, статуру та темперамент; матеріали продукту обмежують контур, матеріал, відображення та положення при носінні. Це стабільніше, ніж узагальнено писати «згенерувати рекламу окулярів».
## Генерація відео з тексту
Коли є лише один текстовий елемент, це генерація відео з тексту. Підходить для безпосереднього створення зображення на основі творчої ідеї, сценарію або опису кадру. Промпт можна організувати в порядку «суб’єкт + дія + сцена + камера + освітлення + звук».
```bash theme={null}
curl -X POST 'https://api.acedata.cloud/minimax/videos' \
-H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "15 秒电影级香水广告：清晨海岸的黑色礁石上，透明香水瓶被薄雾与海浪环绕。微距展现瓶身水珠和玻璃折射，镜头从产品特写缓慢拉升到广阔海面；银蓝色调，真实自然光，高级克制，结尾定格产品。"
}
],
"resolution": "2K",
"duration": 15,
"ratio": "16:9"
}'
```
Стандартний синхронний режим після завершення генерації повертає повне завдання:
```json theme={null}
{
"task": {
"id": "f5977217-ed2c-40da-adbe-93d08235618f",
"model": "MiniMax-H3",
"status": "succeeded",
"content": { "url": "https://cdn.acedata.cloud/minimax/f5977217.mp4" },
"resolution": "2K",
"duration": 15,
"ratio": "16:9"
}
}
```
Якщо до запиту додати `"async": true`, інтерфейс негайно повертає:
```json theme={null}
{
"task_id": "f5977217-ed2c-40da-adbe-93d08235618f",
"trace_id": "trace_7f8c2b1a"
}
```
## Генерація відео із зображення першого кадру
Позначте зображення як `first_frame`, і модель почне генерацію з цього кадру. Підходить для природного оживлення постерів, зображень товарів, концепт-артів персонажів і фотографічних робіт.
```json theme={null}
{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "人物自然呼吸并看向窗外，衣角被微风吹动，镜头缓慢推进"
},
{
"type": "image_url",
"image_url": {
"url": "https://cdn.acedata.cloud/b1c82e4937.png"
},
"role": "first_frame"
}
],
"resolution": "2K",
"duration": 5,
"ratio": "adaptive"
}
```
## Відео з останнім кадром і початковим та кінцевим кадрами
Надання лише `last_frame` дозволяє моделі природно генерувати до заданого кадру; одночасне надання `first_frame` і `last_frame` дає змогу чітко контролювати початкову та кінцеву точки. Підходить для переходів, змін форми, процесу зростання або порівняння продукту до та після.
```json theme={null}
{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "女孩从童年自然成长为青年，时间流逝平滑，人物始终位于画面中央"
},
{
"type": "image_url",
"image_url": { "url": "YOUR_FIRST_FRAME_URL" },
"role": "first_frame"
},
{
"type": "image_url",
"image_url": { "url": "YOUR_LAST_FRAME_URL" },
"role": "last_frame"
}
],
"resolution": "2K",
"duration": 5,
"ratio": "adaptive"
}
```
Розміри та співвідношення сторін першого й останнього кадрів мають бути якомога більш узгодженими, а відмінності в положенні головного об’єкта, композиції та освітленні не повинні бути надто великими — так легше отримати природний перехід.
## Генерація відео за мультимодальними референсами
Референсні матеріали можна комбінувати: референсні зображення контролюють зовнішність персонажа або продукту, референсні відео — рухи й рух камери, а референсне аудіо — тембр діалогів, музику або ритм монтажу. У промпті слід чітко вказати, що має контролювати кожен тип матеріалу, щоб уникнути ситуації, коли матеріали лише завантажуються без зазначення зв’язків між ними.
```json theme={null}
{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "保持参考人物的五官、发型与服装一致，按照参考视频中的表演动作完成时尚短片；镜头节奏跟随参考音频，近景突出自然面部表情"
},
{
"type": "image_url",
"image_url": { "url": "YOUR_CHARACTER_IMAGE_URL" },
"role": "reference_image"
},
{
"type": "video_url",
"video_url": { "url": "YOUR_PERFORMANCE_VIDEO_URL" },
"role": "reference_video"
},
{
"type": "audio_url",
"audio_url": { "url": "YOUR_AUDIO_URL" },
"role": "reference_audio"
}
],
"resolution": "2K",
"duration": 5,
"ratio": "adaptive"
}
```
## Сповіщення зворотного виклику
Передавання `callback_url` автоматично вмикає асинхронний режим: інтерфейс створення негайно повертає `task_id` і `trace_id`, а після завершення завдання надсилає остаточний результат методом POST на цю адресу; структура відповідає структурі відповіді на запит стану завдання.
Остаточний статус у зворотному виклику буде `succeeded`, `failed` або `cancelled`. Навіть у разі використання зворотного виклику також рекомендується зберігати `task_id`, щоб мати змогу виконувати активні запити або компенсувати пропущені сповіщення.
## Поширені помилки
| Код стану HTTP | Значення | Рекомендації щодо обробки |
| - | - | - |
| `400` | Помилка параметрів або недопустима комбінація матеріалів | Перевірте обов’язкові поля, `role`, кількість і формат матеріалів |
| `401` | Token відсутній або недійсний | Перевірте `Authorization: Bearer ...` |
| `402` | Недостатньо балансу або ліміту | Поповніть загальний баланс у консолі |
| `422` | Перевірку безпеки контенту не пройдено | Скоригуйте промпт або матеріали та надішліть повторно |
| `429` | Запити надто часті | Повторіть спробу після експоненційної затримки; рекомендований інтервал опитування завдання — близько 10 секунд |
| `500` | Сервіс тимчасово недоступний | Збережіть інформацію про запит і повторіть спробу пізніше |
`task.status: succeeded` у синхронній відповіді означає, що відео вже згенеровано; асинхронне підтвердження лише означає, що завдання потрапило в чергу. Плата стягується лише за остаточно успішно виконане завдання; самі запити стану завдання безкоштовні та не призводять до повторного списання коштів.
### H3 Max
`MiniMax-H3-Max` підтримує 480P або 768P та цілочисельну тривалість від 5 до 15 секунд. За аудіовхід додаткова плата не стягується, перші 2 зображення безкоштовні, а за кожне понад цей ліміт стягується плата; референсні відео оплачуються відповідно до фактичної тривалості вхідного матеріалу. Ця модель не підтримує 2K.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.