API de MiniMax H3-Image: Cómo generar y editar imágenes

La API de MiniMax H3-Image genera y edita imágenes a través de dos endpoints REST: POST /v1/images/generations para texto a imagen y POST /v1/images/edits para editar con entre 1 y 16 imágenes de referencia. Envías una clave Bearer, el ID del modelo MiniMax-H3-Image (o MiniMax-H3-Image-Highspeed), un prompt y un tamaño, y recibes URLs de imágenes o datos en base64. Se aloja en la misma plataforma de desarrolladores de MiniMax que la API de MiniMax M3. La salida alcanza unos 16 megapíxeles sin necesidad de un upscaler.

A continuación: la clave, los campos importantes, la edición, los precios con el descuento de lanzamiento y una prueba automatizada por un agente con Apidog CLI. ¿No conoces el modelo? Empieza por qué es MiniMax H3-Image.

¿Qué es la API de MiniMax H3-Image?

La API de MiniMax H3-Image es el endpoint alojado de MiniMax para su modelo H3-Image de pesos abiertos, que gestiona tanto texto a imagen como edición con múltiples referencias en un solo checkpoint. Se sirve en https://api.minimax.io, acepta solicitudes JSON y es compatible con las llamadas images.generate e images.edit del SDK de OpenAI, por lo que la mayoría del código de imágenes existente solo necesita una nueva URL base y el nombre del modelo.

Los pesos también son públicos: la ficha del modelo en Hugging Face lista un transformador de difusión de 33,1 mil millones de parámetros bajo la licencia comunitaria MiniMax-H3-Image. El autoalojamiento requiere unos 69 GB para el checkpoint más un codificador de texto de 66,7 GB, así que la API es la vía práctica para la mayoría de los equipos.

El lado alojado, según la referencia de la API de MiniMax del 11/11/2026:

Consigue tu clave de API de MiniMax

1. Inicia sesión en la plataforma de desarrolladores de MiniMax.
2. Abre Account Management, luego API Keys, y crea una clave.
3. Añade saldo. Una solicitud sin fondos falla con HTTP 402 y el código de error 1008 (saldo insuficiente).
4. Exporta la clave para que tu código y tu agente la lean del entorno, nunca de un archivo que subas al repositorio:

export MINIMAX_API_KEY="your-key-here"

Cada llamada la envía como Authorization: Bearer $MINIMAX_API_KEY.

Tu primera solicitud de texto a imagen

La llamada más pequeña útil necesita model, prompt y o bien un tamaño o bien un nivel de área:

curl https://api.minimax.io/v1/images/generations \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 600 \
  -d '{
    "model": "MiniMax-H3-Image",
    "prompt": "An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture",
    "aspect_ratio": "16:9",
    "area": "2K",
    "n": 1,
    "response_format": "url"
  }'

Con el SDK de Python de OpenAI, apunta base_url a MiniMax y desactiva los reintentos:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.minimax.io/v1",
    api_key=os.environ["MINIMAX_API_KEY"],
    timeout=600,
    max_retries=0,
)

result = client.images.generate(
    model="MiniMax-H3-Image",
    prompt="An orange cat lying on a windowsill basking in the sun, warm afternoon light",
    size="2720x1536",
    response_format="url",
)
for item in result.data:
    print(item.url)  # None for an image that failed

La línea max_retries=0 es importante. El endpoint no es idempotente: el servidor termina y cobra por un trabajo incluso si tu cliente agota el tiempo de espera, así que un reintento automático factura dos veces. En su lugar, establece un tiempo de espera de 600 segundos.

Parámetros de solicitud que importan

Controlas el tamaño de la salida de una de dos maneras, y no puedes mezclarlas.

Píxeles exactos. Establece size como WIDTHxHEIGHT, por ejemplo 4096x4096. El área total debe estar entre 655.360 y 20.000.000 píxeles, y la relación de aspecto entre 1:3 y 3:1. No envíes aspect_ratio ni area en este modo, ni siquiera como auto, o recibirás un 400.

Nivel más relación. Deja size como auto y establece area (1K, 2K o 4K, por defecto 4K) y aspect_ratio (cualquier X:Y de 1:3 a 3:1). El servidor calcula los píxeles; 2K con 16:9 devuelve 2720 x 1536.

Los demás campos:

Dos reglas confunden a mucha gente. Primera: si desactivas la mejora del prompt, debes indicar un size exacto o un aspect_ratio explícito; auto devuelve un 400. Segunda: b64_json limita el área total de salida: 20.000.000 de píxeles para PNG (una imagen de cualquier tamaño) y 80.000.000 para JPEG o WebP (cuatro imágenes 4K o diez imágenes 2K). Para lotes más grandes, usa URLs.

Según la ficha del modelo, H3-Image funciona mejor alrededor de 16 MP: 4096x4096 (1:1), 5472x3072 (16:9) o 6272x2688 (21:9).

Edita imágenes con hasta 16 referencias

La edición usa los mismos campos más un array images. Referénciate a las entradas por su posición en el prompt ("imagen 1", "imagen 2"):

import os, requests

resp = requests.post(
    "https://api.minimax.io/v1/images/edits",
    headers={"Authorization": f"Bearer {os.environ['MINIMAX_API_KEY']}"},
    json={
        "model": "MiniMax-H3-Image",
        "prompt": "Replace the cat in image 1 with the Shiba Inu in image 2, keep the background unchanged",
        "images": [
            {"image_url": "https://example.com/cat.jpg"},
            {"image_url": "https://example.com/dog.png"},
        ],
        "size": "auto",
        "response_format": "url",
    },
    timeout=600,
)
resp.raise_for_status()
print(resp.json()["data"])

El endpoint también acepta multipart/form-data, que es lo que envía el images.edit del SDK de OpenAI cuando subes archivos. Límites según la referencia de ediciones:

• De 1 a 16 imágenes en JPG, PNG, WebP, HEIC o HEIF
• Cada lado entre 128 y 8.192 píxeles, con una relación largo-corto de no más de 4:1
• Cuerpo de la solicitud de hasta 64 MiB en total; base64 añade alrededor de un tercio, así que usa URLs públicas para entradas grandes

Lee la respuesta y gestiona los errores

Una llamada exitosa devuelve un elemento data por cada imagen solicitada, en orden:

{
  "data": [
    {"url": "https://.../output-0.jpg", "size": "2720x1536", "revised_prompt": "Warm afternoon light streams through..."},
    {"error": {"code": "1027", "message": "output image failed content safety check"}}
  ],
  "output_format": "jpeg",
  "usage": {"generated_images": 1, "input_tokens": 3174, "output_tokens": 4080, "total_tokens": 7254},
  "request_id": "0217..."
}

Tres hábitos mantienen tu integración honesta:

1. Comprueba si cada elemento tiene error. El estado HTTP es 200 si al menos una imagen tiene éxito, así que un 200 no significa que hayan vuelto las n imágenes. Si todas fallan, recibirás 402, 422 o 500 en su lugar.
2. Descarga las URLs de inmediato. MiniMax indica que la URL no está garantizada a seguir disponible, así que copia el archivo a tu propio almacenamiento.
3. Registra request_id. Es el ID de trazabilidad que soporte te pedirá.

Los límites de tarifa devuelven 429. El código 1002 significa que superaste el límite de imágenes por minuto, y cada solicitud cuenta como n imágenes, así que un lote de 10 consume 10 de tu cuota de golpe.

Precios de MiniMax H3-Image y descuento de lanzamiento

La facturación es por token, y solo pagas por las imágenes que tienen éxito. Según la página de precios de MiniMax, consultada el 11/11/2026:

MiniMax también publica costes de ejemplo por imagen para el modelo estándar:

Highspeed cuesta aproximadamente entre 1,6 y 2 veces más por imagen ($0.13001 por 4K, $0.06501 con descuento). La longitud del prompt afecta al lado de entrada, así que considera estas cifras como estimaciones.

Oferta de lanzamiento: hasta el 17 de noviembre de 2026 a las 16:00 UTC, MiniMax aplica un 50 % de descuento en el coste total de la solicitud para ambos modelos cuando la imagen entregada tiene al menos 16.600.000 píxeles. Una imagen de 4096x4096 (16.777.216 píxeles) califica; una imagen 2K no. ¿Buscas alternativas gratuitas? Consulta cómo usar MiniMax H3-Image gratis.

Deja que tu agente de programación lo pruebe con Apidog CLI

Las APIs de imágenes fallan en silencio: un 200 con la mitad de las imágenes ausentes, una regla de tamaño que olvidaste. Deja que tu agente de programación (Claude Code, Codex, Cursor) construya una prueba repetible con Apidog CLI en lugar de revisar las respuestas a mano.

Configura una vez:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_APIDOG_TOKEN>
apidog skill install

Luego dale a tu agente un solo prompt:

In Apidog project <projectId>, create an environment "MiniMax Global" with base URL
https://api.minimax.io. Add the endpoint POST /v1/images/generations from the MiniMax
H3-Image API reference, with Bearer auth from the {{MINIMAX_API_KEY}} variable.
Create a test case that sends model MiniMax-H3-Image, area 1K, aspect_ratio 1:1, n 1,
and asserts HTTP 200, data[0].url exists, and no item in data has an error field.
Run it and summarize any failures.

El agente lee cada esquema de payload, valida su JSON, crea los recursos y ejecuta el caso:

apidog environment create "MiniMax Global" --project <projectId> --base-url https://api.minimax.io
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file endpoint.json
apidog endpoint create --project <projectId> --file endpoint.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> \
  --env-var "MINIMAX_API_KEY=$MINIMAX_API_KEY" -r cli,json

--env-var pasa tu clave en tiempo de ejecución, así que nunca queda guardada en un archivo. El reportero cli imprime cada aserción como superada o fallida; json escribe un informe que tu agente lee después. Mantén la prueba en 1K: cada ejecución es una generación real y facturada. La misma línea se ejecuta en CI con -r junit (consulta la guía de CI/CD de Apidog CLI y Apidog CLI en Claude Code). El plan gratuito de Apidog cubre hasta 4 usuarios.

¿Estándar o Highspeed: qué ID de modelo?

Ambos IDs aceptan parámetros idénticos, así que cambiar es cuestión de una sola cadena. Usa MiniMax-H3-Image para recursos finales y lotes sensibles al coste, y MiniMax-H3-Image-Highspeed para vistas previas interactivas donde la latencia importa más que el precio. La referencia de la API no da cifras de latencia, así que mídela con tus propios prompts. ¿Evalúas alternativas? Lee MiniMax H3-Image vs Nano Banana 2.1, la guía de la API de Nano Banana 2.1 o la guía de la API de GPT Image 2.6.

Preguntas frecuentes

¿Cuál es el ID del modelo MiniMax H3-Image? Usa MiniMax-H3-Image para el modelo estándar o MiniMax-H3-Image-Highspeed para la versión más rápida y cara. Ambos funcionan en /v1/images/generations y /v1/images/edits con los mismos parámetros.

¿Funciona la API de MiniMax H3-Image con el SDK de OpenAI? Sí. Establece base_url="https://api.minimax.io/v1" y llama a images.generate o images.edit. Configura max_retries=0, porque los reintentos crean nuevas generaciones facturadas.

¿Cuántas imágenes de referencia puedo usar para editar? De 1 a 16 por solicitud, cada una de 128 a 8.192 píxeles por lado, con todo el cuerpo de la solicitud por debajo de 64 MiB.

¿Cuánto cuesta una imagen con MiniMax H3-Image? Los ejemplos de MiniMax sitúan una llamada estándar de texto a imagen en unos $0.022 para 1K y $0.069 para 4K, con 4K a la mitad, unos $0.034, hasta el 17 de noviembre de 2026, 16:00 UTC.

¿Por qué recibí un 200 pero menos imágenes de las que pedí? El éxito parcial devuelve 200. Los elementos fallidos, incluidos los bloqueados por la verificación de seguridad, llevan un objeto error en lugar de una url, y no se te cobra por ellos.