API MiniMax H3-Image: como gerar e editar imagens

A API do MiniMax H3-Image gera e edita imagens por meio de dois endpoints REST: POST /v1/images/generations para texto-para-imagem e POST /v1/images/edits para edição com 1 a 16 imagens de referência. Você envia uma chave Bearer, o ID do modelo MiniMax-H3-Image (ou MiniMax-H3-Image-Highspeed), um prompt e um tamanho, e recebe de volta URLs de imagem ou dados base64. Ela fica na mesma plataforma de desenvolvedores da MiniMax que a API do MiniMax M3. A saída chega a cerca de 16 megapixels sem precisar de um upscaler.

Abaixo: a chave, os campos que importam, edição, preços com o desconto de lançamento e um teste executado por agente com o Apidog CLI. Não conhece o modelo? Comece por o que é o MiniMax H3-Image.

O que é a API do MiniMax H3-Image?

A API do MiniMax H3-Image é o endpoint hospedado da MiniMax para seu modelo H3-Image de pesos abertos, que lida tanto com texto-para-imagem quanto com edição de imagens com múltiplas referências em um único checkpoint. Ele é servido em https://api.minimax.io, aceita requisições JSON e é compatível com as chamadas images.generate e images.edit do SDK da OpenAI, de modo que a maior parte do código de imagem existente precisa apenas de uma nova URL base e de um novo nome de modelo.

Os pesos também são públicos: o model card no Hugging Face lista um transformer de difusão de 33,1 bilhões de parâmetros sob a licença MiniMax-H3-Image Community License. A auto-hospedagem exige cerca de 69 GB para o checkpoint mais um codificador de texto de 66,7 GB, então a API é o caminho prático para a maioria das equipes.

O lado hospedado, segundo a referência da API da MiniMax em 11/11/2026:

Obtenha sua chave de API da MiniMax

1. Faça login na plataforma de desenvolvedores da MiniMax.
2. Abra Account Management, depois API Keys, e crie uma chave.
3. Adicione saldo. Uma requisição sem fundos falha com HTTP 402 e código de erro 1008 (saldo insuficiente).
4. Exporte a chave para que seu código e seu agente a leiam do ambiente, nunca de um arquivo que você faz commit:

export MINIMAX_API_KEY="your-key-here"

Cada chamada a envia como Authorization: Bearer $MINIMAX_API_KEY.

Sua primeira requisição de texto-para-imagem

A menor chamada útil precisa de model, prompt e de um tamanho ou de um nível 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"
  }'

Com o SDK Python da OpenAI, aponte base_url para a MiniMax e desative as retentativas:

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

A linha max_retries=0 importa. O endpoint não é idempotente: o servidor conclui e cobra pelo trabalho mesmo se o seu cliente atingir o timeout, então uma retentativa automática cobra duas vezes. Em vez disso, defina um timeout de 600 segundos.

Parâmetros de requisição que importam

Você controla o tamanho da saída de uma de duas formas, e não pode misturá-las.

Pixels exatos. Defina size como LARGURAxALTURA, por exemplo 4096x4096. A área total deve estar entre 655.360 e 20.000.000 pixels e a proporção entre 1:3 e 3:1. Não envie aspect_ratio ou area nesse modo, nem mesmo como auto, ou você receberá um 400.

Nível mais proporção. Deixe size como auto e defina area (1K, 2K ou 4K, padrão 4K) e aspect_ratio (qualquer X:Y de 1:3 a 3:1). O servidor calcula os pixels; 2K em 16:9 retorna 2720 x 1536.

Os outros campos:

Duas regras pegam as pessoas de surpresa. Primeiro, se você desativar o aprimoramento de prompt, deve fornecer um size exato ou um aspect_ratio explícito; auto retorna um 400. Segundo, b64_json limita a área total da saída: 20.000.000 de pixels para PNG (uma imagem de qualquer tamanho) e 80.000.000 para JPEG ou WebP (quatro imagens 4K ou dez imagens 2K). Para lotes maiores, use URLs.

O model card diz que o H3-Image funciona melhor por volta de 16 MP: 4096x4096 (1:1), 5472x3072 (16:9) ou 6272x2688 (21:9).

Edite imagens com até 16 referências

A edição usa os mesmos campos mais um array images. Faça referência às entradas pela posição no prompt (“image 1”, “image 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"])

O endpoint também aceita multipart/form-data, que é o que o images.edit do SDK da OpenAI envia quando você faz upload de arquivos. Limites da referência de edits:

• 1 a 16 imagens em JPG, PNG, WebP, HEIC ou HEIF
• Cada lado entre 128 e 8.192 pixels, proporção entre maior e menor lado de no máximo 4:1
• Corpo total da requisição de até 64 MiB; base64 adiciona cerca de um terço, então passe a usar URLs públicas para entradas grandes

Leia a resposta e trate os erros

Uma chamada bem-sucedida retorna um item data por imagem solicitada, na ordem:

{
  "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..."
}

Três hábitos mantêm sua integração confiável:

1. Verifique cada item em busca de error. O status HTTP é 200 se pelo menos uma imagem tiver sucesso, então um 200 não significa que todas as n imagens voltaram. Se todas as imagens falharem, você recebe 402, 422 ou 500.
2. Baixe as URLs imediatamente. A MiniMax diz que a URL não tem garantia de permanecer disponível, então copie o arquivo para o seu próprio armazenamento.
3. Registre o request_id. É o ID de rastreamento que o suporte pede.

Limites de taxa retornam 429. O código 1002 significa que você excedeu o limite de imagens por minuto, e cada requisição conta como n imagens, então um lote de 10 consome 10 da sua cota de uma vez.

Preços do MiniMax H3-Image e o desconto de lançamento

O faturamento é por token, e você só paga pelas imagens que têm sucesso. Da página de preços da MiniMax, consultada em 11/11/2026:

A MiniMax também publica custos de exemplo por imagem para o modelo padrão:

O Highspeed custa aproximadamente 1,6 a 2 vezes mais por imagem ($0.13001 para 4K, $0.06501 com desconto). O comprimento do prompt altera o lado de entrada, então trate esses valores como estimativas.

Oferta de lançamento: até 17 de novembro de 2026 às 16:00 UTC, a MiniMax dá 50% de desconto no custo total da requisição para ambos os modelos quando a imagem entregue tiver pelo menos 16.600.000 pixels. Uma imagem de 4096x4096 (16.777.216 pixels) se qualifica; uma imagem 2K não. Prefere rotas gratuitas? Veja como usar o MiniMax H3-Image de graça.

Deixe seu agente de código testá-la com o Apidog CLI

APIs de imagem falham silenciosamente: um 200 com metade das imagens faltando, uma regra de tamanho que você esqueceu. Em vez de conferir respostas manualmente, deixe seu agente de código (Claude Code, Codex, Cursor) construir um teste reproduzível com o Apidog CLI.

Configure uma vez:

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

Depois dê ao seu agente um único 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.

O agente lê o schema de cada payload, valida seu JSON, cria os recursos e executa o 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

O --env-var passa sua chave em tempo de execução, então ela nunca acaba em um arquivo salvo. O reporter cli imprime cada assertion como passou ou falhou; o json gera um relatório que seu agente lê de volta. Mantenha o teste em 1K: cada execução é uma geração real e cobrada. A mesma linha roda em CI com -r junit (veja o guia de CI/CD do Apidog CLI e o Apidog CLI no Claude Code). O plano gratuito da Apidog cobre até 4 usuários.

Standard ou Highspeed: qual ID de modelo?

Ambos os IDs aceitam parâmetros idênticos, então trocar é mudar uma string. Use MiniMax-H3-Image para ativos finais e lotes sensíveis a custo, e MiniMax-H3-Image-Highspeed para prévias interativas, em que a latência vale mais que o preço. A referência da API não traz número de latência, então meça com seus próprios prompts. Avaliando alternativas? Leia MiniMax H3-Image vs Nano Banana 2.1, o guia da API do Nano Banana 2.1 ou o guia da API do GPT Image 2.6.

FAQ

Qual é o ID do modelo MiniMax H3-Image? Use MiniMax-H3-Image para o modelo padrão ou MiniMax-H3-Image-Highspeed para a versão mais rápida e cara. Ambos funcionam em /v1/images/generations e /v1/images/edits com os mesmos parâmetros.

A API do MiniMax H3-Image funciona com o SDK da OpenAI? Sim. Defina base_url="https://api.minimax.io/v1" e chame images.generate ou images.edit. Defina max_retries=0, porque retentativas criam novas gerações cobradas.

Quantas imagens de referência posso usar para edição? De 1 a 16 por requisição, cada uma com 128 a 8.192 pixels por lado, com todo o corpo da requisição abaixo de 64 MiB.

Quanto custa uma imagem do MiniMax H3-Image? Os exemplos da MiniMax colocam uma chamada padrão de texto-para-imagem em cerca de $0.022 para 1K e $0.069 para 4K, com o 4K reduzido pela metade para cerca de $0.034 até 17 de novembro de 2026, 16:00 UTC.

Por que recebi um 200 mas menos imagens do que pedi? Sucesso parcial retorna 200. Os itens que falharam, incluindo os bloqueados pela verificação de segurança, trazem um objeto error em vez de uma url, e você não é cobrado por eles.