Tutorial
Como usar o minimax-h3-image de geração de imagem a partir de texto via API HiAPI: curl e Python
Nesta página
O que este tutorial cobre e o que você precisa preparar antes
Este tutorial trata de uma única coisa concreta: enviar um prompt de geração de imagem ao modelo de geração de imagem a partir de texto minimax-h3-image através da API HiAPI, primeiro com uma requisição curl e depois com uma pequena função Python que você pode colocar em uma aplicação. O conteúdo abrange a estrutura da requisição, como interpretar a resposta, como os erros se manifestam e o que precisa ser reforçado antes de colocar em produção.
Ele deliberadamente não aborda teoria de engenharia de prompt, pós-processamento de imagens ou construção de UI. O objetivo é mais focado: ao terminar a leitura, você deve ter uma requisição confiável e saber exatamente por que a última falhou.
Pré-requisitos
- Uma conta HiAPI. Antes de tudo, você precisa de um projeto e de uma chave de API — toda requisição abaixo exige autenticação.
- Guarde a chave em local seguro. Coloque-a em uma variável de ambiente (
HIAPI_API_KEY), não em um arquivo de código-fonte, para que o mesmo código funcione localmente e em CI. - O identificador do modelo. Este tutorial usa
minimax-h3-imagee sua capacidadetext-to-image. Trate o nome do modelo e o caminho da tarefa como valores de configuração no código, e não como strings mágicas espalhadas por todo lado. - Ferramentas. Use
curlpara a primeira requisição e Python 3.9+ comrequestspara a segunda. Nenhuma outra biblioteca é necessária. - Uma forma de visualizar a imagem. Você lerá um payload de resposta que contém dados da imagem ou uma referência a ela — inspecione manualmente os campos da resposta uma vez antes de assumir qualquer schema.
Um hábito para cultivar desde já
Gere a primeira requisição bem-sucedida fora do código da sua aplicação. Um comando curl funcional é a fonte da verdade: sempre que a versão em Python se comportar de forma estranha, compare com ele. Se a chamada curl funcionar e a Python não, o problema está no seu cliente, não no modelo ou na rede.
Montando uma requisição funcional de geração de imagem a partir de texto com curl
Comece com a menor requisição possível e depois adicione uma configuração de cada vez. A requisição de geração é composta de três partes: o endpoint, o cabeçalho de autenticação e o corpo JSON.
A requisição
curl -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-h3-image",
"task": "text-to-image",
"prompt": "uma tigela de cerâmica sobre uma toalha de linho, luz suave de janela ao norte, lente 50mm, profundidade de campo rasa",
"size": "1024x1024",
"n": 1
}'
Há três pontos a observar nesse comando:
- A chave é enviada como bearer token no cabeçalho
Authorization. Nunca a coloque na URL ou no corpo da requisição, caso contrário ela irá parar em logs e no histórico do shell. modeletaskdescrevem o que você quer — a família de modelos e a capacidade. Escreva ambos explicitamente mesmo que existam valores padrão; requisições explícitas resistem melhor ao tempo.prompté uma string comum. Todo o resto (size,n) são configurações da imagem, não descrições do sujeito.
Interpretando a resposta
Formate a saída para conseguir realmente lê-la:
curl -s -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json | python -m json.tool
Durante a iteração, coloque o corpo da requisição em um arquivo (request.json) — assim o prompt permanece legível e alterar o prompt vira um diff de uma linha, em vez de um jogo de adivinhação de aspas.
Inspecione o payload antes de escrever o parser. Observe se a imagem é retornada inline ou como URL, quais campos carregam o identificador da imagem e qualquer prompt modificado, e se a resposta contém metadados de uso. Anote esses nomes de campo; seu cliente Python dependerá deles.
Confirmando o fluxo de ponta a ponta
Salve a imagem retornada, abra-a e verifique se você recebeu o que pediu. Uma resposta 200 com um corpo JSON plausível não equivale a uma imagem correta — é neste ponto que problemas de prompt e parâmetros são descobertos de forma mais barata.
Traduzindo a requisição para Python
Agora porte exatamente a mesma requisição. Mantenha tudo simples: uma função, timeouts explícitos e, por enquanto, sem retentativas ocultas.
import os
import requests
HIAPI_API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/images/generations"
def generate_image(prompt: str, size: str = "1024x1024", n: int = 1) -> dict:
"""Gera uma imagem usando minimax-h3-image via HiAPI."""
payload = {
"model": "minimax-h3-image",
"task": "text-to-image",
"prompt": prompt,
"size": size,
"n": n,
}
response = requests.post(
ENDPOINT,
headers={
"Authorization": f"Bearer {HIAPI_API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=(5, 120), # timeout de conexão, timeout de leitura
)
response.raise_for_status()
return response.json()
Há quatro escolhas deliberadas nessa função:
- Timeout em tupla. O timeout de conexão é curto, porque uma conexão lenta indica problema; o timeout de leitura é mais folgado, porque a geração de imagem naturalmente leva tempo. Um único valor de timeout força você a ser ruim em apenas um dos modos de falha.
json=payload. Deixe a biblioteca serializar o corpo. Strings JSON montadas à mão são um terreno fértil para bugs de aspas.raise_for_status()antes de fazer o parse. A verificação de status não é opcional — tratar um corpo de resposta de erro como sucesso é o tipo de bug mais confuso nesse tipo de integração.- Retornar um
dictsimples. Você pode decorá-lo com modelos tipados depois; primeiro garanta que sabe quais campos a resposta realmente contém.
Isolando a busca da chave
Se a variável estiver ausente, os.environ["HIAPI_API_KEY"] lança uma exceção imediatamente. Isso é intencional: falhe na inicialização, não na primeira requisição do usuário. Em uma base de código maior, resolva a chave uma vez durante o carregamento da configuração e então passe um cliente já configurado, em vez de ler a variável de ambiente no ponto de chamada.
Executando a integração
if __name__ == "__main__":
result = generate_image("uma pipa vermelha sobre uma praia molhada na maré baixa, luz nublada")
print(result)
Execute e compare com a saída do curl. A estrutura do payload deve ser consistente. Se não for, você encontrou uma diferença que vale a pena esclarecer antes de continuar construindo.
Tratando erros em vez de adivinhar
O bug de integração mais comum é tentar novamente um erro que nunca terá sucesso. Divida as falhas em três categorias e trate-as de forma diferente.
Falhas de autenticação e autorização
Normalmente se manifestam como 401 ou 403. As causas incluem: cabeçalho ausente, prefixo Bearer mal formatado, chave revogada ou mal configurada, ou o projeto não ter acesso ao modelo. Elas não são retentáveis. Tentar novamente só desperdiça tempo e polui os logs com a mesma falha. Corrija as credenciais e siga em frente.
Falhas de validação da requisição
Normalmente são respostas de nível 400: valores desconhecidos de model ou task, size não suportado pelo modelo, n fora do intervalo, prompt vazio, JSON mal formatado. Elas também não são retentáveis — a mesma requisição falhará da mesma forma. O trabalho útil é expor a mensagem de erro como está ao desenvolvedor que escreveu a requisição, em vez de engoli-la em uma exceção genérica.
Falhas transitórias de servidor e rede
Respostas 429 e 5xx, além de reset de conexão e timeout de leitura, são a categoria realmente retentável. Trate-as com backoff exponencial limitado e jitter:
import time, random, requests
def post_with_retry(session, url, payload, max_attempts=4):
for attempt in range(max_attempts):
try:
r = session.post(url, json=payload, timeout=(5, 120))
if r.status_code in (429, 500, 502, 503, 504):
raise requests.HTTPError(f"erro transitório {r.status_code}", response=r)
r.raise_for_status()
return r.json()
except (requests.ConnectionError, requests.Timeout, requests.HTTPError) as exc:
if attempt == max_attempts - 1:
raise
time.sleep(min(2 ** attempt + random.random(), 30))
Dois avisos. Primeiro, um HTTPError disparado por um 4xx que não seja 429 deve ser propagado imediatamente — não deixe a cláusula except absorver falhas de validação. Segundo, siga qualquer orientação de retentativa presente na resposta, em vez de inventar seu próprio atraso.
A retentativa aqui não é idempotente
Cada geração retentada é uma nova geração cobrada. Se a requisição der timeout, a imagem ainda pode ter sido gerada e cobrada. Mantenha o número de retentativas pequeno, registre o número de tentativas junto com os metadados da requisição nos logs e prefira expor uma falha clara a gerar silenciosamente a mesma imagem quatro vezes.
Higiene prática de prompts e parâmetros
O sentido desses hábitos é a comparabilidade: quando você altera uma coisa, deve conseguir determinar se a mudança na saída foi causada por ela.
Escreva prompts que especifiquem o conteúdo da cena
Descreva na ordem: sujeito, cenário, iluminação, composição. Substantivos concretos e termos fotográficos (como "luz suave de janela ao norte", "profundidade de campo rasa") carregam mais sinal do que uma pilha de adjetivos estéticos. Evite usar muitos prompts negativos; descreva o que deve aparecer.
Mude uma variável por vez
Mantenha um pequeno arquivo de prompts por projeto e edite-o entre execuções, em vez de reescrevê-lo do zero. Se uma execução decepcionar, mude o prompt ou as configurações — não ambos. Caso contrário, você não saberá qual mudança fez efeito.
Trate as configurações como um contrato explícito
size e n afetam tanto a saída quanto o custo. Fixe-os em um objeto de configuração, em vez de passar literais por vários pontos de chamada, para que alterar a proporção para o recurso inteiro seja uma única edição. Se precisar de várias imagens para comparar, solicite-as em uma única chamada, e não em várias — menos idas e voltas, logs mais legíveis.
Armazene os prompts junto com as saídas
Persista a string exata do prompt, as configurações e o identificador do modelo ao lado de cada imagem gerada. Um prompt que não pode ser reproduzido é uma imagem que não pode ser regenerada, depurada ou melhorada. Esse único hábito economiza mais tempo do que qualquer truque de prompt.
Defina uma semente para comparação
O mesmo prompt pode produzir imagens diferentes entre execuções. Ao avaliar uma mudança, compare resultados agregados — várias imagens por configuração — em vez de confiar em uma única amostra sortuda ou azarada.
Versione os prompts
Trate o texto do prompt como código: mantenha-o em arquivos, revise alterações e registre qual versão do prompt gerou qual ativo. Isso torna "por que a imagem piorou na terça-feira passada?" uma pergunta respondível.
Checklist de produção antes do lançamento
Uma requisição funcional é só a parte fácil. As verificações abaixo separam uma demonstração de uma integração.
- Defina timeouts em toda chamada. Configure explicitamente timeouts de conexão e de leitura, nunca use os padrões. Um endpoint de geração sem timeout de leitura acabará travando um worker.
- Retentativas limitadas, apenas para erros retentáveis. Limite o número de tentativas, adicione jitter e garanta que falhas de validação e autenticação ignorem completamente o caminho de retentativa.
- Gestão de chaves. Leia a chave do ambiente ou de um cofre de segredos, nunca do código-fonte. Faça rotação sem alterar o código.
- Logs estruturados. Registre o identificador do modelo, o prompt (ou seu hash mais uma referência), as configurações, o status HTTP, o número de tentativas e qualquer identificador de requisição presente na resposta. Sem isso, problemas de imagem não serão reproduzíveis.
- Visibilidade de custos. A geração é cobrada pela saída, então o uso depende de quantas imagens você solicita e com que frequência retenta. Defina antecipadamente se as requisições serão por usuário, por tarefa ou em segundo plano e acompanhe o volume de acordo — consulte o painel de preços ao vivo no site para obter as tarifas atuais, em vez de fixar suposições no código.
- Defina o comportamento em caso de falha. Decida o que o usuário verá quando a geração falhar após a última tentativa: um estado de erro, um placeholder ou uma nova tentativa na fila. Um fallback indefinido vira uma experiência de usuário indefinida.
- Fixe o schema do payload. Armazene e valide os campos de resposta dos quais você depende, para que mudanças no payload apareçam como erros explícitos, e não como
Nonesilenciosos.
Etapa final de verificação
Execute o comando curl, a função Python e uma requisição deliberadamente inválida (primeiro com chave errada, depois com parâmetros errados) e confirme que cada uma produz a falha esperada. Só essa última etapa mostra que o tratamento de erros é real, e não decorativo.
Depois que a requisição estiver autenticada, portada, com retentativas razoáveis e registrada em logs, a integração pode ficar atrás do restante da aplicação.
Artigos relacionados
Ver todos os artigos →-
Tutorial
Guia prático do gpt-6.2-sol: 5 usos de alto valor de modelos de texto nos negócios
-
Tutorial
Guia prático do gpt-6.2-astra: pontos de integração e implementação em 5 cenários de texto de alto valor
Uma lista de verificação do ponto de vista do desenvolvedor, da seleção de cenários à implementação em engenharia
-
Tutorial
Cenários práticos do Tripo H3.1: 5 usos de alto valor e pontos de implementação
De texto para 3D à reconstrução multivisão: escolha o modo e os parâmetros certos para cada cenário de negócio