Guia de introdução ao MiniMax H3 Image: geração de imagem a partir de texto, edição com múltiplas imagens de referência, parâmetros e preços

O MiniMax H3 Image é um modelo de imagem da MiniMax e possui dois IDs de chamada no HiAPI: minimax-h3-image/text-to-image (geração de imagem a partir de texto) e minimax-h3-image/image-to-image (geração ou edição com 1–16 imagens de referência). Este artigo explica como escolher entre os dois IDs, como preencher os parâmetros, como o custo é calculado e os detalhes a observar na chamada.

Como escolher entre os dois IDs

• Apenas descrição em texto: use text-to-image; o único campo obrigatório é prompt (até 5000 caracteres).
• Você tem imagens para usar como referência: use image-to-image; o campo adicional obrigatório é image_urls, com 1–16 imagens. É possível trocar o cenário de uma foto de produto, redesenhar uma foto no estilo de ilustração ou pintura a óleo e também fornecer várias imagens de referência ao mesmo tempo.
• Os dois IDs têm o mesmo preço por imagem; no modo imagem-para-imagem há um acréscimo por imagem de referência, conforme a seção "Preços" abaixo.

Parâmetros

• resolution: 1K / 2K / 4K; padrão 2K. Por exemplo, 2K em 1:1 gera 2048×2048; 1K em 9:16 gera 768×1360; 4K em 16:9 gera 5472×3072.
• aspect_ratio: auto, 1:1, 5:4, 4:5, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16, 21:9. Na geração a partir de texto, o padrão é 1:1; na geração a partir de imagem, o padrão é auto, e o modelo escolhe a proporção com base no prompt e nas imagens de referência, podendo não coincidir com a primeira imagem de referência — se quiser um formato fixo, informe a proporção explicitamente.
• output_format: jpeg (padrão) ou png. O PNG é bem maior; um PNG em 4K pode chegar a 30MB. Se não houver necessidade específica, use jpeg.
• seed: opcional, de 0 a 2147483647; fixe-o quando quiser reproduzir a mesma imagem.
• Cada requisição gera 1 imagem; não há suporte a largura e altura personalizadas, fundo transparente nem repintura local com máscara.

Exemplo de chamada

Envio da tarefa:

curl https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-image/image-to-image",
    "input": {
      "prompt": "Place the serum bottle on a pale stone pedestal, soft side light, clean e-commerce product shot",
      "image_urls": ["https://example.com/bottle.png"],
      "resolution": "2K",
      "aspect_ratio": "3:4"
    }
  }'

Depois de receber data.taskId, consulte repetidamente GET https://api.hiapi.ai/v1/tasks/<taskId>. Quando status se tornar success, o endereço da imagem estará em data.output[0].url. Imagens em 2K normalmente ficam prontas em 30–40 segundos. O link do resultado tem prazo de validade (campo expireAt); se precisar guardar por longo prazo, baixe e armazene por conta própria.

Preços

• 1K e 2K: $0.0129 por imagem.
• 4K: $0.0393 por imagem.
• No modo imagem-para-imagem, cada imagem de referência acrescenta $0.0036. Por exemplo, 2K com 3 imagens de referência: 0.0129 + 3 × 0.0036 = $0.0237.
• Só são cobradas tarefas que geram imagem com sucesso; tarefas com falha são reembolsadas integralmente.

Como escrever prompts

• Escreva com clareza na ordem "sujeito + cenário + iluminação + estilo + composição".
• No modo imagem-para-imagem, deixe claro o que deve ser preservado e o que deve ser alterado, por exemplo: "mantenha os traços faciais e a pose da pessoa, troque o fundo por blocos de cinza quente e aplique pinceladas de pintura a óleo no conjunto".
• Teste a composição primeiro em 1K ou 2K e, após definir o resultado, gere em 4K: o preço unitário em 4K é cerca de 3 vezes o de 2K.