Blogue

Tutorial

Como chamar fibo-2.0/text-to-image pela API do HiAPI: prática com curl e Python

Nov 13, 2026
Imagem de capa: planos de vidro translúcido sobrepostos sobre um fundo cinza-azulado claro, refratando faixas azuis contidas, formando uma composição geométrica abstrata.
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 POST define 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-image no 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_KEY passa 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/json informa 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=payload faz o requests serializar 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=60 torna 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, size e n como 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 →

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