Como usar bria-product-shot via API hiapi: curl, Python e uma requisição que funciona

bria-product-shot recebe uma foto de produto e retorna uma nova imagem que coloca o produto em diferentes cenários. Você pode descrever o cenário em inglês ou fornecer uma imagem de referência para que ele siga o estilo de fundo dessa imagem. Este guia mostra uma requisição executada de ponta a ponta no hiapi, além das regras de parâmetros que determinam se uma requisição é aceita.

Você precisa obter uma chave de API hiapi na página de API Keys do painel e ter uma URL de foto de produto publicamente acessível (JPEG, PNG ou WEBP, no máximo 12 MB).

Exemplo mínimo funcional (curl)

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bria-product-shot",
    "input": {
      "image_url": "https://your-cdn.example.com/serum-bottle.png",
      "prompt": "On a white marble countertop beside a window, soft morning light, a few green leaves in the background",
      "placement_type": "manual_placement",
      "manual_placement_selection": "bottom_center"
    }
  }'

A chamada de criação retorna imediatamente um ID de tarefa:

{"code":200,"data":{"taskId":"tk-hiapi-01M5K7TWWMM68ZDTERJN4QV8MW"},"message":"success"}

Faça polling em GET /v1/tasks/<taskId> até que data.status seja success ou fail. A resposta após a conclusão é semelhante a esta (o hostname de saída foi encurtado):

{
  "code": 200,
  "data": {
    "model": "bria-product-shot",
    "status": "success",
    "storage": "temp",
    "taskId": "tk-hiapi-01M5K7TWWMM68ZDTERJN4QV8MW",
    "output": [{"artifactId": "287064", "type": "image", "expireAt": 1793325686,
                "url": "https://temp.hiapi.ai/.../...-0.png"}]
  },
  "message": "success"
}

Versão em Python

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def product_shot(image_url: str, scene: str, position: str = "bottom_center") -> bytes:
    r = requests.post(API, headers=HEADERS, json={
        "model": "bria-product-shot",
        "input": {
            "image_url": image_url,
            "prompt": scene,
            "placement_type": "manual_placement",
            "manual_placement_selection": position,
        },
    }, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    for _ in range(60):
        d = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        if d["status"] == "success":
            # output URLs expire (about 7 days): download immediately
            return requests.get(d["output"][0]["url"], timeout=60).content
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(4)
    raise TimeoutError(task_id)

open("shot.png", "wb").write(product_shot(
    "https://your-cdn.example.com/serum-bottle.png",
    "On a white marble countertop beside a window, soft morning light, a few green leaves in the background",
))

Parâmetros principais

Campo	Descrição
image_url	Obrigatório. URL http(s) pública da foto do produto.
prompt	Descrição do cenário em inglês, com 1 a 1000 caracteres.
reference_image_url	Imagem de referência do cenário. Use este parâmetro ou prompt, apenas um dos dois, nunca ambos ao mesmo tempo.
placement_type	manual_placement (padrão) posiciona o produto em posições predefinidas; original mantém sua posição na foto.
manual_placement_selection	bottom_center (padrão), upper_left, upper_right, bottom_left, bottom_right, right_center, left_center, upper_center, center_vertical, center_horizontal. Válido apenas ao usar manual_placement.
original_quality	Válido apenas ao usar original: preserva as dimensões de entrada em vez de redimensionar para cerca de 1 MP.
fast	Padrão true. Desative para usar o modelo padrão; o preço é o mesmo.
optimize_description	Padrão true. Expande o texto do cenário; válido apenas ao usar prompt, não pode ser usado com imagem de referência.

O schema é fechado (additionalProperties: false) e possui regras entre campos, portanto combinações como prompt com reference_image_url, ou original com posição predefinida, são requisições inválidas.

Registro de testes e observações

O que foi executado contra a API em tempo real:

• Uma geração real foi feita com a requisição acima, mantendo fast no valor padrão. A tarefa passou por handling e archiving, atingindo success cerca de 26 segundos após a criação.
• Para entrada quadrada, a saída foi um PNG 1024×1024 (cerca de 1 MB), o que está de acordo com a descrição na página do modelo: para entradas quadradas, as posições predefinidas são medidas em 1024×1024.
• Um valor de erro intencional "manual_placement_selection": "middle" foi rejeitado na criação, retornando HTTP 400 e error_code: INVALID_REQUEST. A mensagem de erro lista todas as dez posições permitidas, então você pode mostrá-la diretamente ao usuário sem esperar que a tarefa falhe.

Dicas práticas:

• Baixe a saída imediatamente. Cada saída traz um timestamp expireAt (horário Unix após a conclusão, cerca de sete dias); armazene a imagem no seu próprio storage.
• Preço fixo por imagem. Segundo a página do modelo, o texto do cenário, a imagem de referência, a posição de posicionamento e o modo rápido não alteram o preço. Consulte os números atuais na página de preços em vez de codificá-los diretamente.
• Este guia executou apenas uma geração, portanto a página não faz nenhuma afirmação sobre a qualidade em diferentes categorias de produtos. Teste as imagens do seu próprio catálogo antes de usar em lote.

Recomendações para produção

• Crie a tarefa, armazene o taskId e faça polling com algumas novas tentativas em caso de erros temporários de rede. Faça polling novamente do id salvo em vez de criar uma nova tarefa, pois uma nova tarefa será cobrada novamente.
• Para filas, valide manual_placement_selection no cliente com base nos dez valores acima, para que entradas inválidas nunca cheguem à API.

Páginas relacionadas

• Página do modelo Bria Product Shot: preços em tempo real, formulário de entrada e playground.
• Página do modelo Bria Eraser: remove objetos com uma máscara, o que é uma tarefa diferente de inserir um produto em um novo cenário.
• Navegue por todos os modelos de imagem
• Guia da API 851-labs de remoção de fundo: se o fundo da sua foto de origem estiver poluído, recorte o produto primeiro.
• Como usar a API FLUX.2 imagem para imagem

Perguntas frequentes

Posso usar uma imagem de referência em vez de um prompt de texto? Sim. Envie reference_image_url e omita prompt. Não envie ambos ao mesmo tempo, nem envie optimize_description junto com a imagem de referência.

Quantas imagens uma chamada retorna? Uma. A página do modelo informa que cada execução gera uma imagem.

O produto mantém sua posição na minha foto? Somente com placement_type: "original". O manual_placement padrão o reposiciona para a posição predefinida escolhida.