Blogue

Tutorial

Como chamar fibo-gen-1.5/text-to-image via HiAPI: guia com curl e Python

Nov 12, 2026
Arte de capa com pontos de meio-tom verde-menta formando um gradiente de densidade suave sobre um fundo quase preto.
Nesta página

Construindo uma requisição funcional com curl

fibo-gen-1.5/text-to-image é um modelo de geração de imagem a partir de texto hospedado, acessado pelo padrão padrão de requisição da HiAPI. Esse detalhe é mais importante do que parece à primeira vista: você não precisa baixar pesos, montar uma GPU nem aprender um SDK específico do modelo. Basta enviar uma requisição HTTP com o identificador do modelo e o prompt, e então receber o resultado da imagem. O trabalho de integração se concentra em três pontos — como projetar o prompt, quais parâmetros definir e como tratar a resposta.

Antes de escrever qualquer código, há algumas premissas que você pode adotar com segurança:

  • Autenticação unificada. Toda chamada à HiAPI carrega sua chave de API no cabeçalho da requisição. Não existe um fluxo de autenticação específico por modelo.
  • O modelo é selecionado pelo nome. fibo-gen-1.5/text-to-image vai no campo de modelo do corpo da requisição e deve ser escrito exatamente assim, incluindo o sufixo /text-to-image.
  • Do ponto de vista do chamador, a geração é síncrona. Você envia a requisição, aguarda e recebe a saída. O orçamento de timeout deve refletir a latência real de geração, não a suposição de retorno imediato.
  • A resposta é estruturada. Você recebe um envelope JSON, não um bloco de dados binários brutos, portanto precisa analisá-lo antes de usar a imagem.

Se você já integrou qualquer outro modelo da HiAPI, isso vai parecer familiar. Se este é o seu primeiro, o padrão que você aprender aqui se transfere diretamente para todo o restante da plataforma. O conhecimento realmente específico do modelo está na escolha de parâmetros, que este guia aborda mais adiante.

Executando a mesma chamada em Python

Comece com a chamada mínima que funciona. Exporte a chave para evitar que ela entre em texto claro no histórico do shell:

export HIAPI_API_KEY="your_api_key_here"

Em seguida, envie a requisição:

curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fibo-gen-1.5/text-to-image",
    "prompt": "a weathered fisherman mending a net on a wooden dock at dawn, overcast light, 35mm photograph",
    "size": "1024x1024",
    "n": 1
  }'

Há três pontos que merecem destaque, pois são onde as tentativas de “copiar, colar e torcer” costumam falhar:

  1. A string do modelo deve ser exata. fibo-gen-1.5/text-to-image — não fibo-gen-1.5, nem uma variante de maiúsculas e minúsculas. Qualquer desvio retorna um erro do tipo modelo não encontrado, em vez de um fallback silencioso.
  2. A chave vai no cabeçalho Authorization como bearer token. Não a coloque no corpo da requisição nem na query string.
  3. Content-Type: application/json é obrigatório. Sem ele, alguns proxies e gateways corrompem o payload antes que ele chegue à API.

Se quiser ver exatamente o que é retornado — incluindo os cabeçalhos de resposta —, adicione -i à chamada curl. Esse é o hábito de depuração mais útil quando a resposta parece vazia: ele mostra se você recebeu um 200 com corpo de resposta de formato anômalo ou um status não-2xx que precisa ser tratado. Durante a exploração, use o pipe jq . para formatar a saída JSON.

Depois do primeiro sucesso, troque o prompt e execute novamente. Manter o restante da chamada inalterado isola as mudanças de prompt das mudanças estruturais.

Levando para produção

A passagem de um script funcional para uma integração confiável está sobretudo nas partes maçantes. Lista de verificação:

  • A chave não entra no código. Carregue-a de variáveis de ambiente ou de um gerenciador de segredos, nunca faça commit dela e faça rotação no ciclo que você realmente conseguir manter. Use chaves diferentes para desenvolvimento e produção, para que o vazamento da chave de desenvolvimento não derrube o tráfego em produção.
  • Timeouts explícitos e justificados. Defina o limite com base na latência de geração observada na sua carga de trabalho, não por chute. Registre o tempo real de cada chamada para fundamentar esse número.
  • Retentativas limitadas e seletivas. Para falhas transitórias — timeouts, situações de limite de taxa —, use backoff exponencial com um teto rígido de tentativas. Nunca repita payloads malformados nem falhas de autenticação; elas falharão sempre da mesma forma e desperdiçarão sua cota.
  • A saída é validada antes de ser confiada. Verifique se o número de bytes decodificados atinge uma quantidade razoável e se o arquivo abre como uma imagem válida. Um arquivo de zero bytes ou truncado que chega ao CDN é pior do que um erro direto na etapa de geração.
  • Toda geração é registrada. Armazene o prompt, os parâmetros, a resposta e o carimbo de data/hora juntos. Isso possibilita reprodutibilidade e atribuição de custos no futuro.
  • A chamada fica encapsulada atrás de uma função, não espalhada. Usar um único generate() significa que você só precisa corrigir a lógica de retentativa, os timeouts e o registro de logs em um único lugar.

Primeiro faça uma requisição limpa a fibo-gen-1.5/text-to-image com curl, depois porte para Python e, em seguida, adicione a camada operacional ao redor. O formato da requisição nunca muda — o que muda é apenas a proteção que você constrói em torno dela.

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