Tutorial
Como chamar fibo-2.0/text-to-image pela API do HiAPI: prática com curl e Python
Nesta página
O que este tutorial constrói
Este é um guia prático que leva você a realmente obter uma imagem de volta do fibo-2.0/text-to-image no HiAPI. Ao final, você terá duas coisas que pode executar imediatamente: um comando curl que gera uma requisição válida de geração de imagem, e uma pequena função Python que faz a mesma coisa e retorna o resultado para processamento posterior.
Vamos avançar na ordem em que a maioria dos desenvolvedores realmente trabalha. Primeiro, confirme que o ambiente e as credenciais estão prontos. Depois, leia o corpo da requisição campo por campo, para que você entenda claramente o que cada parte controla. Em seguida, envie a chamada com curl, para provar que endpoint, chave e payload estão consistentes. Só depois disso portamos a mesma requisição para Python, onde o trabalho realmente interessante — analisar a resposta, tratar falhas, encapsular em uma função — começa.
O objetivo não é enumerar todos os parâmetros possíveis, mas dar a você uma forma de requisição que você entende completamente, para que possa ajustar o prompt, as dimensões de saída e o código ao redor para o seu caso de uso, sem adivinhar.
Antes de enviar a primeira requisição
Antes da primeira chamada bem-sucedida, três condições precisam ser atendidas.
Conta HiAPI e chave de API
Requisições para fibo-2.0/text-to-image exigem autenticação. Gere uma chave de API na sua conta HiAPI e mantenha-a longe do controle de versão. Os exemplos abaixo leem a chave de uma variável de ambiente em vez de codificá-la diretamente — faça isso desde o primeiro dia, porque adicionar tratamento de chave depois é trabalhoso.
export HIAPI_API_KEY="your-api-key-here"
Uma ferramenta capaz de enviar requisições HTTP
Para a parte prática com curl, você precisa de curl na sua máquina. Ele vem com macOS e a maioria das distribuições Linux; no Windows, também está disponível nas versões atuais e no Windows Terminal. Para a parte Python, você precisa de Python 3 e da biblioteca requests, a forma mais comum de fazer chamadas HTTP a partir de scripts. Se ainda não instalou:
pip install requests
Clareza sobre o que você quer gerar
Tenha um prompt pronto. Modelos de imagem reagem fortemente a descrições específicas e explícitas — sujeito, estilo, iluminação e composição — então uma linha de ideia geralmente basta para começar a testar. Você vai continuar refinando depois de ver o primeiro resultado; este é o ciclo normal.
Com esses três itens prontos, tudo o mais gira em torno do corpo da requisição.
Analisando a requisição campo por campo
A chamada de fibo-2.0/text-to-image é uma requisição POST com corpo JSON. O corpo é pequeno: um prompt e configurações que moldam a saída. Em vez de memorizar o payload completo, entenda cada campo, para que você possa modificá-lo conscientemente.
Identificador do modelo
O caminho do endpoint já indica o modelo: fibo-2.0/text-to-image. Na maioria dos casos, você não precisa passar uma string de modelo adicional — a rota que você chama determina qual modelo é executado. Se sua integração suportar roteamento por um endpoint compartilhado, coloque o nome do modelo em uma constante de configuração, para que você possa trocá-lo sem alterar o ponto de chamada.
Prompt
Esta é a entrada central: a descrição textual da imagem que você deseja. Trate-a como uma especificação, não como um desejo. Declarar sujeito, estilo visual e composição dá ao modelo muito mais informação útil do que conceitos abstratos. Coloque o prompt em uma variável ou arquivo separado, para que você possa iterar rapidamente sem reescrever o código da requisição.
Configurações de saída
Requisições de imagem geralmente carregam um pequeno conjunto de controles de saída — mais comumente as dimensões ou a proporção da imagem gerada, e a quantidade se você quiser vários resultados. Use os nomes de campo documentados para fibo-2.0/text-to-image na referência de modelos do HiAPI; o payload de exemplo abaixo usa esses nomes canônicos. Se uma configuração não estiver documentada para o modelo, omita-a em vez de adivinhar — campos desconhecidos são uma fonte comum de erros de validação.
O que não colocar no corpo da requisição
Não coloque a chave de API no corpo JSON. A autenticação pertence aos cabeçalhos. Manter as credenciais fora do payload significa que o corpo pode ser registrado e comparado com segurança durante a depuração — você vai perceber o valor disso na primeira vez que uma requisição falhar.
Uma requisição curl funcional
Abaixo está uma chamada completa. Substitua seu próprio prompt e execute-a em um shell onde HIAPI_API_KEY esteja definida.
curl -X POST "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "porto tranquilo ao amanhecer, névoa leve pairando sobre a água, composição ampla, estilo fotográfico",
"size": "1024x1024",
"n": 1
}'
O que cada parte faz
-X POSTdefine o método HTTP. A geração de imagem é uma operação de criação, então é POST, não GET.- A URL aponta para a rota
fibo-2.0/text-to-imageno host da API do HiAPI. Se sua conta usar uma URL base regional ou específica de projeto, substitua esse host e mantenha o caminho. Authorization: Bearer $HIAPI_API_KEYpassa sua chave a partir do ambiente. O shell expande a variável, então a chave nunca aparece como string literal no histórico do seu comando.Content-Type: application/jsoninforma ao servidor que o corpo é JSON. Sem isso, muitos gateways rejeitam a requisição antes mesmo de ela chegar ao modelo.-d '...'é o corpo JSON: o prompt, o tamanho solicitado e a quantidade de uma imagem.
Verificando o resultado
Execute o comando e observe primeiro a saída bruta. Uma chamada bem-sucedida retorna um documento JSON descrevendo a imagem gerada; uma chamada com falha retorna um objeto de erro. Antes de construir qualquer coisa em cima disso, confirme que você consegue distinguir os dois a olho nu. Se a resposta for grande, use uma ferramenta de formatação como jq para tornar a estrutura legível:
curl -s -X POST "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"porto tranquilo ao amanhecer","size":"1024x1024","n":1}' | jq .
Quando a chamada manual funciona, você eliminou credenciais e payload como suspeitos. Qualquer problema a partir daí está no seu código.
A mesma chamada em Python
A versão Python faz exatamente o que o comando shell faz, mas oferece lugares para validar entradas, tentar novamente e armazenar resultados. Mantenha-a pequena e explícita.
import os
import requests
API_URL = "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image"
def generate_image(prompt: str, size: str = "1024x1024", n: int = 1) -> dict:
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"prompt": prompt,
"size": size,
"n": n,
}
response = requests.post(
API_URL,
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=60,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = generate_image(
"porto tranquilo ao amanhecer, névoa leve pairando sobre a água, composição ampla, estilo fotográfico"
)
print(result)
Por que está escrito assim
- A chave é lida do ambiente dentro da função, então, se estiver ausente, a chamada falha ruidosamente na inicialização em vez de enviar uma requisição não autenticada.
json=payloadfaz orequestsserializar o corpo e definir o tipo de conteúdo corretamente. Não construa strings JSON manualmente em Python; isso introduz erros de aspas que só aparecem em tempo de execução.timeout=60torna falhas lentas explícitas. A geração de imagem não é instantânea, então escolha um tempo limite que você esteja disposto a esperar — mas sempre defina um.raise_for_status()transforma respostas 4xx e 5xx em exceções. É essa linha que impede que chamadas com falha sejam silenciosamente tratadas como sucesso.- A função recebe
prompt,sizeencomo parâmetros, para que o restante do seu programa possa chamá-la como qualquer outra função de biblioteca.
Execute o arquivo e você deverá ver a mesma estrutura JSON retornada pela chamada curl.
Lendo a resposta e tratando erros
Uma resposta bem-sucedida fornece um objeto JSON descrevendo a saída gerada. O detalhe que importa é a própria imagem gerada — normalmente uma URL ou referência que você pode baixar ou armazenar — além de quaisquer metadados que a API retorne sobre a requisição. Analise a resposta como dados; não a extraia com manipulação de strings. Se a forma não corresponder ao esperado na primeira vez que você inspecionar uma resposta ao vivo, verifique a referência do modelo antes de ajustar o analisador, porque adivinhar nomes de campo é exatamente como as integrações quebram silenciosamente.
Detectando falhas
Há três camadas de falha que vale a pena tratar intencionalmente.
Erros de transporte. A requisição nunca é concluída: falha de DNS, conexão redefinida, timeout. Em Python, eles aparecem como requests.exceptions, que são seguros para tentar novamente com backoff.
Status HTTP de erro. O servidor respondeu mas rejeitou a requisição. 401 geralmente significa chave ausente ou incorreta; erros de validação 4xx normalmente significam nome de campo ou valor errado; 429 significa que você enviou rápido demais; 5xx significa que algo deu errado no lado do servidor. raise_for_status() captura todos esses como um tipo de exceção, então inspecione a mensagem no corpo da resposta antes de decidir o que fazer.
Status 200 mas corpo inesperado. É por isso que você valida a estrutura em vez de supor. Verifique se os campos dos quais depende existem antes de usá-los e, mesmo com status 200, trate a ausência de uma referência de imagem como falha.
try:
result = generate_image("porto tranquilo ao amanhecer")
image = result.get("data", [{}])[0]
except requests.HTTPError as exc:
print("request failed:", exc.response.status_code, exc.response.text)
Hábito importante: nunca engula erros silenciosamente. Registre pelo menos o código de status e o corpo da resposta, porque esse par de informações indica se você deve corrigir o payload ou esperar e tentar novamente.
Rumo à produção
Depois que uma chamada única funciona e as falhas ficam visíveis, alguns pequenos hábitos fazem a integração se sustentar sob tráfego real.
Tente novamente apenas o que é seguro repetir
Erros de transporte, timeouts, respostas 429 e 5xx merecem nova tentativa com backoff exponencial e um limite de tentativas. Erros de validação e 401 não merecem — repetir uma requisição malformada só consome cota. Separe claramente esses dois grupos no tratamento de erros.
Mantenha a configuração fora do código
Coloque a URL base da API, o caminho do modelo, o tamanho padrão e o timeout em configuração, em vez de espalhá-los pelas funções. Quando você migrar do ambiente de teste para outro ambiente, ou depois experimentar um modelo similar, basta alterar um único lugar.
Registre requisições e respostas, mas remova as chaves
Registre o prompt, os parâmetros, o código de status e a resposta truncada. Nunca registre a chave de API. Assim você consegue responder, uma semana depois, "por que esta imagem voltou errada" sem precisar reproduzir o problema.
Valide a entrada antes de enviar
Verifique se o prompt não está vazio e está dentro de um comprimento razoável, e se size e n correspondem aos valores documentados do modelo. Capturar valores errados localmente é mais rápido e mais barato do que uma ida e volta.
Armazene resultados, não apenas imprima
As referências de imagem geradas podem ser temporárias. Como parte do mesmo trabalho, baixe ou copie a saída para o seu próprio armazenamento e registre qual prompt e parâmetros a produziram. Esse registro torna a regeneração e a auditoria possíveis.
Encapsule fibo-2.0/text-to-image na pequena função generate_image deste tutorial e faça o restante da sua aplicação depender dessa função, em vez de chamadas HTTP brutas. Quando você estiver pronto para variar prompts em escala, a referência de modelos do HiAPI é onde você confirma os parâmetros suportados antes de expandir a interface.
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