Como usar recraft-v4.1/text-to-image pela API HiAPI: guia com curl e Python

O que este endpoint oferece

recraft-v4.1/text-to-image é um endpoint de modelo de texto para imagem: você envia um prompt de texto e algumas opções de modelagem no corpo da requisição e recebe os dados da imagem gerada. Ele é ideal quando você quer produzir uma imagem finalizada em uma única chamada, sem precisar orquestrar um pipeline de várias etapas por conta própria.

Na HiAPI, esse modelo está incluído no modo agregado: uma URL base, um cabeçalho de autenticação e uma estrutura de requisição/resposta consistente entre endpoints. Você não precisa configurar um SDK e um conjunto de credenciais separados para cada modelo de imagem que deseja avaliar — basta apontar o cliente para o endpoint de recraft-v4.1/text-to-image na HiAPI e manter o restante do código estável. Isso é especialmente importante na fase de prototipagem, quando você quer comparar prompts, estilos e modelos sem reescrever a camada de transporte a cada vez.

Uma forma prática de entender essa chamada:

• Prompt — a descrição em linguagem natural da imagem que você deseja.
• Style — campo do corpo da requisição que orienta o tratamento visual da saída.
• Resolution — campo do corpo da requisição que determina o tamanho da saída.

Como os três trafegam no mesmo corpo JSON, a engenharia de prompt e a modelagem da saída acontecem em uma única ida e volta. Se você está avaliando se este é o endpoint adequado, a resposta geralmente é sim — quando você precisa de geração de imagem síncrona e orientada por prompt, e quer manter os detalhes de infraestrutura do fornecedor fora do código da aplicação.

Pré-requisitos e autenticação

Antes da primeira chamada, certifique-se de ter:

• Uma conta HiAPI e uma chave de API. Mantenha-a fora do controle de versão e carregue-a a partir de variáveis de ambiente.
• curl para um teste rápido de fumaça e Python 3 com requests instalado (se você for usar o exemplo em Python).
• Um prompt que você realmente queira renderizar — mesmo que seja simples, já basta para validar a integração.

A autenticação da HiAPI é baseada em cabeçalho. A chave de API é transmitida pelo cabeçalho, e o mesmo padrão de cabeçalho é usado quer você chame a partir de curl, Python ou qualquer outro cliente HTTP. A seleção do modelo é feita pelo caminho do endpoint, portanto o cabeçalho de autenticação permanece o mesmo quando você troca de modelo.

Uma configuração local segura é assim:

export HIAPI_API_KEY="your-key-here"

Depois, referencie $HIAPI_API_KEY nos comandos de shell e os.environ["HIAPI_API_KEY"] no Python. Nunca codifique a chave diretamente em scripts que possam ser commitados, e evite colá-la em logs ou relatórios de erro. Se a chave vazar, faça a rotação nas configurações da conta em vez de tentar removê-la do histórico.

Os exemplos a seguir pressupõem duas coisas: a URL base da API HiAPI e o caminho do modelo recraft-v4.1/text-to-image. Antes de integrar isso a uma build, confirme ambos na referência de API da sua conta, pois o host e o caminho exatos são as únicas informações deste guia que devem ser copiadas da documentação atual, e não de memória.

Requisição curl executável

A forma mais rápida de confirmar que a chave, o endpoint e a estrutura do payload funcionam é uma chamada curl. A requisição envia um corpo JSON com o prompt e os campos de modelagem, e transmite a chave de API no cabeçalho:

curl -X POST "$HIAPI_BASE_URL/recraft-v4.1/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A minimalist isometric illustration of a developer workstation, soft pastel palette, clean background",
    "style": "illustration",
    "resolution": "1024x1024"
  }'

Alguns pontos a observar sobre essa chamada:

• Caminho do endpoint. O nome do modelo está no caminho. Trocar para outro modelo depois significa alterar esse segmento do caminho, e não reconstruir a requisição.
• Use o corpo, não a query string. prompt, style e resolution ficam no corpo JSON. Assim a URL permanece estável e o payload é fácil de registrar e reproduzir.
• Autenticação por cabeçalho. O cabeçalho Authorization carrega a chave; Content-Type deve ser application/json.

Se você receber uma resposta diferente de 200 na primeira tentativa, verifique nesta ordem: se a chave está definida no shell, se a URL base não tem barras finais duplicadas e se o corpo JSON é válido (vírgulas finais costumam ser a causa). Depois que a chamada funcionar, salve o comando exato em um arquivo de rascunho — uma chamada curl que você sabe que funciona é sua referência para comparar cada alteração de SDK e cliente.

A mesma requisição em Python

Para código real, encapsule a chamada em uma função pequena, para que retentativas, logging e troca de modelo tenham um lugar único. Usando requests:

import os
import requests

HIAPI_BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]


def generate_image(prompt, style="illustration", resolution="1024x1024", timeout=120):
    url = f"{HIAPI_BASE_URL}/recraft-v4.1/text-to-image"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {
        "prompt": prompt,
        "style": style,
        "resolution": resolution,
    }
    response = requests.post(url, headers=headers, json=payload, timeout=timeout)
    response.raise_for_status()
    return response.json()

Pontos de design que vale a pena manter:

• Use json=, não data=. Passar um dict para json= define o tipo de conteúdo e serializa o corpo por você, então o payload fica idêntico, byte a byte, ao da versão curl.
• Timeout explícito. A geração de imagem não é instantânea; um timeout generoso evita falsos erros com requisições lentas, mas saudáveis. Não dependa dos valores padrão do cliente.
• raise_for_status() primeiro. Converta erros HTTP em exceções antes de tentar ler o corpo da resposta, para que um 4xx ou 5xx nunca seja confundido com dados de imagem.
• Configuração baseada em ambiente. A URL base e a chave vêm do ambiente, o que torna a função portátil entre local, staging e produção.

A função retorna o JSON já analisado. Como extrair a imagem desse JSON é o próximo tópico, e é onde a maioria das integrações falha.

Tratar a resposta síncrona de imagem

recraft-v4.1/text-to-image retorna os dados da imagem de forma síncrona: a imagem volta na mesma resposta HTTP da requisição, sem loop de polling e sem task ID para acompanhar. Isso simplifica o cliente, mas transfere duas responsabilidades para o seu código — decodificar o payload e tratar falhas de forma explícita.

O caminho de tratamento robusto é:

1. Verifique o status antes de analisar. Trate qualquer resposta diferente de 200 como erro e exiba o corpo da resposta, que geralmente explica o problema.
2. Leia o campo de imagem com intenção. O JSON de resposta carrega os dados da imagem; dependendo do campo recebido, ele pode ser uma URL ou bytes de imagem codificados. Trate os dois caminhos em vez de assumir um deles.
3. Decodificação defensiva. Se o payload estiver codificado em base64, decodifique e grave os bytes em um arquivo. Não faça binários passarem por caminhos somente texto nem os imprima no terminal.
4. Limite o tamanho do payload. Respostas síncronas de imagem são grandes em comparação com JSON típico. Grave em disco em streaming quando o cliente suportar, e evite manter várias respostas em memória ao mesmo tempo.

Um passo mínimo de salvamento para payloads em base64:

import base64

data = generate_image("A calm forest at dawn, soft light")
image_b64 = data["image"]  # adjust to the actual field name in the response
with open("out.png", "wb") as f:
    f.write(base64.b64decode(image_b64))

Dois modos de falha merecem tratamento específico. Timeouts devem ser repetidos com backoff, mas somente quando a idempotência for esperada — regenerar uma imagem produz resultados diferentes, então registre o prompt em cada tentativa. Erros de cliente (como corpo malformado ou valor de opção inválido) não se resolvem com retentativa; falhe rápido e registre o texto da resposta. Por fim, valide que o campo de imagem existe antes de decodificar, para que uma mudança de schema ou um payload de erro gere uma exceção clara em vez de um erro de decodificação confuso.

Ajustar estilo e resolução ao seu caso de uso

style e resolution são os dois campos do corpo da requisição que mais influenciam o resultado retornado, e ambos têm baixo custo de iteração, pois são enviados junto com o prompt.

Style

style orienta o tratamento visual da saída. Use-o para manter uma série de imagens visualmente consistente — por exemplo, fixando o mesmo estilo em um lote de ilustrações de produto ou imagens de capa de artigo, para que pareçam um conjunto. Quando o resultado parecer errado, verifique primeiro se o estilo combina com o conteúdo: aplicar um estilo voltado a ilustração a um prompt realista conflita com o texto. Antes de adicionar detalhes, teste prompts simples com um estilo fixo, para que você possa distinguir se um resultado ruim vem do estilo ou da formulação.

Resolution

resolution determina o tamanho da saída. Faça-a corresponder ao uso pretendido: escolha tamanhos próximos do quadrado para avatares e miniaturas, e tamanhos mais largos para banners e imagens principais. Duas regras práticas:

• Gere no tamanho certo em vez de ampliar depois. Gere a imagem próxima do tamanho final de exibição, em vez de gerar uma pequena e ampliá-la.
• Atenção à proporção. Se o seu layout espera uma proporção específica, escolha uma resolução que corresponda a essa proporção, em vez de cortar depois.

Depurar resultados inesperados

Quando a imagem parecer errada, isole uma variável por vez. Mantenha o prompt fixo e altere style; depois mantenha os dois fixos e altere resolution. Se nada ajudar, reescreva o prompt com substantivos concretos e indicações claras de composição, em vez de adicionar adjetivos. Confirme também que você não está enviando silenciosamente um tipo de valor errado — uma string de estilo que não corresponde às opções aceitas pode ser rejeitada ou ignorada, dependendo da lógica de validação. Registre o corpo exato de cada requisição; esse é o único registro confiável de como uma imagem foi produzida.

Encapsular para produção

O valor daquela função pequena aparece quando você a fortalece. Um encapsulamento de nível de produção deve fazer quatro coisas:

• Encapsular o transporte. Uma função detém a URL, os cabeçalhos, a estrutura do payload e o timeout. Quem chama passa apenas o prompt e as opções, nada mais.
• Adicionar retentativas com backoff. Repita um número limitado de vezes para timeouts e respostas 5xx; nunca repita erros 4xx. Como a geração de imagem não é idempotente, mantenha o limite de retentativas baixo e associe o prompt a cada tentativa.
• Registre a requisição, não apenas o resultado. Registre o prompt, o estilo, a resolução, o status e a duração. Quando alguém perguntar por que a imagem ficou assim, esse log é a resposta.
• Trate o modelo como parâmetro. Passe o caminho do modelo como parâmetro, com valor padrão recraft-v4.1/text-to-image. Assim, trocar para outro modelo de imagem passa a ser uma mudança de configuração e não uma refatoração, o que torna a avaliação lado a lado barata.

Mantenha a camada de encapsulamento leve. Resista à tentação de adicionar cache, filas ou políticas de armazenamento nela — isso pertence a uma camada superior, para que evoluam independentemente da chamada de API. Uma interface estável também significa que seus testes podem simular a camada de transporte e verificar o payload que você enviará, capturando a maioria dos erros de integração antes que cheguem à requisição real.

Com autenticação, uma requisição que você sabe que funciona e tratamento explícito de resposta, você tem tudo o que precisa para chamar recraft-v4.1/text-to-image pela HiAPI em curl e Python, e depois trocar de modelo sem tocar no restante do código.