Blogue

Tutorial

Como usar krea-3/text-to-image pela API do HiAPI: curl, Python e uma requisição executável

Nov 10, 2026
Imagem de capa: sobre um fundo cinza-carvão quente, uma faixa de luz âmbar atravessa a imagem diagonalmente, com linhas finas de cores secundárias pontuando as bordas.
Nesta página

Por que chamar krea-3/text-to-image por uma API agregadora

Cada novo modelo de imagem significa mais um SDK, mais um esquema de autenticação, mais um conjunto de peculiaridades de resposta. Se você publica apenas um recurso de imagem, esse custo é tolerável. Mas se você publica vários — ou quer poder trocar de modelo livremente no futuro — ele se torna o principal custo do trabalho.

Chamar krea-3/text-to-image pelo HiAPI elimina esse custo. Você integra uma única vez, contra uma única convenção de endpoint, uma única credencial e uma única estrutura de resposta. O identificador do modelo se torna um campo no payload da requisição, não uma bifurcação no código. Quando você quer comparar a saída com outros modelos de imagem ou migrar cargas de trabalho, você muda uma string, não uma integração.

Para este modelo específico, os ganhos práticos são concretos:

  • Todas as requisições compartilham a mesma estrutura. As chamadas de geração de texto para imagem seguem as mesmas convenções de autenticação e payload em toda a plataforma, então o que você aprende na primeira chamada se transfere diretamente para o próximo modelo.
  • Código de aplicação independente de modelo. Mantenha o nome do modelo na configuração. Prototipar com krea-3/text-to-image e depois trocar por outro modelo em produção não deve exigir alterar sua camada HTTP.
  • Ponto único de observação de uso. Cobrança, logs de requisição e respostas de erro vêm todos da mesma interface, em vez de N painéis de fornecedores.
  • Menos chaves. Não importa quantos modelos você chame, você só precisa armazenar, rotacionar e restringir uma única chave.

O preço é o preço habitual da agregação: você trabalha através de uma interface genérica, então as peculiaridades específicas de cada modelo são normalizadas. Na prática, é exatamente isso que você quer — entradas normalizadas, erros previsíveis e a liberdade de tratar o modelo como um parâmetro ajustável.

Este tutorial mantém o escopo deliberadamente estreito. Vamos construir uma requisição executável, rodá-la duas vezes (primeiro com curl, depois com Python), observar como a redação do prompt direciona saídas em estilo fotográfico e de ilustração, e então depurar as poucas falhas que respondem pela maioria dos problemas na primeira chamada. Sem diagramas de arquitetura, sem opiniões sobre frameworks — apenas uma requisição que você pode enviar nos próximos cinco minutos e uma lista de verificação para usar quando algo der errado.

Pressupostos: você tem uma conta no HiAPI, consegue ler a chave de API no painel e está familiarizado com o terminal e o interpretador Python. Nada além disso.

Antes de enviar a requisição

Três condições precisam ser atendidas antes da primeira chamada. Acerte essas e o resto é principalmente ajuste fino; erre e você passará uma hora depurando a camada errada.

1. Conta e chave de API

Faça login no HiAPI e obtenha sua chave de API no painel. Trate-a como confidencial: ela deve ficar em uma variável de ambiente ou em um gerenciador de segredos, nunca em um arquivo commitado, nunca em um prompt ou em uma mensagem de suporte. Os exemplos abaixo a leem de uma variável de ambiente:

export HIAPI_API_KEY="your-key-here"

Se sua organização suporta várias chaves, use uma dedicada para esta integração, para que você possa rotacioná-la independentemente de outras execuções.

2. Convenção de endpoint e cabeçalho de autenticação

As requisições ao HiAPI usam autenticação por bearer token — o mesmo padrão que você já viu em outras centenas de APIs:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Use a base URL mostrada na referência da API do HiAPI para a região da sua conta e acrescente o caminho de geração de imagem documentado ali. Não adivinhe o caminho de memória nem a partir de um post de blog (incluindo este) — a referência da API é a única fonte de verdade, e o caminho é a única parte da requisição que muda sem aviso. Sugestão do tutorial: consulte a referência uma vez, copie a URL e guarde-a em um valor de configuração.

3. Identificador do modelo, com a grafia exata

O identificador do modelo é krea-3/text-to-image. Mantenha o prefixo de namespace e o hífen exatamente como escritos — krea3/text2image ou apenas krea-3 falharão com modelo não encontrado. Maiúsculas e minúsculas também importam. Armazene-o como uma constante:

MODEL = "krea-3/text-to-image"

É essa string que torna sua integração independente de modelo, então dê um nome a ela e trate-a como configuração, em vez de codificá-la fixamente em cada ponto de chamada.

O que você não precisa descobrir de antemão

Você não precisa saber os nomes dos campos de tamanho de imagem, seed ou passos antes da primeira chamada. Comece com o mínimo: autenticação, identificador do modelo e prompt. Depois de obter uma resposta 200, adicione os parâmetros um a um, porque uma requisição que falha com cinco campos definidos lhe dá cinco suspeitos. Uma requisição mínima que falha lhe dá apenas um.

Construir uma requisição executável com curl

O curl é a maneira mais rápida de isolar os dois problemas da primeira chamada: credenciais e estrutura de payload. Sem versão de SDK, sem ambiente virtual, sem runtime assíncrono — apenas uma requisição no fio.

A chamada mínima carrega apenas o que o modelo realmente precisa: o cabeçalho de autenticação, o identificador do modelo e o prompt.

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "krea-3/text-to-image",
    "prompt": "A weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph"
  }'

Duas observações antes de rodar. Primeiro, $HIAPI_BASE_URL é um placeholder — defina-o com a base URL da referência da API do HiAPI e confirme o segmento de caminho na mesma referência. Segundo, o flag -sS mantém a saída silenciosa mas ainda mostra erros, que é exatamente o que você quer ao depurar.

Como é uma resposta saudável: um objeto JSON contendo uma referência ou dados da imagem gerada, além de metadados da requisição. A estrutura exata está documentada na referência da API; não escreva código de parsing para uma estrutura que você ainda não observou. Salve a resposta real em um arquivo, para ter uma base factual:

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"krea-3/text-to-image","prompt":"A neon-lit alley after rain, cinematic still"}' \
  -o response.json

Depois inspecione-o com jq ou no seu editor. Esse arquivo é sua fixture de teste: quando você portar para Python, compare a saída. Se a resposta do Python for estruturalmente diferente de response.json, o problema está no seu código, não no modelo.

A razão de fazer isso primeiro com curl é a alavancagem de diagnóstico. Se a chamada curl tiver sucesso, sua chave está boa, a URL está correta e o identificador do modelo resolve — então qualquer falha posterior está no código da sua aplicação. Se a chamada curl falhar, o corpo do erro lhe dirá qual dos três deu problema, e você ainda não escreveu uma linha de código.

Assim que a requisição mínima funcionar, adicione um parâmetro por vez. Rode o curl novamente após cada adição. Guarde os payloads bem-sucedidos; eles se tornarão suas fixtures de entrada aceitas para testes.

A mesma requisição em Python

A versão em Python é deliberadamente entediante: mesma URL, mesmos cabeçalhos, mesmo corpo JSON. O foco é portabilidade — a estrutura de requisição que você validou no curl deve migrar para um script e depois para um serviço sem redesenho.

import os
import json
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"].rstrip("/")
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "krea-3/text-to-image"

def generate(prompt: str) -> dict:
    response = requests.post(
        f"{BASE_URL}/v1/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()

if __name__ == "__main__":
    result = generate(
        "A weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph"
    )
    print(json.dumps(result, indent=2))

Algumas escolhas deliberadas:

  • Use variáveis de ambiente, não literais. A chave nunca aparece no código-fonte. Se a variável estiver ausente, os.environ["HIAPI_API_KEY"] falhará ruidosamente na inicialização, o que é melhor do que um 401 confuso três camadas abaixo.
  • Chame raise_for_status() antes de fazer o parsing. Você quer que erros HTTP surjam como exceções, não como um KeyError quando você tenta ler um campo de um corpo de erro que por acaso é JSON.
  • Timeout generoso. Geração de imagem não é um endpoint instantâneo. Defina um timeout que reflita isso e trate-o explicitamente em produção (veja a seção de produção).
  • Use json= em vez de construir strings manualmente. Deixe a biblioteca serializar. Montar JSON na mão é exatamente a fonte de erros de vírgula final e de aspas.

Rode uma vez e compare a saída com o response.json capturado antes. As estruturas devem coincidir. Imprima a referência de imagem ou os dados de imagem decodificados conforme o que a resposta retornar — novamente, escreva código para a estrutura observada, não para uma suposta.

Como MODEL é uma constante, a mesma função generate() serve para qualquer modelo de imagem na plataforma. Esse é o retorno do modelo agregado: movê-lo para um serviço, adicionar um segundo modelo ou fazer testes A/B de saída são mudanças de parâmetro, não reescritas.

Controlar estilo fotográfico e estilo de ilustração

Estilo não é um interruptor; é a direção em que você empurra o modelo, e krea-3/text-to-image responde às mesmas alavancas que você usaria com um fotógrafo ou ilustrador: sujeito, meio, iluminação e vocabulário de ofício.

Puxar para o estilo fotográfico

A saída fotográfica depende principalmente de nomear o instrumento e suas consequências. Palavras que descrevem câmera, lente, filme e luz real funcionam melhor do que a palavra "realista".

  • Nomeie o meio e o método de captura: "fotografia 35mm", "retrato editorial", "still documental".
  • Nomeie a luz: "luz do dia nublada", "contraluz na hora dourada", "softbox única à esquerda da câmera".
  • Nomeie as imperfeições: "leve desfoque de movimento", "grão visível", "profundidade de campo rasa".

Compare "um pescador em um cais" com "um pescador envelhecido remendando uma rede em um cais ao amanhecer, luz nublada, fotografia 35mm, grão visível". O segundo prompt restringe o modelo à textura e à iluminação da fotografia, em vez de uma representação genérica.

Puxar para o estilo de ilustração

Ilustração depende de nomear a tradição, a qualidade da linha e a paleta — e muitas vezes de remover as pistas fotográficas que você acabou de aprender.

  • Nomeie o estilo: "ilustração vetorial flat", "tinta e aquarela", "ilustração editorial de meados do século", "line art isométrico".
  • Nomeie a linha: "traços limpos e uniformes", "traço solto e gestual".
  • Nomeie a paleta: "paleta contida de duas cores", "pastéis suaves".

Iterar, não predefinir

Trate o prompt como configuração ajustável. Mude uma dimensão por vez — substitua apenas a frase de meio, mantendo sujeito e iluminação iguais — para que você aprenda o efeito de cada token. Mantenha um breve registro das variantes de prompt e das saídas que elas produzem; esse registro vale mais do que qualquer biblioteca de presets, porque é calibrado para o seu modelo e o seu conteúdo.

Se a requisição expuser parâmetros além do prompt — tamanho, seed ou similares — ajuste-os depois de fixar o prompt, não antes. Mudar o prompt e três parâmetros ao mesmo tempo não lhe diz qual mudança fez efeito.

Diagnosticar erros comuns

A maioria das falhas na primeira chamada se encaixa em quatro categorias. Siga a lista de verificação em ordem; cada passo elimina uma camada.

Falhas de autenticação

Sintoma: 401 ou 403, com uma mensagem sobre credenciais ou permissões.

  • HIAPI_API_KEY está realmente definida no shell que executa o comando? echo $HIAPI_API_KEY — uma string vazia parece muito com uma chave errada.
  • O cabeçalho é exatamente Authorization: Bearer <key>? Faltar Bearer, aspas extras ou uma quebra de linha colada na chave causam falha.
  • A chave foi revogada ou está restrita a outro ambiente? Em caso de dúvida, regenere e teste novamente com curl.

Payload de requisição malformado

Sintoma: 400, com uma mensagem sobre corpo, campos ou parsing de JSON.

  • Valide o JSON antes de enviar. No curl, uma única aspas não escapada dentro do prompt quebra o corpo. Em Python, json= cuida disso para você — mais um motivo para preferi-lo.
  • Verifique se há Content-Type: application/json.
  • Confira os nomes dos campos contra a referência da API. Um valor com grafia correta sob o nome de campo errado ainda dá 400.
  • Volte ao payload mínimo — apenas modelo e prompt — confirme que funciona e depois adicione campos um a um.

Identificador de modelo errado

Sintoma: 404, ou 400 indicando modelo desconhecido ou indisponível.

  • Compare sua string caractere por caractere com krea-3/text-to-image. O prefixo de namespace, o hífen e os segmentos de caminho importam.
  • Verifique se espaços acidentais ou aspas tipográficas foram introduzidos ao copiar e colar da documentação.
  • Confirme que o valor não está sendo sobrescrito por um padrão de configuração em algum lugar do código.

Respostas de taxa e cota

Sintoma: 429, ou uma mensagem sobre limite ou saldo insuficiente.

  • Faça backoff e tente novamente após um breve atraso, em vez de martelar o endpoint.
  • Verifique seu uso e saldo no painel.
  • Se isso acontecer durante o desenvolvimento, procure um loop de retry que dispara mais rápido do que você imaginava — uma requisição que falha dentro de um bloco try combinada com retries agressivos esgota limites rapidamente.

Se nada acima resolver, capture o ID de requisição completo e o corpo do erro da resposta e envie ao suporte. Corpos de erro em APIs agregadas costumam ser específicos o suficiente para apontar o problema; o erro é parafraseá-los em vez de colá-los.

Colocar em produção

Sua requisição agora é um protótipo. Quatro práticas a transformam em algo que pode rodar continuamente.

Tratar erros por categoria, não por string

Mapeie códigos de status HTTP para comportamentos: erros de autenticação são defeitos de configuração e devem acionar alguém; erros de payload 4xx são defeitos de código e devem fazer a requisição falhar ruidosamente; 429 e 5xx são transitórios e devem ser repetidos com backoff exponencial e jitter. Nunca repita um 400 — você só gastará cota para confirmar o mesmo defeito. Defina timeouts explícitos e trate timeouts como transitórios.

if response.status_code == 429 or response.status_code >= 500:
    raise TransientError(response.status_code)
response.raise_for_status()

Registrar prompts e versioná-los

Toda imagem gerada deve ser rastreável até o prompt exato que a produziu. Armazene o prompt junto com o identificador do modelo, os parâmetros e o ID de requisição da resposta. Trate o texto do prompt como configuração versionada — uma string prompt_v3 commitada em um arquivo de configuração, não um literal enterrado em uma função. Quando a qualidade da saída mudar, você precisa saber se foi o prompt, os parâmetros ou o modelo que mudou.

Manter o nome do modelo na configuração

krea-3/text-to-image deve aparecer apenas uma vez, em uma constante ou entrada de configuração. Esse é o retorno do modelo agregado: trocar de modelo, rodar comparações ou fazer rollback se tornam mudanças de configuração, não a implantação de um novo caminho de código. Também torna trivial rotear diferentes cargas de trabalho para diferentes modelos no futuro.

Testar contra fixtures

Salve as respostas bem-sucedidas capturadas neste tutorial como fixtures. Garanta que seu código de parsing consiga lidar com elas e use os corpos de erro registrados para testar o mapeamento de erros. Você descobrirá desvios na estrutura de resposta antes dos seus usuários.

Comece pela chamada curl mínima, confirme a estrutura da resposta, porte-a tal e qual para Python e então itere o prompt uma dimensão por vez — e consulte a referência da API do HiAPI para detalhes de endpoint que podem mudar.

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