MiniMax H3 Image Highspeed

Генерация или редактирование изображения по тексту и не более чем 16 референсам в 1K, 2K или 4K либо в точном размере в пикселях; оплата по токенам, которые потратил каждый рендер.

• Асинхронная обработка: запрос создания быстро возвращает ID задачи. Изображение будет доступно после её успешного завершения.
• Одна задача создаёт одно изображение. Для нескольких изображений создайте несколько задач.
• Генерация по тексту либо редактирование и объединение до 16 референсных изображений по общедоступным HTTPS-ссылкам.
• Выберите кадр через resolution и aspect_ratio либо одним точным size, например 2720x1536. Вместе — нельзя. По умолчанию aspect_ratio равен auto: кадр выбирает модель по промпту и изображениям, если они есть.
• Оплата по токенам: ввод текста (промпт, включая улучшение промпта MiniMax), ввод референсов и вывод изображения — каждый по своей цене за 1 млн токенов. Цены за изображение ниже — оценки. По умолчанию resolution равен 4K; 1K и 2K тратят одинаковое число выходных токенов и стоят одинаково.
• Результат — файл png (по умолчанию), jpeg или webp, формат задаёт output_format. Неудавшаяся задача ничего не стоит.

Открывает модель в API Explorer. Введите свой API-ключ BeatAPI, чтобы создать задачу. Это настоящий запрос: его стоимость спишется с вашего баланса.

Идентификаторы моделей

Обе модели MiniMax H3 Image используют этот эндпоинт и принимают одни и те же поля. Значения ниже взяты прямо из контракта шлюза.

Адрес API и авторизация

POST https://api.beatapi.io/v1/images/tasks

Передавайте тело запроса в JSON с заголовком Content-Type: application/json. Idempotency-Key необязателен. Для каждого логического запроса используйте уникальное значение длиной не более 255 символов и повторно используйте его только для отправки точно такого же тела. В течение 24 часов повтор с тем же ключом и телом возвращает первый ответ с заголовком Idempotent-Replayed: true. Тот же ключ с другим телом возвращает 409 idempotency_conflict. Ответы, отличные от 2xx, не сохраняются, поэтому повтор после 400 или 402 выполняется заново.

Как выполняется запрос

Режимы ввода

Параметры запроса

"images": [
  "https://cdn.beatapi.io/samples/smart-bottle.png",
  "https://cdn.beatapi.io/samples/neon-singer.png"
]

"size": "2720x1536"

"output_format": "webp"

Перед созданием задачи шлюз также проверяет следующие сочетания параметров:

• size задаётся как ШxВ и заменяет resolution и aspect_ratio: всего от 655 360 до 20 000 000 пикселей, не шире и не выше 3:1; кадр рендерится ровно как задан и не округляется.
• Оплата по токенам по указанным ценам за токены, которые потратил каждый рендер (ввод текста с улучшением промпта, референсы, вывод изображения); указанные цены за изображение — оценки; 1K и 2K тратят одинаковое число выходных токенов.
• aspect_ratio: auto — кадр выбирает модель по промпту и изображениям, если они есть.

Ограничения входных материалов

До создания задачи шлюз проверяет каждый входной материал. Если ограничение нарушено, возвращается 400 bad_request с указанием материала. Средства не списываются.

• Референсные изображения: PNG, JPEG или WebP с определением формата по содержимому; до 50 MB каждый (десятичные мегабайты; проверяется, если сервер сообщает размер), от 1 до 16 ссылок. GIF, HEIC и SVG отклоняются.
• Для самих референсных изображений ограничения числа пикселей и соотношения сторон не проверяются.
• Если сервер не ответил вовремя, ссылка не отклоняется при создании. Шлюз скачивает её повторно при запуске обработки. Если скачать по-прежнему нельзя, задача завершается ошибкой с возвратом средств.
• Файл находится на вашем устройстве? Загрузите его через POST /v1/files и передайте полученный data.url.

Размер кадра: resolution и aspect_ratio либо size

Задать размер и ширину изображения можно двумя способами, они взаимоисключающие:

• Класс и соотношение. Передайте resolution (1K, 2K или 4K) и, если нужна форма, aspect_ratio. Если не указать ни то, ни другое, будут 4K и auto: кадр выбирает модель.
• Точный размер. Передайте только size, например 2720x1536: от 655 360 до 20 000 000 пикселей, не шире и не выше 3:1, рендерится ровно как задано.

Если отправить size вместе с resolution или aspect_ratio, запрос будет отклонён с ошибкой "size" already fixes the output; do not send "resolution" with it (или "aspect_ratio"). Проверка срабатывает, даже если другое поле равно значению по умолчанию.

На чём основана оценка

Цены за изображение в таблице ниже — оценки. Каждая рассчитана на 3 000 текстовых токенов (промпт и улучшение промпта MiniMax) и выходные токены класса, без референсов. Итоговая плата рассчитывается по токенам, которые рендер реально потратил.

Параметры, которые модель не принимает

Эндпоинт изображений знает несколько полей, которые используют другие модели изображений. Здесь их отправка отклоняется, а не игнорируется, поэтому вы не платите за настройку, которая ни на что не повлияла:

• background, quality, seed, enhance_prompt → field "background" is not supported by model minimax-h3-image-highspeed (с отправленным полем и вызванной моделью).
• Любое другое неизвестное поле, например n или moderation → unknown field: n. Поля n нет: одна задача создаёт одно изображение.

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

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3-image-highspeed",
  "prompt": "A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field",
  "aspect_ratio": "3:2",
  "resolution": "2K"
}'

Изображение по тексту

Горизонтальное изображение в 2K по промпту, с указанием класса и пропорций.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3-image-highspeed",
  "prompt": "A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field",
  "aspect_ratio": "3:2",
  "resolution": "2K"
}'

Пусть кадр выберет модель

Только промпт: resolution равен 4K, а aspect_ratio равен auto, поэтому кадр выбирает модель.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3-image-highspeed",
  "prompt": "A tall, narrow travel poster of a mountain railway at dawn, bold flat colours"
}'

Редактирование одного изображения

Меняем фон и сохраняем товар.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3-image-highspeed",
  "prompt": "Keep the bottle exactly as it is. Replace the background with a sunlit kitchen counter and add a soft reflection under the bottle.",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png"
  ],
  "aspect_ratio": "1:1",
  "resolution": "2K"
}'

Объединение нескольких изображений

Укажите каждый референс в промпте по его порядку.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3-image-highspeed",
  "prompt": "Place the bottle from the first image on a neon-lit stage like the one in the second image. Keep the bottle label readable.",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png",
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "aspect_ratio": "16:9",
  "resolution": "2K"
}'

Точный размер

Кадр 2720x1536 в формате WebP. size передаётся один: без resolution и без aspect_ratio.

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "minimax-h3-image-highspeed",
  "prompt": "A flat illustration of a lighthouse on a cliff at dawn, pastel colours, clean shapes",
  "size": "2720x1536",
  "output_format": "webp"
}'

Ответы

Создание задачи (201)

Объект задачи. Поле output равно null, пока задача не завершится успешно. Поля с пометкой «во время выполнения» исчезают после завершения задачи.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "minimax-h3-image-highspeed",
    "capability_version": 1,
    "media_type": "image",
    "model": "minimax-h3-image-highspeed",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 5,
    "output": null,
    "usage": {
      "credits_reserved": 0.026621,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 0.026621
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Успешно завершённая задача

GET /v1/tasks/{task_id} возвращает HTTP 200 со status: "succeeded" и результатом в data.output.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "minimax-h3-image-highspeed",
    "capability_version": 1,
    "media_type": "image",
    "model": "minimax-h3-image-highspeed",
    "status": "succeeded",
    "stage": "succeeded",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": {
      "media": [
        {
          "type": "image",
          "url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.png",
          "mime_type": "image/png"
        }
      ],
      "r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.png"
    },
    "usage": {
      "credits_reserved": 0.026621,
      "credits_settled": 0.026621,
      "credits_refunded": 0,
      "credits_charged": 0.026621
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Поля результата

Задача, завершившаяся ошибкой

Если задача завершилась ошибкой, GET /v1/tasks/{task_id} всё равно возвращает HTTP 200: сведения об ошибке находятся в теле ответа. Зарезервированная сумма возвращается полностью, поэтому списания нет.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "image",
    "capability_id": "minimax-h3-image-highspeed",
    "capability_version": 1,
    "media_type": "image",
    "model": "minimax-h3-image-highspeed",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 0.026621,
      "credits_settled": 0,
      "credits_refunded": 0.026621,
      "credits_charged": 0
    },
    "retryable": true,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": "processing_failed",
    "error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
  }
}

Полный пример

Создайте задачу, дождитесь её завершения с интервалом опроса, указанным сервером, и выведите ссылки на результаты. Задайте BEATAPI_API_KEY в переменной окружения и установите requests.

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
    # One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(3):
        response = requests.post(f"{API}/v1/images/tasks", headers=headers, json=body, timeout=60)
        if response.status_code in (429, 503) and attempt < 2:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        break
    try:
        payload = response.json()
    except ValueError:  # an edge error page is not JSON
        response.raise_for_status()
        raise
    if not response.ok:
        error = payload["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
    return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        if response.status_code == 429 or response.status_code >= 500:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        response.raise_for_status()
        task = response.json()["data"]
        if task["status"] in ("succeeded", "failed"):
            return task
        time.sleep(task.get("poll_after_seconds", 5))
    raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
  "model": "minimax-h3-image-highspeed",
  "prompt": "A minimalist product photo of a glass water bottle on wet black stone, soft rim light, shallow depth of field",
  "aspect_ratio": "3:2",
  "resolution": "2K"
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
    raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
    print(item["url"])

Оплата

• Оплата по токенам по ценам за 1 млн токенов из таблицы ниже: ввод текста (промпт, включая улучшение промпта MiniMax), ввод изображений (референсы в images) и вывод изображения. Токены считает модель; число токенов меняют resolution или size, промпт и референсы.
• Цены за изображение — оценки для одного рендера каждого resolution без референсов при 3 000 текстовых токенов и выходных токенах из таблицы выше. 1K и 2K тратят одинаковое число выходных токенов, поэтому оценка у них одна.
• При создании задачи оценка для её класса резервируется с вашего баланса и с квоты ключа, если она есть. При успешном завершении списание уточняется по токенам, которые рендер реально потратил, поэтому итоговый data.usage может отличаться от резерва. Запрос, отклонённый до создания задачи, ничего не стоит.
• Неудавшаяся задача возвращается полностью.

Текущие базовые цены совпадают с указанными на странице цен. Если для аккаунта согласована скидка, стоимость будет ниже. Фактически списанная сумма всегда указана в data.usage задачи.

Частые ошибки

Краткий справочник HTTP-ошибок

Ошибки до создания задачи возвращаются с HTTP-статусом, отличным от 2xx, без списания средств. Обрабатывайте error.code или error.retryable; причина указана в message. Полный список и правила повторов приведены в разделе ошибок.

{
  "error": {
    "code": "bad_request",
    "message": "\"prompt\" is required",
    "retryable": false,
    "request_id": "req_5f0c2a9e4b7d4e31"
  }
}