Tutorial
Como usar grok-imagine/text-to-image via HiAPI API: guia curl e Python
Nesta página
O que grok-imagine/text-to-image oferece
grok-imagine/text-to-image é um endpoint de conversão de texto em imagem fornecido pela HiAPI: você envia um prompt e alguns parâmetros de geração em JSON por HTTP e recebe uma imagem. É todo o contrato. Sem SDK para instalar, sem inicialização de sessão, e sem necessidade de polling de tarefas em segundo plano para ver a primeira imagem.
Seu posicionamento no fluxo de trabalho do desenvolvedor:
- Prototipagem rápida. Você pode passar de uma ideia a uma imagem renderizada em um único comando de terminal, o que permite testar rapidamente conceitos de prompt.
- Pipeline de conteúdo. Como é apenas uma chamada HTTP comum, você pode chamá-lo de serviços de backend, workers de fila ou scripts de build, assim como qualquer outra API.
- Funcionalidade de produto. A geração de imagens voltada ao usuário geralmente exige tratamento previsível de requisição/resposta, erros estruturados e novas tentativas. Um endpoint sem estado atende bem a esses três pontos.
O que este endpoint não é: ele não armazena prompts para você, não gerencia uma biblioteca de imagens geradas e não substitui sua própria orquestração. A requisição é sua responsabilidade, a saída é sua responsabilidade e o destino dos bytes é sua decisão.
Este guia foca em primeiro fazer a requisição funcionar, depois torná-la confiável. Seja usando curl ou Python, o padrão é idêntico, pois ambos são a mesma requisição HTTP autenticada. Comece pelo mínimo funcional, confirme o sucesso da ida e volta e só então adicione complexidade.
Pré-requisitos e autenticação
Antes da primeira chamada, confirme que você tem:
- Uma conta HiAPI e uma chave de API. Trate a chave como segredo: carregue-a de variáveis de ambiente e nunca a codifique diretamente em scripts que possam ser commitados.
- Uma ferramenta para fazer requisições HTTP. Para o primeiro teste,
curlé suficiente. Para Python, userequestsouhttpx; ambos serão abordados adiante. - Acesso à rede ao host da API HiAPI. Se estiver atrás de um proxy corporativo, certifique-se de definir
HTTPS_PROXYpara seu shell, para que tantocurlquanto Python possam lê-lo.
A chave é passada como bearer token no cabeçalho Authorization:
export HIAPI_API_KEY="your-key-here"
Então cada requisição carrega:
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
Dois hábitos que valem a pena adquirir imediatamente:
- Nunca coloque a chave na URL. Nenhuma parte da requisição deve colocar credenciais na query string, pois elas acabam em logs e no histórico do shell.
- Use uma chave por ambiente. Chaves de desenvolvimento e produção devem ser valores diferentes, para que você possa rotacionar uma sem afetar a outra.
Se você ainda não gerou uma chave, crie uma no painel da HiAPI e armazene-a no seu gerenciador de segredos ou em um arquivo .env local fora do controle de versão. Assim que echo $HIAPI_API_KEY imprimir o valor, você estará pronto para fazer a primeira requisição.
Requisição mínima funcional em curl
A chamada útil mínima envia apenas o identificador do modelo e o prompt. Todo o resto tem valores padrão, então não se apresse em ajustar parâmetros antes de ver uma imagem retornada.
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine/text-to-image",
"prompt": "um farol em uma costa rochosa ao entardecer, mar calmo, luz suave e nublada"
}'
O papel de cada parte:
-X POSTcom corpo JSON é a forma padrão para endpoints de geração.modelseleciona explicitamentegrok-imagine/text-to-image. Fixe o nome do modelo no script, em vez de depender do padrão, para que mudanças no padrão não alterem silenciosamente sua saída.prompté a única entrada de conteúdo. No primeiro teste, mantenha-o como uma frase clara.
Uma resposta bem-sucedida retorna JSON contendo a imagem gerada, normalmente uma URL ou um payload base64, dependendo do formato de resposta solicitado. Antes de escrever qualquer código de parsing, leia a resposta com um formatador JSON. Se estiver visualizando a saída no terminal, canalizá-la por python -m json.tool torna a estrutura mais legível.
Depois de funcionar, salve a resposta bruta em um arquivo, para ter uma linha de base comprovadamente boa:
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json \
-o response.json
Colocar o corpo da requisição em request.json permite editar o prompt sem lutar com aspas do shell, o que é especialmente importante quando o prompt fica longo ou contém pontuação.
A mesma requisição em Python
A versão em Python é a mesma chamada HTTP, só que com uma experiência melhor: dicionários em vez de aspas aninhadas e manipulação direta dos bytes da imagem.
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "grok-imagine/text-to-image",
"prompt": "um farol em uma costa rochosa ao entardecer, mar calmo, luz suave e nublada",
}
response = requests.post(
f"{base_url}/v1/images/generations",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)
Dois detalhes merecem destaque. Primeiro, timeout=120 — a geração de imagem não é instantânea, e uma requisição sem timeout pode deixar um worker pendurado indefinidamente se o upstream travar. Segundo, chame raise_for_status() antes do parsing, para que um corpo de resposta de erro não seja confundido com uma resposta de imagem bem-sucedida.
Para salvar a imagem, trate as duas formas de resposta:
item = data["data"][0]
if item.get("b64_json"):
import base64
image_bytes = base64.b64decode(item["b64_json"])
else:
image_bytes = requests.get(item["url"], timeout=60).content
with open("output.png", "wb") as f:
f.write(image_bytes)
Se preferir um único conjunto de dependências, httpx é usado da mesma forma, com httpx.post(..., json=payload). O ponto crucial é que o corpo e os cabeçalhos da requisição sejam idênticos ao exemplo curl — é essa consistência que torna os dois exemplos intercambiáveis e a depuração previsível.
Organizando prompts para proporção de aspecto
Saídas em formato wide falham de maneiras específicas: o modelo tem muito espaço horizontal para preencher, então tende a repetir elementos ou a flutuar um sujeito minúsculo em uma cena vazia. Resolva isso com estrutura de prompt, não empilhando mais adjetivos.
Use um esqueleto de três partes:
- Sujeito — do que trata a imagem, declarado primeiro e específico. “Um navio de carga entrando no porto” é melhor que “um navio”.
- Estilo — a linguagem de renderização: fotografia, vetor flat, aquarela, still de cinema. Uma ou duas palavras bastam.
- Composição — como o quadro se organiza; é aqui que o sucesso ou fracasso de uma proporção wide é decidido.
Para a composição, nomeie explicitamente a estrutura horizontal:
- Especifique uma ordem de leitura da esquerda para a direita ou panorâmica: “vista ampla, sujeito no terço direito, céu aberto à esquerda.”
- Descreva primeiro plano, plano médio e fundo como faixas separadas, pois uma imagem wide é naturalmente lida em camadas.
- Defina o que preenche as bordas: “guindastes portuários na extrema esquerda, águas abertas na extrema direita.” As bordas são onde uma imagem wide esvazia primeiro.
- Evite prompts que sugiram composição retrato ou quadrada — rostos em close, um único objeto centralizado — e espere que sejam esticados ou tenham barras pretas.
Quando definir o parâmetro de proporção de aspecto para formato panorâmico, ajuste o prompt junto. Um prompt escrito para um quadro quadrado produzirá um conceito quadrado em uma tela wide. Reescreva-o para incluir distância horizontal: horizontes, ruas, fileiras de objetos, grupos espalhados por uma sala.
Itere uma variável por vez. Fixe a proporção e mude a redação; depois fixe a redação e mude a proporção. Registre ambos junto com a saída, para poder julgar qual mudança realmente ajudou.
Tratando erros e códigos de resposta
Leia o código de status primeiro, depois o corpo da resposta. Cada falha comum aponta para uma correção diferente, e confundi-las desperdiça tempo.
401 Unauthorized
Chave ausente, mal formatada ou revogada. Verifique se o cabeçalho é exatamente Authorization: Bearer <key>, se a variável de ambiente realmente foi expandida (imprima o comprimento, não o valor) e se você não enviou por engano uma chave de outro ambiente.
400 Bad Request
Seu JSON é HTTP válido, mas inválido para este endpoint. Suspeitos comuns:
modelcom erro de digitação ou ausente. Deve sergrok-imagine/text-to-image.promptvazio ou ausente.- Algum parâmetro com tipo errado — string onde deveria ser número, ou vice-versa.
- O corpo da requisição não é JSON válido, geralmente por problemas de aspas do shell no
curl. Mova o corpo para um arquivo e use-d @request.json.
Leia o corpo da mensagem de erro; normalmente ele indica o campo problemático.
429 Too Many Requests
Você está enviando requisições mais rápido que sua cota. A correção é no cliente: backoff, fila, retry. Não aperte o loop de retry só porque recebeu 429 — isso piora a situação.
Erros 5xx do servidor
São condições transitórias ou do upstream. Tente novamente após um atraso; se a falha persistir após várias tentativas, capture o payload da requisição e o corpo da resposta para diagnóstico, em vez de tentar indefinidamente.
Timeouts e erros de conexão
Não são códigos de status HTTP, mas são as falhas mais comuns na prática. Se requests lançar um timeout de conexão, a requisição pode ainda ter sido processada. Antes de escrever um loop de retry, decida para seu caso de uso se o timeout significa “tentar novamente” ou “desistir”.
Ajuste e retry em produção
Depois que a requisição de linha de base funcionar, ajuste em passos pequenos: primeiro a redação do prompt, depois a proporção de aspecto, depois outros parâmetros, comparando saídas lado a lado. Salve cada payload de requisição junto com sua saída, para que os resultados sejam sempre reproduzíveis.
Um wrapper de produção faz três coisas: tenta novamente apenas falhas que valem a pena, registra logs suficientes para depuração e falha ruidosamente ao desistir.
import time
import requests
def generate(payload, max_attempts=4):
for attempt in range(1, max_attempts + 1):
try:
r = requests.post(
f"{base_url}/v1/images/generations",
headers=headers,
json=payload,
timeout=120,
)
except requests.RequestException as exc:
log.warning("request failed attempt=%d err=%s", attempt, exc)
time.sleep(2 ** attempt)
continue
if r.status_code == 429 or r.status_code >= 500:
log.warning("retryable status=%d attempt=%d", r.status_code, attempt)
time.sleep(2 ** attempt)
continue
if r.status_code >= 400:
raise RuntimeError(f"{r.status_code}: {r.text[:500]}")
return r.json()
raise RuntimeError("exhausted retries")
Observações sobre esse padrão:
- Backoff exponencial com limite (
2 ** attempt) evita que clientes limitados por taxa martele o endpoint repetidamente. Se você executa muitos workers, adicione jitter. - Tente novamente apenas 429, 5xx e erros de rede. 400 ou 401 falharão da mesma forma em todas as tentativas.
- Registre o número da tentativa e o status, não a chave de API, e nunca registre o prompt completo se ele puder conter dados do usuário.
- Limite o tempo total. Um loop de retry sem limite transforma uma requisição lenta em um worker travado.
Meça sua própria latência e taxa de sucesso, em vez de supor; esses dois números indicam se você precisa de mais paralelismo ou mais backoff. Comece com a requisição mínima deste guia, envolva-a com a função auxiliar acima e itere a partir daí.
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