Blogue

Tutorial

Como usar grok-imagine/text-to-image via HiAPI API: guia curl e Python

Nov 12, 2026
Arte de capa em papel estratificado em creme e grafite, com uma única folha terracota escalonada em profundidade rasa.
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:

  1. 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.
  2. Uma ferramenta para fazer requisições HTTP. Para o primeiro teste, curl é suficiente. Para Python, use requests ou httpx; ambos serão abordados adiante.
  3. Acesso à rede ao host da API HiAPI. Se estiver atrás de um proxy corporativo, certifique-se de definir HTTPS_PROXY para seu shell, para que tanto curl quanto 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 POST com corpo JSON é a forma padrão para endpoints de geração.
  • model seleciona explicitamente grok-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:

  1. Sujeito — do que trata a imagem, declarado primeiro e específico. “Um navio de carga entrando no porto” é melhor que “um navio”.
  2. Estilo — a linguagem de renderização: fotografia, vetor flat, aquarela, still de cinema. Uma ou duas palavras bastam.
  3. 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:

  • model com erro de digitação ou ausente. Deve ser grok-imagine/text-to-image.
  • prompt vazio 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 →

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