Tutorial
Como chamar fibo-gen-1.5/text-to-image via HiAPI: guia com curl e Python
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-imagevai 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:
- A string do modelo deve ser exata.
fibo-gen-1.5/text-to-image— nãofibo-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. - A chave vai no cabeçalho
Authorizationcomo bearer token. Não a coloque no corpo da requisição nem na query string. 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 →-
Tutorial
Guia prático do gpt-6.2-sol: 5 usos de alto valor de modelos de texto nos negócios
-
Tutorial
Guia prático do gpt-6.2-astra: pontos de integração e implementação em 5 cenários de texto de alto valor
Uma lista de verificação do ponto de vista do desenvolvedor, da seleção de cenários à implementação em engenharia
-
Tutorial
Cenários práticos do Tripo H3.1: 5 usos de alto valor e pontos de implementação
De texto para 3D à reconstrução multivisão: escolha o modo e os parâmetros certos para cada cenário de negócio