gpt-image-2.5-flare para imágenes de producto de comercio electrónico: flujo de trabajo por lotes basado en la API de hiapi

La fotografía de producto suele ser la parte más lenta de la publicación de un catálogo: cada SKU requiere una sesión de estudio, cada fondo de temporada exige una nueva sesión, y cada regla de relación de aspecto de cada plataforma requiere otra sesión más. gpt-image-2.5-flare en hiapi condensa gran parte de ese trabajo en un único ID de modelo: puede generar imágenes de producto a partir de indicaciones de texto y también editar fotos existentes (reemplazar fondos, componerlas en escenas de estilo de vida, ajustar el tamaño para distintos canales) sin modificar el producto en sí. Esta guía lo demostrará con tres flujos de trabajo reales y salidas de API sin editar, y luego mostrará cómo aplicarlo por lotes a todo el catálogo en lugar de procesar una imagen a la vez.

Los productos que aparecen en las siguientes imágenes (una botella de vidrio verde etiquetada «MOSS» y una tetera de color azul cobalto etiquetada «AER») son accesorios conceptuales para demostrar esta técnica, no fotografías reales de clientes; sin embargo, cada imagen es una salida real y sin editar de la API de hiapi, no una simulación.

Por qué la clave es un único ID de modelo

gpt-image-2.5-flare maneja dos tareas distintas según lo que se le envíe:

• Omita image_urls y generará una imagen únicamente a partir de su indicación de texto (texto a imagen).
• Agregue image_urls y, en su lugar, editará la foto proporcionada (imagen a imagen): el mismo modelo, el mismo endpoint, el mismo precio.

Para un catálogo, esto es más importante de lo que parece: ya sea que esté fotografiando un producto por primera vez o reutilizando fotos existentes, no tendrá que alternar entre dos ID de modelo ni entre dos esquemas de precios. Otros dos detalles lo hacen especialmente adecuado para el procesamiento por lotes:

• Niveles de calidad, no un costo fijo único. Puede elegir low / medium / high / xhigh / max por solicitud, de modo que un lote de miniaturas de 500 SKU y una docena de imágenes principales para la página de inicio no tienen que facturarse al mismo costo por imagen.
• Relaciones de aspecto flexibles. Puede elegir relaciones como 1:1, 4:5, 9:16 o 16:9 en cada solicitud, de modo que la misma imagen de producto se pueda recortar para una cuadrícula cuadrada de marketplace, un feed móvil vertical o un banner ancho sin volver a fotografiar.

Cada llamada se realiza a través de la API de tareas asíncronas de hiapi: POST /v1/tasks envía la tarea y luego se consulta GET /v1/tasks/{id} (o se usa un callback) hasta que el estado sea success. No existe una llamada síncrona que «devuelva la imagen directamente en la respuesta»: tanto la generación como la edición tardan varios segundos.

Paso 1: Genere desde cero una toma de estudio limpia

Comience con una foto de estudio simple y bien iluminada: este es el material base que editará en los pasos siguientes.

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_task(prompt, quality="medium", aspect_ratio="1:1", image_urls=None, idempotency_key=None):
    payload = {"model": "gpt-image-2.5-flare",
               "input": {"prompt": prompt, "quality": quality, "aspect_ratio": aspect_ratio}}
    if image_urls:
        payload["input"]["image_urls"] = image_urls
    headers = dict(HEADERS)
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
    resp = requests.post(BASE, headers=headers, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id, timeout_s=300, poll_every=5):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]  # download or re-upload immediately — it expires
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


studio_shot_url = wait_for_task(create_task(
    "Photorealistic square studio product photograph. Center exactly one translucent forest-green "
    "glass perfume bottle with a brushed silver cylindrical cap on a pale ivory stone pedestal. A "
    "small rectangular cream label reads \"MOSS\" in a thin serif font. Soft diffused studio lighting, "
    "seamless pale warm-gray background, subtle reflection, no props, no text elsewhere in frame.",
    quality="medium",
    aspect_ratio="1:1",
))

quality="medium" es un valor predeterminado razonable para la primera pasada; todas las imágenes de este artículo usan el mismo nivel. Solo eleve SKU individuales a high cuando el detalle adicional justifique el costo (consulte la tabla de precios a continuación).

Paso 2: Rediseñe el fondo sin regenerar el producto

Este es el flujo de trabajo que realmente ahorra trabajo en el catálogo: vuelva a pasar la toma de estudio como image_urls y describa solamente el cambio que desea; el producto en sí se mantiene idéntico píxel por píxel —la misma forma de botella, el mismo tapón, la misma etiqueta— mientras cambia el fondo.

seasonal_variant_url = wait_for_task(create_task(
    "Edit the supplied product photograph. Change ONLY the seamless background from pale warm gray "
    "to muted terracotta orange. Preserve the exact bottle shape and green glass color, the silver "
    "cap, the cream label and all its text, the lighting direction, and the camera angle exactly.",
    quality="medium",
    aspect_ratio="1:1",
    image_urls=[studio_shot_url],
))

El mismo patrón se aplica a un producto completamente distinto: aquí hay una tetera de color azul cobalto a la que se le reemplazó el fondo por un telón de estudio cálido color durazno, generado de la misma manera:

Este es el núcleo de una tarea de «renovación de temporada» o «tema de nuevo mercado»: una llamada de edición por SKU, el producto no se modifica y el fondo cambia. Ejecútelo 500 veces y habrá renovado el tema de todo el catálogo sin volver a fotografiar.

Paso 3: Componga el producto en escenas de estilo de vida

Las tomas de estudio son adecuadas para las cuadrículas de marketplace; las escenas de estilo de vida venden el producto en una landing page o en un anuncio. El mismo patrón de edición, con una indicación más ambiciosa: el modelo colocará el producto exacto en un escenario del mundo real verosímil, no solo cambiará el color del fondo.

lifestyle_url = wait_for_task(create_task(
    "Create a photorealistic square lifestyle product photograph using the supplied blue kettle as "
    "the exact product reference. Keep the original cobalt-blue kettle, black handle and base, "
    "brushed-metal spout and lid, black knob, and all lettering completely unchanged. Place it on a "
    "sunlit kitchen countertop with soft natural morning light, a few blurred kitchen props in the "
    "background, shallow depth of field.",
    quality="medium",
    aspect_ratio="1:1",
    image_urls=["<your kettle product photo URL>"],
))

Mantenga el lenguaje restrictivo en cada indicación de edición («keep the original ... completely unchanged»): es exactamente lo que impide que el modelo desplace el producto mientras cambia todo lo que lo rodea.

Automatización por lotes para un catálogo completo

Una sola llamada de edición es útil; a escala de catálogo, el valor está en ejecutar el mismo patrón para cada SKU sin intervención manual. Esta es la estructura que funciona en producción:

import concurrent.futures
import csv

QUALITY_BY_USE = {"thumbnail": "low", "listing": "medium", "hero": "high"}


def process_row(row):
    idem_key = f"{row['sku']}-{row['use']}-{row['background']}"
    prompt = (
        f"Edit the supplied product photograph. Change ONLY the seamless background to "
        f"{row['background']}. Preserve the exact product shape, color, materials, label text, "
        f"lighting direction, and camera angle."
    )
    try:
        task_id = create_task(
            prompt,
            quality=QUALITY_BY_USE[row["use"]],
            aspect_ratio=row["aspect_ratio"],
            image_urls=[row["source_photo_url"]],
            idempotency_key=idem_key,
        )
        return row["sku"], wait_for_task(task_id)
    except Exception as exc:
        return row["sku"], f"ERROR: {exc}"


with open("catalog.csv") as f:
    rows = list(csv.DictReader(f))  # sku,source_photo_url,background,use,aspect_ratio

with concurrent.futures.ThreadPoolExecutor(max_workers=4) as pool:
    results = list(pool.map(process_row, rows))

Cuando se procesa más de un puñado de imágenes, conviene tener en cuenta lo siguiente:

• Clave de idempotencia por fila. Envíe un encabezado Idempotency-Key distinto para cada SKU/variante, de modo que una solicitud reintentada tras un tiempo de espera no cree —ni facture de nuevo— una tarea duplicada.
• Limite la concurrencia; no lo envíe todo de una vez. Un grupo de subprocesos pequeño (o un semáforo asíncrono) evita alcanzar los límites de velocidad; ante un 429, retroceda y reintente en lugar de tratarlo como un fallo definitivo.
• Elija el nivel de calidad según el uso de la imagen, no con un criterio uniforme: las miniaturas y las cuadrículas de listado suelen bastar con low/medium, mientras que las imágenes principales de la página de inicio o las creatividades publicitarias merecen high o xhigh.
• Derive distintas relaciones de aspecto a partir de la misma imagen fuente ya editada, no de la original: ejecute primero una vez la edición de reemplazo de fondo y luego solicite versiones recortadas en 1:1, 4:5 y 9:16 a partir de ese resultado, para que cada canal muestre exactamente la misma presentación del producto.
• Descargue o vuelva a subir inmediatamente las URL de salida. Las salidas de las tareas caducan; no use URL temporales como fuente permanente de sus imágenes.

Precios

gpt-image-2.5-flare se factura por el número de imágenes de salida, según el nivel de calidad, con la misma tarifa tanto si se genera desde cero como si se edita:

Calidad	Precio por imagen
low	$0.0172
medium	$0.0672
high	$0.1829
xhigh	$0.3572
auto	$0.3572
max	$0.7143

En el nivel medium, renovar el tema de un catálogo de 500 SKU con una edición de reemplazo de fondo por producto cuesta aproximadamente $33.60. Consulte la página de precios para ver la tabla de tarifas completa y actualizada de todos los modelos.

Preguntas frecuentes

¿La edición alterará mi producto por accidente? Limite la indicación de edición a un único cambio («change ONLY the background...») y enumere explícitamente lo que debe permanecer inalterado (forma, color, texto de la etiqueta, ángulo de cámara). Los ejemplos anteriores muestran que el producto se mantiene sin cambios en cada edición.

¿El mismo modelo puede generar y editar? Sí: gpt-image-2.5-flare es un único ID de modelo. Incluya image_urls para editar una foto existente; omítalo para generar solo a partir de la indicación.

¿Cuántas imágenes de origen se pueden pasar en una llamada de edición? Se pueden pasar hasta 16 a través de image_urls, aunque la mayoría de las ediciones de catálogo de productos solo necesitan una: la foto que desea rediseñar.

¿Cómo evito la doble facturación al reintentar? Envíe un encabezado Idempotency-Key único para cada solicitud. Una solicitud reintentada con la misma clave devuelve la tarea original en lugar de crear una nueva.

Lecturas relacionadas

Si está configurando su primera llamada, comience con la guía de la API de gpt-image-2.5-flare para obtener un ejemplo mínimo funcional y conocer más a fondo el ciclo de vida de las tareas asíncronas. Para más patrones de indicaciones más allá de la fotografía de producto, consulte Indicaciones de GPT Image 2.5 Flare: recetas para copiar y pegar con salidas reales. Los parámetros y el esquema completos están en la página del modelo, y las convenciones generales de la API (autenticación, consulta de tareas, callbacks) están en la documentación de hiapi.

¿Listo para probarlo en su propio catálogo? Obtenga una clave de API en el panel de hiapi y luego ejecute el ejemplo de toma de estudio anterior con su primera foto de producto.