MiniMax H3 Image Генерация изображений

POST

/v1/images/generations

Для пользователей из материкового Китая: используйте https://toapis.cn в качестве эндпоинта (Base URL). Замените https://toapis.com на https://toapis.cn во всех примерах этого документа.

Используйте minimax-h3-image для генерации изображений или передавайте эталонные изображения для редактирования. API сначала возвращает id задачи; получите результат через Статус задачи изображения.

Authorizations

Authorizationstringзаголовокобязательно

Используйте токен доступа платформы в формате Authorization: Bearer <token>. Токены управляются в консоли вашего сайта.

Body

Тип запроса — application/json. Все параметры модели ниже передаются на верхнем уровне тела запроса.

modelstringтелообязательнопо умолчанию: minimax-h3-image

Фиксированное значение minimax-h3-image.

promptstringтелообязательно

Текстовое описание или инструкция редактирования. После удаления пробелов по краям должна содержать 1-32000 символов Unicode и не может состоять только из пробелов.

nintegerтелопо умолчанию: 1

Количество генерируемых изображений, диапазон 1-10. Фактическое число успешных изображений может быть меньше запрошенного.

sizestringтелопо умолчанию: auto

Если параметр опущен или равен auto, размеры определяются resolution и aspect_ratio. Можно также передать явные пиксельные размеры, например 1024x1024: ширина и высота — положительные целые числа, общее число пикселей в диапазоне 655360-20000000, соотношение сторон от 1:3 до 3:1.

Явный пиксельный size нельзя совмещать с resolution или aspect_ratio, даже если они равны auto. В этом режиме значение 4K по умолчанию не применяется.

Также принимается запись пропорций вида 16:9, эквивалентная aspect_ratio. Если пропорции указаны в обоих полях, они должны совпадать. Для уровней разрешения используйте resolution; не пишите size: "4K".

aspect_ratiostringтелопо умолчанию: auto

Поддерживается auto или пропорция ширина:высота, например 1:1, 4:3, 16:9. Каждый компонент — целое число от 1 до 300, пропорция от 1:3 до 3:1. Не совмещается с явным пиксельным size.

resolutionstringтелопо умолчанию: 4K

Только заглавные 1K, 2K, 4K. Это уровень разрешения, а не фиксированные размеры; фактический размер указан в поле size результата. Не совмещается с явным пиксельным size.

image_urlsstring[]тело

Необязательный список URL эталонных изображений, до 16 штук. Используйте доступные HTTP(S) URL; встраивание имени пользователя или пароля в URL не допускается, Base64 и data URI не поддерживаются. Запросы с эталонными изображениями обрабатываются как редактирование и всегда включают улучшение промпта.

URL должны быть доступны сервису обработки изображений и не могут зависеть от вашей локальной сети или сессии браузера. То, что изображение открывается в браузере, не гарантирует успешное редактирование; после отправки проверяйте финальный статус задачи и поля ошибок.

output_formatstringтелопо умолчанию: jpeg

Поддерживаются jpeg, jpg, png, webp. jpg эквивалентен jpeg.

response_formatstringтелопо умолчанию: url

Поддерживается только url. URL изображений возвращаются в результате задачи после завершения, а не в ответе на отправку.

output_compressionintegerтелопо умолчанию: 95

Диапазон 0-100. Чем выше значение, тем выше качество и обычно больше файл. Действует только для JPEG и WebP; PNG игнорирует этот параметр.

disable_prompt_enhancedbooleanтелопо умолчанию: false

Отключить ли улучшение промпта. true допускается только для чистой генерации по тексту и требует явного пиксельного size или фиксированной пропорции. Нельзя установить true при передаче эталонных изображений.

aigc_watermarkbooleanтелопо умолчанию: false

Добавлять ли видимый водяной знак AIGC. Этот переключатель не управляет идентификаторами в метаданных файла изображения.

webhookstringтело

Необязательный URL обратного вызова по завершении задачи, см. Webhook задач.

Неподдерживаемые параметры

Не передавайте area, mask, mask_url, background, quality, partial_images, preview, previous_task_id, image_size, seed, watermark, prompt_extend, а также одноимённые поля metadata. Для уровней разрешения используйте resolution, для видимого водяного знака — aigc_watermark.

stream=true, ввод и вывод Base64 и multipart-загрузка файлов не поддерживаются. Не применяйте параметры или значения по умолчанию других моделей изображений.

Пример запроса

curl --request POST \
  --url 'https://toapis.com/v1/images/generations' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "minimax-h3-image",
    "prompt": "A small house by the sea, watercolor illustration style",
    "n": 1,
    "resolution": "2K",
    "aspect_ratio": "16:9",
    "output_format": "png",
    "response_format": "url"
  }'

Пример с явным пиксельным размером; поля разрешения и пропорций не передаются:

{
  "model": "minimax-h3-image",
  "prompt": "A small house by the sea, watercolor illustration style",
  "size": "1536x1024",
  "n": 1,
  "output_format": "webp",
  "output_compression": 90
}

Ответ на отправку

Ниже приведён пример структуры ответа:

{
  "id": "tsk_img_example",
  "object": "generation.task",
  "model": "minimax-h3-image",
  "status": "queued",
  "progress": 0,
  "created_at": 1794355200
}

Сохраните id и опрашивайте через GET /v1/images/generations/{task_id}; также работает GET /v1/tasks/{task_id}. Опрашивайте с интервалом не менее 5-10 секунд и джиттером, при 429 соблюдайте Retry-After. Остановка локального ожидания не отменяет задачу; продолжайте опрашивать исходную задачу и не отправляйте повторно.

Результаты и тарификация

result.data содержит только успешные изображения. Поле image_index каждого элемента — это исходный индекс изображения с нуля, а не индекс в массиве успешных. size, output_format и revised_prompt описывают фактический результат изображения.
При частичном успехе result.failed_images содержит image_index и error неудачных элементов; при полном успехе поле отсутствует. completed не гарантирует успех всех запрошенных изображений.
result.request_id — идентификатор для трассировки и не заменяет id задачи при запросах.
usage.generated_images — число фактически успешных изображений, возвращается с расчётным использованием. Плата рассчитывается по фактическим токенам текстового ввода, ввода изображений и вывода изображений отдельно, а не как произведение n на фиксированную цену за изображение.
Текущую цену смотрите в котировке консоли вашего сайта и аккаунта. Итоговая сумма определяется billing при billing.status=settled. Не считайте предварительно удержанную сумму или отсутствующее использование окончательными расходами.

Полный ответ и поля расчёта см. в Статус задачи изображения.