Como usar o imagen-4.0 pela API do HiAPI: curl, Python e exemplos de requisição disponíveis

O que o HiAPI oferece para o imagen-4.0

imagen-4.0 é um modelo de texto para imagem: você envia um prompt em linguagem natural e ele devolve uma imagem gerada. Como desenvolvedor de integração, o que realmente importa não é a arquitetura do modelo, mas o contrato de interface em torno dele. No HiAPI, esse contrato é um endpoint HTTP — que aceita JSON e autentica com uma chave bearer — exatamente o mesmo padrão que você já conhece das chamadas de chat completion e embedding.

Benefícios reais de usar o HiAPI em vez de acessar o modelo diretamente:

• Esquema de autenticação unificado. A mesma chave de API vale para todos os modelos da plataforma, então você não precisa alternar entre credenciais de vários provedores.
• Formato de requisição unificado. Um corpo JSON contendo o identificador do modelo e o prompt. Sem precisar aprender a estrutura de requisição de um SDK específico.
• Retorno síncrono. O imagen-4.0 devolve o resultado na mesma resposta HTTP, então em cenários básicos não é preciso construir loop de polling nem webhook.

Este guia vai te levar do zero até uma requisição funcional em curl e em Python, e depois explicar como ler a resposta e o que preparar antes de ir para produção.

Obter a chave de API e configurar a autenticação

Toda chamada ao imagen-4.0 no HiAPI é autenticada com um bearer token. Você cria uma chave de API na sua conta HiAPI e, a partir daí, essa chave é a única credencial necessária para as requisições — sem project ID separado e sem cabeçalhos de assinatura.

O princípio que evita a maioria dos incidentes: a chave deve ficar em variável de ambiente, nunca ser commitada no código-fonte. Uma chave colada em um script e enviada ao repositório é uma chave que você terá de rotacionar.

Configuração local

Exporte a chave na sua sessão de shell:

export HIAPI_API_KEY="your-key-here"

Se quiser que a variável seja persistente, adicione essa linha ao arquivo de configuração do seu shell; ou use um arquivo .env, inclua-o no .gitignore e carregue-o na inicialização da aplicação.

Ambiente implantado

Em CI e em produção, defina HIAPI_API_KEY pelo gerenciador de segredos da plataforma — injetando a variável de ambiente em tempo de execução, não gravando o arquivo na imagem. Assim o código da aplicação fica idêntico entre local e ambiente implantado, mudando apenas a origem da variável.

Cabeçalho da requisição

Toda requisição carrega:

Authorization: Bearer $HIAPI_API_KEY

Se você vir um 401, a primeira coisa a verificar é se o cabeçalho está sendo realmente enviado e se a variável resolve para um valor não vazio. Um shell que nunca exportou a variável envia Bearer normalmente, seguido de nada.

Entender a estrutura da requisição antes de enviar

O corpo de uma requisição ao imagen-4.0 é pequeno o bastante para memorizar, e isso é justamente o ponto — uma vez que você entende sua estrutura, consegue montar a requisição em qualquer linguagem, sem traduzir um trecho de código copiado e colado.

No mínimo, é preciso enviar:

{
  "model": "imagen-4.0",
  "prompt": "A weathered lighthouse on a cliff at dusk, long exposure, muted colors"
}

Dois campos fazem o trabalho principal:

• model identifica qual modelo processa a requisição. É uma string e é o mesmo identificador que a plataforma usa em todos os lugares onde lista o imagen-4.0. Se estiver errado, você recebe uma resposta de erro, não um fallback silencioso.
• prompt é a descrição da imagem que você quer. Escreva como descreveria a cena para uma pessoa: sujeito, cenário, estilo, iluminação. Prompts específicos produzem resultados mais previsíveis do que prompts de uma única palavra.

A requisição é enviada via POST, com Content-Type: application/json, para o endpoint de geração de imagem da plataforma. O modelo pode ter parâmetros opcionais adicionais, mas o corpo com os dois campos acima já é uma requisição completa e válida — comece por ele e só adicione opções quando necessário.

Como o corpo é JSON puro, curl, Python, Node e qualquer ferramenta com cliente HTTP são cidadãos de primeira classe. As duas seções a seguir mostram a mesma requisição em duas formas.

Requisição curl funcional

Comece pelo terminal, onde você vê a resposta bruta, sem qualquer interferência de parsing.

curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0",
    "prompt": "A weathered lighthouse on a cliff at dusk, long exposure, muted colors"
  }'

Linha a linha:

• -sS silencia a barra de progresso mas ainda mostra erros, deixando a saída legível sem esconder falhas.
• -X POST define o método da requisição. A geração de imagem cria conteúdo, então é POST.
• A URL é o endpoint de geração de imagem da plataforma, composta pela sua base URL mais o caminho. Mantenha a base URL em uma variável para que o mesmo comando funcione em ambientes diferentes.
• O primeiro cabeçalho carrega sua chave bearer, lida da variável de ambiente exportada anteriormente.
• Content-Type: application/json informa ao servidor como interpretar o corpo.
• -d fornece o corpo JSON. As aspas simples impedem que o shell interprete chaves e aspas; o JSON dentro é literal.

Se quiser inspecionar a saída, passe-a por um formatador JSON:

curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"imagen-4.0","prompt":"A weathered lighthouse on a cliff at dusk"}' \
  | python -m json.tool

Se a resposta contiver uma referência de imagem, a requisição foi bem-sucedida. A próxima seção transforma isso em código de aplicação.

Escrever a mesma requisição em Python

A chamada curl é convertida diretamente. A única escolha real é o cliente HTTP; o urllib da biblioteca padrão funciona em qualquer lugar, mas o requests tem código mais curto e é a biblioteca que a maioria dos codebases já usa.

Função auxiliar reutilizável

import os
import requests

HIAPI_BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai/v1")


def generate_image(prompt: str, model: str = "imagen-4.0") -> dict:
    api_key = os.environ["HIAPI_API_KEY"]
    response = requests.post(
        f"{HIAPI_BASE_URL}/images/generations",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json={"model": model, "prompt": prompt},
        timeout=120,
    )
    response.raise_for_status()
    return response.json()


result = generate_image("A weathered lighthouse on a cliff at dusk")
print(result)

Três pontos valem destaque:

• os.environ["HIAPI_API_KEY"] lança KeyError imediatamente quando a variável está ausente, falhando rápido e alto em vez de enviar um token vazio.
• json= serializa o dicionário automaticamente e define o content type, então o comportamento da requisição é idêntico ao da versão curl.
• timeout=120 limita a duração da chamada. Geração de imagem demora mais que completion de texto, então use um timeout folgado em vez do padrão sem timeout.

A função recebe o prompt como parâmetro e retorna o JSON já interpretado, o que significa que o restante do seu código não precisa tocar nos detalhes de HTTP. Teste no REPL antes de conectar isso a qualquer coisa.

Ler a resposta síncrona e tratar erros

O imagen-4.0 responde de forma síncrona: a imagem gerada vem no corpo da mesma resposta HTTP. Em cenários básicos não há job ID para consultar nem loop de polling para escrever — trate a chamada como qualquer outra interação requisição-resposta.

O que é retornado

A resposta de sucesso é um objeto JSON. Em Python, faça o parse com response.json(), ou passe a saída do curl por um formatador JSON, e então localize os dados da imagem na estrutura retornada — normalmente uma URL ou um payload de imagem codificado, junto com metadados sobre a geração. Leia os nomes exatos dos campos em uma resposta real uma vez e escreva o código a partir disso.

Problemas para os quais se proteger

Envolva a chamada e verifique o status antes de fazer o parse:

try:
    result = generate_image("A weathered lighthouse on a cliff at dusk")
except requests.HTTPError as e:
    print("HTTP error:", e.response.status_code, e.response.text)
except requests.Timeout:
    print("Request timed out")

Modos de falha que vale a pena tratar explicitamente:

• 401 — chave ausente ou inválida. Corrija a variável de ambiente, não o código.
• 4xx em geral — corpo malformado, identificador de modelo errado ou prompt rejeitado. O corpo da resposta costuma indicar qual desses. Registre em log.
• 5xx — falhas do lado do servidor. Essas merecem retry com backoff.
• Timeouts — trate como resultado desconhecido, não como sucesso; não assuma que a imagem foi gerada.

Sempre registre o status code e o corpo da resposta truncado em caso de falha. Depurar sem essas informações é adivinhar.

Do primeiro pedido à produção

A requisição já funciona. Antes de escalar, verifique item por item:

• Configuração. A base URL e a chave de API vêm de variáveis de ambiente. Nenhum literal no código-fonte, nenhuma chave na imagem.
• Timeouts. Toda chamada de imagem tem timeout. Sem timeout, uma requisição travada pode ocupar um worker indefinidamente.
• Retries. Faça retry apenas de 5xx e timeouts, com backoff exponencial e limite máximo. Nunca faça retry de 401 ou de 4xx por corpo malformado — eles vão falhar exatamente da mesma forma.
• Log. Registre o modelo, o comprimento do prompt, o status code e a latência de cada chamada. Não registre a chave e, se o prompt puder conter dados do usuário, não registre o prompt completo.
• Consciência de custo. A geração de imagem é cobrada pela saída produzida, então acompanhe quantas imagens foram pedidas por usuário ou por job e defina limites na camada de aplicação. Para as tarifas atuais, consulte o painel de preços da plataforma, não este guia.
• Concorrência. Chamadas de imagem são mais lentas que chamadas de texto. Dimensione o pool de workers com base nisso, não assumindo a latência de chat-completion.

Com esses itens prontos, a mesma função auxiliar generate_image funciona sem alterações em jobs em lote, funcionalidades voltadas ao usuário e ferramentas internas. Para mais detalhes de integração, consulte a documentação da plataforma.