Blogue

Tutorial

Como usar o minimax-h3-image de geração de imagem a partir de texto via API HiAPI: curl e Python

Nov 13, 2026
Imagem de capa em estilo de trama plana: padrão de quadrados entrelaçados com fitas largas de tecido em marrom-escuro e cor de aveia, pontuado por alguns fios de trama em tom de latão.
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-image e sua capacidade text-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 curl para a primeira requisição e Python 3.9+ com requests para 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.
  • model e task descrevem 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 dict simples. 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 None silenciosos.

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 →

Comece a criar com artefactos de IA persistentes

Obtenha a sua chave de API e chame modelos de imagem, vídeo e áudio através de uma única API baseada em tasks.

Ler a documentação da API