> ## 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. Этот интерфейс поддерживает генерацию видео по тексту, управление первым и последним кадрами и генерацию видео по мультимодальным референсам, используя унифицированную мультимодальную структуру V2 `content` для создания задач. ## Процесс получения доступа Чтобы использовать API генерации видео MiniMax H3, сначала получите ваш 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). > 📘 Полная документация: [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 | Нет | - | Публичный URL callback для получения финального результата задачи; при указании автоматически включается асинхронный режим | Правила для `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 МБ | Ширина и высота: 256–5760 px; соотношение сторон 0.4–2.5 | Не более 1 первого кадра, не более 1 последнего кадра, не более 9 референсных изображений | | Видео | MP4、MOV; H.264/AVC или H.265/HEVC; аудиодорожка AAC или MP3 | Не более 50 МБ | Каждый фрагмент 2–15 секунд, суммарно не более 15 секунд; ширина и высота: 256–5760 px; соотношение сторон 0.4–2.5; 23.976–60 fps | Не более 3 референсных видеофрагментов | | Аудио | WAV、MP3 | Не более 15 МБ | Каждый фрагмент 2–15 секунд, суммарно не более 15 секунд | Не более 3 референсных аудиофрагментов | В мультимодальном референсном сценарии общее количество изображений, видео и аудио составляет не более 12 файлов. Сценарий с первым и последним кадрами и сценарий с референсными материалами взаимоисключающие: при использовании `reference_image`, `reference_video` или `reference_audio` больше нельзя использовать `first_frame` или `last_frame`, и наоборот. ## Демонстрация возможностей производственного уровня Ниже приведены не концепт-арты и не материалы-заполнители, а реальные референсные входные данные и фактические видео-результаты официальных примеров возможностей MiniMax H3 производственного уровня. Три группы кейсов соответственно охватывают брендовые короткометражные фильмы, повествование с реальными людьми и модную электронную коммерцию, и подходят для оценки наиболее ключевых возможностей модели в коммерческом производстве. | Возможность | Ключевые наблюдения | | - | - | | Согласованность персонажей и лиц | Стабильны ли черты лица, причёска, макияж и характер персонажа после переключения между несколькими кадрами | | Мимика | Взгляд, микромимика, эмоциональное напряжение и естественные движения головы в крупных планах | | Сохранение структуры товара | Контуры, материалы, взаимное расположение при ношении и зеркальные отражения таких товаров, как очки и сумки | | Реализация визуального стиля бренда | Едины ли атмосфера сцены, кинематографическое зерно, цвета, Logo и ритм монтажа | | Кинематографическое повествование | Могут ли изменения крупности плана, постановка персонажей, движение камеры, ритм и звук сформировать цельный фрагмент | Под «возможностями работы с лицами» здесь понимаются согласованность внешности персонажей, детализация лиц и управление актёрской игрой при генерации видео, а не распознавание личности, сопоставление лиц или интерфейс замены лиц. ### Короткометражный фильм премиального бренда: единство персонажей, продукта и бренд-активов **Цель производства:** модный брендовый фильм премиального уровня в формате 16:9. Создать холодную атмосферу с помощью пустынной дороги и винтажного автомобиля, сохранить внешность главной героини и структуру чёрной сумки, а также естественно включить Logo бренда в финал. Этот кейс главным образом проверяет согласованность персонажей между кадрами, сохранение товара, кинематографичность и способность завершать ролик брендингом. | Референс атмосферы и сцены | Референс персонажа | | - | - | | Референс атмосферы брендового фильма с пустынной дорогой и винтажным автомобилем | Референс главной героини брендового фильма | | Референс продукта — сумки | Референс Logo бренда | | - | - | | Референс продукта — чёрной сумки | Референс Logo бренда |