Como usar o imagen-4.0-fast pela API HiAPI: guia com curl e Python

Direção de otimização do imagen-4.0-fast

O imagen-4.0-fast é a camada de baixa latência da família imagen-4.0: ele prioriza respostas rápidas para solicitações de geração de imagem, mantendo a mesma estrutura de requisição e resposta dos outros modelos da família. Na prática, deve-se escolher essa camada quando as imagens precisam ser exibidas instantaneamente durante a interação do usuário — por exemplo, miniaturas de rascunho, pré-visualizações para o usuário refinar ou elementos para layouts em tempo real — e não em processamento em lote offline (quando o tempo real decorrido não importa).

Uma forma eficaz de pensar na escolha do modelo é separar o orçamento de interação do teto de qualidade. Quando o orçamento de interação é apertado e uma imagem "boa o suficiente" desbloqueia o próximo passo, a camada rápida vence. Quando a imagem é o próprio entregável, a camada de maior qualidade vence. Como o imagen-4.0-fast compartilha a mesma interface HiAPI dos outros modelos de imagem, alternar de camada depois exige apenas mudar a configuração, sem reescrever o código — assim, você pode começar pela camada rápida, medir se a qualidade da saída atende ao padrão do produto e só então considerar mover casos de uso específicos para camadas superiores.

Outro aspecto da otimização da camada rápida é a previsibilidade sob carga. Tempos de geração curtos significam que a conexão fica ocupada por menos tempo, o que faz o orçamento de concorrência se comportar de forma mais linear: antes de atingir o limite de taxa da conta, dobrar o número de workers aproximadamente dobra a vazão, em vez de provocar timeout no meio da geração. A discussão sobre timeouts e concorrência mais adiante se baseia exatamente nessa característica.

Se o seu caso de uso envolve fluxos de usuário em várias etapas, processamento em lote ou qualquer cenário em que a requisição possa ser repetida, a camada rápida é a escolha padrão mais segura — você tolera uma tentativa extra e ainda permanece dentro da janela de paciência humana.

Pré-requisitos e configuração da API

Antes da primeira chamada, quatro coisas precisam estar prontas.

1. Conta HiAPI e chave de API

Toda a geração de imagem é feita por meio da API unificada da HiAPI. Crie uma chave de API no console da HiAPI e armazene-a como variável de ambiente, em vez de escrevê-la no código-fonte:

export HIAPI_API_KEY="your_key_here"

Nunca faça commit da chave. Se o seu código roda em CI ou em contêineres, injete a variável em tempo de execução por meio de um gerenciador de segredos.

2. URL base e identificador do modelo

Mantenha duas constantes em um módulo de configuração, para que todas as requisições do código apontem para o mesmo lugar:

HIAPI_BASE_URL = "https://api.hiapi.ai"
HIAPI_IMAGE_MODEL = "imagen-4.0-fast"

O identificador do modelo seleciona o imagen-4.0-fast no payload da requisição. Trate-o como dado, e não como uma string codificada espalhada por vários arquivos.

3. Um cliente HTTP confiável

Em Python, tanto httpx quanto requests funcionam; o httpx oferece um objeto de timeout mais claro. Em trabalho de shell, o curl já basta e é a forma mais rápida de isolar se o problema está no seu código ou na própria requisição.

4. Utilitário mínimo de teste

Defina desde o início onde a saída gerada será gravada — em um teste de fumaça, escrever em um arquivo em disco basta, mas o código de produção deve fazer streaming ou armazenamento de forma consciente, em vez de deixar payloads grandes na memória.

Dois hábitos de configuração compensam cedo. Primeiro, concentre a autenticação em uma função auxiliar que anexa o cabeçalho Authorization, assim a rotação de chave exige mudança em um único lugar. Segundo, mantenha uma flag DEBUG que permita imprimir o ID da requisição e o tempo decorrido sem alterar o payload. Quando ocorre um incidente às duas da manhã, esses dois hábitos decidem entre uma correção de cinco minutos e uma hora de adivinhação.

Fazer uma requisição funcional com curl

A seguir, uma chamada curl completa e executável. Ela gera uma imagem a partir de um prompt de texto:

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0-fast",
    "prompt": "a quiet harbor at dawn, soft mist over wooden docks, photographic",
    "n": 1,
    "size": "1024x1024"
  }'

Campo a campo:

• -sS oculta a barra de progresso, mas ainda exibe erros. Ao depurar, adicione -i para ver os cabeçalhos de resposta, que normalmente trazem o ID da requisição, útil para referenciar ao pedir ajuda.
• -X POST junto com o cabeçalho Content-Type: application/json faz do payload uma requisição estruturada, e não um corpo opaco.
• Authorization: Bearer $HIAPI_API_KEY é o único mecanismo de autenticação. A chave é lida da variável de ambiente, então, desde que você a defina na sessão, ela não aparece em texto claro no histórico do shell.
• model seleciona o imagen-4.0-fast no endpoint de imagens da HiAPI. Omiti-lo pode resultar em um modelo padrão diferente — sempre especifique explicitamente.
• prompt é o único campo de conteúdo obrigatório. Seja descritivo, mas não escreva uma enciclopédia; prompts longos demais consomem tokens e, além de certo ponto, raramente melhoram a saída da camada rápida.
• n controla quantas imagens a requisição retorna. Comece com 1 durante a integração.
• size é a solicitação de resolução de saída. A seção 5 explica como escolher.

Execute uma vez e inspecione o corpo da resposta antes de escrever qualquer código Python. Se o curl funcionar, qualquer falha posterior está no código do cliente. Se o curl falhar, o problema está na chave, no payload ou na conta — e você já eliminou metade do escopo de investigação.

Fazer a mesma requisição em Python

A seguir, o cliente Python mínimo, correspondendo campo a campo à chamada curl e envolvendo a camada HTTP com tratamento de erros:

import os
import httpx

HIAPI_BASE_URL = "https://api.hiapi.ai"
HIAPI_IMAGE_MODEL = "imagen-4.0-fast"

def generate_image(prompt: str, size: str = "1024x1024") -> dict:
    api_key = os.environ["HIAPI_API_KEY"]  # fail fast if unset
    payload = {
        "model": HIAPI_IMAGE_MODEL,
        "prompt": prompt,
        "n": 1,
        "size": size,
    }
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    }
    with httpx.Client(timeout=httpx.Timeout(60.0, connect=10.0)) as client:
        response = client.post(
            f"{HIAPI_BASE_URL}/v1/images/generations",
            json=payload,
            headers=headers,
        )
    if response.status_code == 401:
        raise RuntimeError("HiAPI rejected the API key")
    if response.status_code == 429:
        raise RuntimeError("Rate limited; back off and retry")
    response.raise_for_status()
    return response.json()

if __name__ == "__main__":
    result = generate_image("a quiet harbor at dawn, soft mist over wooden docks, photographic")
    print(result)

Há algumas escolhas intencionais nesse trecho:

• os.environ["HIAPI_API_KEY"] lança imediatamente um KeyError quando a variável está ausente, o que é melhor do que enviar uma requisição não autenticada e interpretar erroneamente o 401 como problema de chave.
• Timeouts explícitos — timeout de conexão e de leitura configurados separadamente. O timeout de leitura é o mais crítico para geração de imagem, pois o servidor mantém a conexão aberta enquanto gera a imagem.
• Tratamento por código de status, antes de raise_for_status(). 401 e 429 exigem respostas totalmente diferentes do código; combiná-los em uma única exceção torna o retry propenso a erros.
• Gerenciador de contexto Client garante que a conexão seja fechada de forma determinística. Em serviços de longa duração, crie um cliente na inicialização e reutilize-o — a reutilização de conexão é importante para a vazão.

O corpo da resposta contém referências às imagens geradas e metadados. Registre o corpo completo da resposta nas primeiras chamadas durante a integração, para saber exatamente de quais nomes de campo o seu código depende.

Parâmetros e escolha de resolução

O tratamento de parâmetros do imagen-4.0-fast se beneficia de um estilo simples e explícito. Mantenha o payload como um dicionário construído por uma única função e valide antes de enviar, não depois de falhar.

Prompt

O prompt é o parâmetro de maior alavancagem e o mais fácil de superdimensionar. Descreva na ordem: sujeito, cena, estilo. Evite empilhar termos de estilo contraditórios; a camada rápida os resolve como uma média, e não como o compromisso que você imaginou. Se você gera repetidamente o mesmo prompt, armazene o resultado em cache no servidor em vez de solicitar novamente.

n

Solicitar várias imagens em uma única chamada é conveniente para seletores voltados ao usuário, mas multiplica o trabalho de uma única requisição, prolongando o tempo de ocupação da conexão. Mantenha n igual a 1 durante a integração; aumente-o apenas depois de medir a latência ponta a ponta com ele ativado.

size

O parâmetro de resolução é onde custo e latência se acumulam silenciosamente. Saídas maiores significam mais trabalho de geração e corpo de resposta maior. Escolha a menor resolução que atenda ao contexto de exibição — um espaço de miniatura não precisa das dimensões de uma imagem principal. Desacople o tamanho de geração do tamanho de exibição, deixando seu pipeline de imagem ampliar ou reduzir depois; isso mantém as requisições previsíveis e facilita ajustar a qualidade conforme a latência no futuro, sem alterar a lógica do prompt.

Determinismo e reprodutibilidade

Registre cada parâmetro que você envia junto com a saída, indexado pelo ID da requisição. Quando alguém perguntar por que uma imagem está diferente da semana passada, o payload armazenado responde em segundos. Se você constrói o payload mesclando entrada do usuário sobre valores padrão, valide o resultado mesclado como um todo — sobrescritas parciais são uma fonte comum de requisições malformadas.

Uma regra prática: o payload deve ser pequeno, totalmente explícito e reproduzível a partir dos logs. Qualquer coisa que não possa ser reconstruída a partir dos logs é um parâmetro que você vai acabar se arrependendo de ter adicionado.

Lidar com timeouts e concorrência

Como o imagen-4.0-fast mantém tempos de geração curtos, a maioria dos problemas de confiabilidade está no cliente: timeout configurado baixo demais, retry disparado quando não deveria, ou paralelismo alto demais para os limites da conta.

Timeouts

Defina dois valores, não um. Um timeout de conexão curto captura rapidamente problemas de rede e DNS; um timeout de leitura mais longo acomoda o tempo de geração mais transmissão. O timeout de leitura deve ser escolhido com base na latência p95 observada no seu ambiente mais uma margem, e não por chute. Repetir uma requisição que já deu timeout enquanto o servidor ainda está trabalhando desperdiça capacidade — portanto, se você realmente fizer retry, trate-o como uma nova tentativa com orçamento próprio, em vez de assumir que a primeira foi gratuita.

Retry

Só repita o que é seguro repetir: erros de conexão e respostas 5xx. Nunca repita 4xx — um payload malformado falhará da mesma forma todas as vezes. Use backoff exponencial com jitter e limite o número total de tentativas. Uma estrutura útil é três tentativas, com atrasos de cerca de 1s, 2s e 4s com randomização, o que distribui a carga quando muitos clientes falham ao mesmo tempo.

Concorrência

Para trabalho em lote, use um pool de workers limitado, e não um asyncio.gather ilimitado. Cada requisição em andamento ocupa uma conexão e consome o orçamento de taxa da sua conta. Comece com um pool pequeno — poucas requisições concorrentes —, meça a vazão e aumente até a latência parar de melhorar ou começarem a aparecer 429. O tempo de geração curto da camada rápida ajuda aqui: como cada requisição termina rapidamente, um pool moderado sustenta alta vazão sem manter conexões abertas por muito tempo.

Contrapressão

Quando você recebe 429, a resposta correta é desacelerar, não repetir imediatamente. Adicione um pequeno atraso seguindo o padrão de backoff acima e considere reduzir temporariamente o tamanho do pool. Registre o nível de concorrência no momento do 429 — esse número é o seu limite prático.

Depurar falhas comuns de requisição

Trate as falhas na ordem que elimina mais incerteza a cada passo: primeiro reproduza com curl, depois vá para o cliente.

401 Unauthorized

Chave ausente, malformada ou não enviada como Bearer token. Inspecione diretamente o cabeçalho Authorization, confirme que a variável de ambiente está realmente preenchida no processo que faz a chamada (contêineres e executores de CI são diferentes do seu shell) e verifique se não há aspas extras ou espaços no final ao redor do valor. Se o curl funciona com a chave literal e a sua aplicação falha, o problema está certamente no carregamento do ambiente.

400 Bad Request

Payload malformado ou valor de parâmetro inválido. Reproduza com o JSON exato que o seu cliente realmente envia — registre o payload serializado, não o dicionário em memória — e compare com o exemplo de curl que funciona. Causas comuns: ausência de Content-Type, model com erro de digitação, campos numéricos enviados como string e campos remanescentes de um formato antigo da API.

422 / erros de validação

O campo existe, mas está fora do intervalo permitido — geralmente n ou size definido como um valor que o modelo não aceita. Reduza o payload aos campos mínimos obrigatórios, confirme o sucesso e então adicione os parâmetros de volta um a um.

429 limite de taxa ou cota esgotada

Você enviou mais requisições, ou mais requisições concorrentes, do que a conta permite. Confirme com os logs de concorrência, reduza o pool e verifique se o padrão de backoff está realmente sendo aplicado. Se persistir mesmo com volume baixo, verifique se outro processo compartilha a mesma chave.

5xx e timeouts

Problema do servidor ou de rede. Repita uma ou duas vezes com backoff; se a falha for repetível com um payload específico, capture o ID da requisição a partir dos cabeçalhos de resposta e o payload exato — é exatamente isso que torna um pedido de escalação produtivo.

Um hábito universal

Mantenha uma reprodução em curl com --verbose para cada incidente de produção. Passar do erro da aplicação para um único comando curl copiável reduz o escopo de depuração à própria requisição. Com isso, o uso do imagen-4.0-fast pela API HiAPI torna-se previsível.