Como usar a API FIBO 1.5? Gere e edite em 5 minutos

TL;DR

• FIBO 1.5 é um par de endpoints de «geração + edição»: fibo-gen-1.5/text-to-image gera imagens fotorrealistas a partir de texto (o texto dentro da imagem também é renderizado com precisão) e fibo-edit-1.5/image-to-image edita a imagem com uma frase (até 4 imagens de referência e também edição local com máscara). Abra a página do modelo Gen para testar; novos usuários ganham 200 créditos ao se cadastrar.
• Mesmo preço nos dois: $0.0575 por imagem; uma pipeline de gerar e depois editar custa $0.115 (ver página de preços).
• A chamada passa pelo endpoint /v1/tasks da HiAPI: submeta a tarefa e receba o taskId, depois consulte o resultado; o campo de instrução do endpoint de edição chama-se instruction, não prompt.

O que ele faz

• Imagem fotorrealista + texto preciso: textos na imagem, como rótulos de produtos e letreiros de loja, são escritos letra por letra (o rótulo do exemplo abaixo é NOIR 07).
• Edição com uma frase: no Edit, use instruction para descrever o que mudar; o que não for mencionado, como pose, rosto e fundo, permanece inalterado.
• Composição com até 4 imagens: troca de roupa, troca de fundo, produto em cena; referencie em image_urls pela ordem.
• Máscara para alterar só uma região: branco = área a alterar, preto = manter.

Abaixo, um resultado real do Gen:

Luxury product photo of an amber glass perfume bottle on wet black marble, gold cap, soft rim light, droplets on the glass, the label reads 'NOIR 07' in elegant serif letters

(Em português: foto de produto de perfume de luxo: frasco de vidro âmbar sobre mármore preto molhado, tampa dourada, luz de contorno suave, gotas de água no vidro, rótulo escrito NOIR 07. Proporção escolhida: 4:5.)

fibo-gen-1.5/text-to-image, 4:5, 768×960, $0.0575.

Gerar com este prompt →

Como escolher entre os dois endpoints

	fibo-gen-1.5/text-to-image	fibo-edit-1.5/image-to-image
O que faz	Gera imagens fotorrealistas a partir de texto	Modifica uma imagem existente com uma frase
Entrada obrigatória	prompt	image_urls (1–4 imagens) + instruction
Preço	$0.0575/imagem	$0.0575/imagem
Parâmetros especiais	aspect_ratio com 9 opções, seed (padrão 5555)	mask_url máscara, seed (padrão 5555)
Indicado para	Criar novas imagens, materiais com texto	Troca de roupa/fundo/composição, ajustes locais

Pipeline típica: Gen cria a imagem base → Edit transforma em um conjunto de imagens (troca de fundo, de cor, adiciona elementos). Para escolher prompts por cenário, veja o guia de prompts.

Duas formas de começar

3 passos no navegador: abra a página do modelo → cole o prompt, escolha a proporção → clique em gerar, $0.0575 por imagem.

3 passos via API: POST /v1/tasks para submeter → receba o taskId → GET /v1/tasks/<taskId> até success e baixe.

curl: a primeira imagem

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "fibo-gen-1.5/text-to-image",
  "input": {
    "prompt": "Luxury product photo of an amber glass perfume bottle on wet black marble, gold cap, soft rim light, droplets on the glass, the label reads '"'"'NOIR 07'"'"' in elegant serif letters",
    "aspect_ratio": "4:5",
    "seed": 2026
  }
}'

Endpoint de edição: troque model por fibo-edit-1.5/image-to-image, escreva a instrução em instruction e referencie as imagens pela ordem (prova virtual com composição de duas imagens):

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "fibo-edit-1.5/image-to-image",
  "input": {
    "image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/78f963cb21d0242c.jpg",
      "https://static.hiapi.ai/gallery/2026/10/36246b7cabde4a1a.jpg"
    ],
    "instruction": "Dress the woman in image 1 with the mustard corduroy jacket from image 2, worn open over her white t-shirt. Keep her pose, face and the studio background.",
    "aspect_ratio": "3:4"
  }
}'

Edição local com máscara: mask_url só aceita 1 imagem e branco = área a alterar (o oposto do Ideogram 4.5 Edit):

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "fibo-edit-1.5/image-to-image",
  "input": {
    "image_urls": ["https://static.hiapi.ai/gallery/2026/10/d9037da1559e78a6.jpg"],
    "mask_url": "https://static.hiapi.ai/gallery/2026/10/cae371f9e4689db5.png",
    "instruction": "Replace the floor under the sneaker with light wooden planks."
  }
}'

Python: submeter, consultar e baixar

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "fibo-gen-1.5/text-to-image",
    "input": {
        "prompt": "Luxury product photo of an amber glass perfume bottle on wet black marble, gold cap, soft rim light, droplets on the glass, the label reads 'NOIR 07' in elegant serif letters",
        "aspect_ratio": "4:5",
        "seed": 2026,
    },
}

resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # endereço temporário, baixe e salve o quanto antes
    img = requests.get(image_url, timeout=60)
    with open("output_image", "wb") as f:
        f.write(img.content)
    print("saved")

Tabela de parâmetros

fibo-gen-1.5/text-to-image

Campo	Obrigatório	Valores	Descrição
prompt	Sim	1–10000 caracteres	Descrição da imagem; coloque entre aspas o texto que deve aparecer (the label reads '…')
aspect_ratio	Não	1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 4:5 / 5:4 / 9:16 / 16:9, padrão 1:1	9 proporções com o mesmo preço
seed	Não	Inteiro, padrão 5555	Fixo mesmo sem enviar: mesmo prompt, mesmo resultado; para variar, troque o seed

fibo-edit-1.5/image-to-image

Campo	Obrigatório	Valores	Descrição
image_urls	Sim	1–4 imagens	A ordem importa; a instruction referencia pela ordem (image 1, image 2)
instruction	Sim	≥1 caractere	O que alterar; o que não for mencionado permanece inalterado
aspect_ratio	Não	As mesmas 9 opções acima	Só vale com 2 ou mais imagens; com uma única imagem, a saída mantém a proporção da original
mask_url	Não	Endereço da imagem	Apenas edição com imagem única; branco = alterar, preto = manter; o tamanho deve ser igual ao da imagem original
seed	Não	Inteiro, padrão 5555	Reproduz com a mesma entrada

Campos fora da tabela no corpo da requisição retornam 400 direto.

Erros que você vai encontrar (mensagens originais da API)

O que você fez	Retorno
Gen sem prompt	400 invalid input: prompt: missing required field "prompt"
seed do Gen enviado como string	400 invalid input: seed: got string, want integer
aspect_ratio escrito errado	400 invalid input: aspect_ratio: value must be one of '1:1', '2:3', '3:2', '3:4', '4:3', '4:5', '5:4', '9:16', '16:9'
Edit sem instruction	400 invalid input: instruction: missing required field "instruction"
Edit com 5 imagens	400 invalid input: image_urls: maxItems: got 5, want 4
Máscara com 2 imagens	400 (image_urls só aceita 1 imagem quando mask_url está presente)
Saldo insuficiente	402 insufficient account balance; top up and retry

Reenviar com o mesmo Idempotency-Key retorna 409 ou 422; troque por uma chave nova e tente de novo.

Atenção antes de ir para produção

• Callback: envie no nível superior do corpo "callback": {"url": "https://..."} para ser notificado automaticamente no estado final e evitar polling.
• Salve logo: output[0].url é um endereço temporário; baixe assim que receber.
• Cite a ordem das imagens na instrução: na composição com várias imagens, referencie com image 1 / image 2; a ordem é a de image_urls.
• Semântica preto e branco da máscara: no FIBO, branco = alterar, preto = manter; ao migrar scripts de outro modelo de edição, inverta a máscara primeiro.

Perguntas frequentes

Como se chama o campo de instrução da edição?

Chama-se instruction, não prompt; nome de campo errado gera erro de campo ausente.

Quantas imagens de entrada posso enviar no máximo?

No máximo 4; a quinta retorna 400 direto.

Para que serve o seed?

O padrão é 5555 e é fixo — a mesma entrada é reproduzida; para resultados diferentes, troque o seed explicitamente.

O preço e a forma de chamada dos dois endpoints são iguais?

São. Só muda o model e o campo input; geração e edição custam $0.0575 por imagem.

Próximo passo: pegue o prompt do perfume e gere uma imagem na página do modelo, depois use uma instruction para transformá-la na versão que você quer; para modelos por cenário, veja o guia de prompts.