Cómo usar bria-product-shot a través de la API de hiapi: curl, Python y una solicitud que funciona

bria-product-shot recibe una foto de producto y devuelve una nueva imagen que coloca el producto en diferentes escenarios. Puedes describir el escenario en inglés o proporcionar una imagen de referencia para que siga el estilo de fondo de esa imagen. Esta guía muestra una solicitud ejecutada de extremo a extremo en hiapi, así como las reglas de parámetros que determinan si la solicitud se acepta.

Necesitas obtener una clave de API de hiapi desde la página de API Keys del panel, así como una URL de foto de producto accesible públicamente (JPEG, PNG o WEBP, máximo 12 MB).

Ejemplo 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"
    }
  }'

La llamada de creación devuelve inmediatamente un ID de tarea:

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

Consulta repetidamente GET /v1/tasks/<taskId> hasta que data.status sea success o fail. La respuesta tras completarse es similar a esta (el nombre de host de salida está abreviado):

{
  "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"
}

Versión en 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 clave

Campo	Descripción
image_url	Obligatorio. URL pública http(s) de la foto del producto.
prompt	Descripción del escenario en inglés, de 1 a 1000 caracteres.
reference_image_url	Imagen de referencia del escenario. Usa este parámetro o prompt, solo uno de los dos, nunca ambos a la vez.
placement_type	manual_placement (predeterminado) coloca el producto en una posición predefinida; original mantiene su posición en la foto.
manual_placement_selection	bottom_center (predeterminado), upper_left, upper_right, bottom_left, bottom_right, right_center, left_center, upper_center, center_vertical, center_horizontal. Solo es válido cuando se usa manual_placement.
original_quality	Solo válido cuando se usa original: conserva las dimensiones de entrada en lugar de escalar a aproximadamente 1 MP.
fast	Predeterminado true. Desactívalo para usar el modelo estándar; el precio es el mismo.
optimize_description	Predeterminado true. Amplía el texto del escenario; solo válido cuando se usa prompt, no puede usarse junto con una imagen de referencia.

El esquema es cerrado (additionalProperties: false) y tiene reglas entre campos, por lo que combinaciones como prompt más reference_image_url, o original más una posición predefinida, son solicitudes no válidas.

Registro de pruebas y notas

Lo que se ejecutó contra la API en vivo:

• Se realizó una generación real con la solicitud anterior, manteniendo fast en su valor predeterminado. La tarea pasó por handling y archiving, y alcanzó success aproximadamente 26 segundos después de su creación.
• Para entradas cuadradas, la salida fue un PNG de 1024×1024 (aproximadamente 1 MB), lo que coincide con lo indicado en la página del modelo: para entradas cuadradas, las posiciones predefinidas se miden en 1024×1024.
• Un valor erróneo introducido deliberadamente, "manual_placement_selection": "middle", fue rechazado en el momento de la creación, devolviendo HTTP 400 y error_code: INVALID_REQUEST. El mensaje de error enumera las diez posiciones permitidas, por lo que puedes mostrarlo directamente al usuario sin esperar a que la tarea falle.

Consejos prácticos:

• Descarga la salida de inmediato. Cada salida incluye una marca de tiempo expireAt (hora Unix tras la finalización, aproximadamente siete días); almacena la imagen en tu propio almacenamiento.
• Precio fijo por imagen. Según la página del modelo, el texto del escenario, la imagen de referencia, la posición de colocación y el modo rápido no cambian el precio. Consulta las cifras actuales en la página de precios en lugar de codificarlas de forma fija.
• Esta guía ejecutó la generación una sola vez, por lo que la página no hace ninguna afirmación sobre la calidad en distintas categorías de productos. Antes de usarlo en lote, prueba primero con imágenes de tu propio catálogo.

Recomendaciones para producción

• Crea la tarea, guarda el taskId y consulta su estado reintentando varias veces ante errores de red temporales. Vuelve a consultar el ID guardado en lugar de crear una nueva tarea, ya que una nueva tarea se factura de nuevo.
• Para las colas, valida manual_placement_selection en el cliente según los diez valores anteriores, de modo que las entradas erróneas nunca lleguen a la API.

Páginas relacionadas

• Página del modelo Bria Product Shot: precios en vivo, formulario de entrada y playground.
• Página del modelo Bria Eraser: elimina objetos usando una máscara, una tarea distinta a colocar un producto en un nuevo escenario.
• Explorar todos los modelos de imagen
• Guía de la API de eliminación de fondo de 851-labs: si el fondo de tu foto de origen es desordenado, recorta primero el producto.
• Cómo usar la API de imagen a imagen de FLUX.2

Preguntas frecuentes

¿Puedo usar una imagen de referencia en lugar de un prompt de texto? Sí. Envía reference_image_url y omite prompt. No envíes ambos a la vez, ni envíes optimize_description junto con una imagen de referencia.

¿Cuántas imágenes devuelve una llamada? Una. La página del modelo indica que cada ejecución genera una imagen.

¿El producto mantiene su posición en mi foto? Solo cuando placement_type: "original". El valor predeterminado manual_placement lo recoloca en la posición predefinida elegida.