gpt-image-2.5-flare para imagens de produtos de e-commerce: fluxo de trabalho em lote com a API hiapi

A fotografia de produtos costuma ser a etapa mais lenta de um catálogo de e-commerce: uma sessão de estúdio para cada SKU, uma nova sessão para cada fundo sazonal e outra para cada regra de proporção de cada plataforma. O gpt-image-2.5-flare na hiapi condensa a maior parte desse trabalho em um único ID de modelo — ele tanto gera imagens de produtos a partir de prompts de texto quanto edita fotos existentes (substitui o fundo, insere em cenas lifestyle, ajusta dimensões para diferentes canais) sem alterar o produto em si. Este guia demonstra isso por meio de três fluxos de trabalho reais e saídas de API não editadas, e depois mostra como aplicá-lo em lote a todo o catálogo de produtos, em vez de uma imagem por vez.

Os produtos mostrados nas imagens abaixo (uma garrafa de vidro verde com o rótulo "MOSS" e uma chaleira azul-cobalto com o rótulo "AER") são adereços conceituais usados para demonstrar esta técnica, não fotografias reais de clientes — mas cada imagem é uma saída real e não editada da API hiapi, não uma simulação.

Por que o ponto-chave é um único ID de modelo

O gpt-image-2.5-flare lida com duas tarefas diferentes conforme o que você envia:

• Omita image_urls e ele gera a imagem apenas a partir do seu prompt de texto (texto para imagem).
• Adicione image_urls e ele passa a editar a foto fornecida (imagem para imagem) — mesmo modelo, mesmo endpoint, mesmo preço.

Para um catálogo de produtos, isso importa mais do que parece: seja para fotografar produtos pela primeira vez ou reaproveitar fotos existentes, você não precisa alternar entre dois IDs de modelo ou dois esquemas de preço. Outros dois detalhes o tornam especialmente adequado ao processamento em lote:

• Níveis de qualidade, não um custo fixo único. Você escolhe low / medium / high / xhigh / max por solicitação, então um lote de miniaturas de 500 SKUs e uma dúzia de imagens principais da página inicial não precisam ser cobrados pelo mesmo custo unitário.
• Proporções flexíveis. É possível escolher 1:1, 4:5, 9:16, 16:9 e outras proporções por solicitação, então a mesma imagem de produto pode ser recortada para uma grade quadrada de marketplace, um feed vertical de celular ou um banner largo, sem nova sessão de fotos.

Cada chamada passa pela API de tarefas assíncronas da hiapi: POST /v1/tasks envia a tarefa e depois você faz polling com GET /v1/tasks/{id} (ou usa callback) até o status ser success. Não há chamada síncrona que "retorna a imagem na resposta" — geração e edição levam alguns segundos.

Passo 1: gerar uma foto de estúdio limpa do zero

Comece com uma foto de estúdio simples e bem iluminada — esta é a base que você vai editar nos passos seguintes.

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"]  # baixe ou reenvie imediatamente — a URL expira
        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" é um padrão razoável para o primeiro processamento — todas as imagens deste artigo usam o mesmo nível. Eleve SKUs individuais para high apenas quando o detalhe extra justificar o custo (veja a tabela de preços abaixo).

Passo 2: redesenhar o fundo sem regerar o produto

Este é o fluxo de trabalho que realmente economiza esforço no catálogo: envie a foto de estúdio de volta como image_urls, descreva apenas a alteração desejada, e o produto em si permanece idêntico pixel a pixel — mesmo formato de garrafa, mesma tampa, mesmo rótulo — enquanto o fundo muda.

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],
))

O mesmo padrão se aplica a produtos completamente diferentes — aqui, uma chaleira azul-cobalto cujo fundo foi substituído por um fundo de estúdio em tom pêssego quente, gerado da mesma forma:

Este é o núcleo da tarefa de "renovação sazonal" ou "tema de novo mercado": uma chamada de edição por SKU, o produto fica intacto, o fundo muda. Execute 500 vezes e você terá um novo tema para todo o catálogo sem refazer as fotos.

Passo 3: inserir o produto em uma cena lifestyle

Fotos de estúdio servem bem para grades de marketplace; cenas lifestyle vendem o produto em landing pages ou anúncios. Mesmo padrão de edição, prompt mais ambicioso — o modelo coloca o produto exato em uma cena realista verossímil, não apenas muda a cor do fundo.

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>"],
))

Mantenha a linguagem de restrição em cada prompt de edição ("keep the original ... completely unchanged") — é ela que impede o modelo de fazer o produto se desviar enquanto muda tudo ao redor.

Automação em lote para todo o catálogo de produtos

Uma chamada de edição isolada é útil; na escala de um catálogo, o valor está em executar o mesmo padrão para cada SKU de forma não supervisionada. Uma estrutura que funciona bem em produção é a seguinte:

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))

Ao processar mais do que algumas imagens, os pontos a seguir importam:

• Chave de idempotência por linha. Envie um header Idempotency-Key diferente para cada SKU/variante, para que solicitações repetidas após um timeout não criem — nem cobrem novamente — tarefas duplicadas.
• Limite a concorrência, não dispare tudo de uma vez. Um pool pequeno de threads (ou semáforo assíncrono) evita atingir limites de taxa; em caso de 429, faça backoff e tente novamente, em vez de tratá-lo como falha definitiva.
• Escolha o nível de qualidade conforme o uso da imagem, não de forma uniforme: miniaturas e listagens em grade normalmente bastam com low/medium, enquanto imagens principais da página inicial ou criativos de anúncios merecem high ou xhigh.
• Derive diferentes proporções a partir da mesma imagem-fonte editada, e não da original — execute uma vez a edição de substituição de fundo e depois solicite versões recortadas em 1:1, 4:5 e 9:16 a partir desse resultado, para que todos os canais exibam exatamente a mesma apresentação do produto.
• Baixe ou reenvie imediatamente a URL de saída. As saídas das tarefas expiram; não use URLs temporárias como fonte permanente das suas imagens.

Preços

O gpt-image-2.5-flare é cobrado pelo número de imagens de saída, conforme o nível de qualidade — a mesma tarifa para geração do zero ou edição:

Qualidade	Preço por imagem
low	$0.0172
medium	$0.0672
high	$0.1829
xhigh	$0.3572
auto	$0.3572
max	$0.7143

No nível medium, redesenhar o tema de um catálogo de 500 SKUs, com uma edição de substituição de fundo por produto, custa aproximadamente $33.60. Consulte a página de preços para a tabela completa e atualizada de tarifas de todos os modelos.

Perguntas frequentes

A edição pode alterar meu produto por acidente? Restrinja o prompt de edição a uma única alteração ("altere apenas o fundo...") e liste explicitamente o que deve permanecer inalterado (formato, cor, texto do rótulo, ângulo de câmera). Os exemplos acima mostram o produto permanecendo inalterado em cada edição.

O mesmo modelo pode gerar e editar? Sim — gpt-image-2.5-flare é um único ID de modelo. Inclua image_urls para editar uma foto existente; omita-o para gerar apenas a partir do prompt.

Quantas imagens-fonte posso enviar em uma chamada de edição? Até 16 via image_urls, embora a maioria das edições de catálogo de produtos precise apenas de uma — a foto que você quer redesenhar.

Como evitar cobrança duplicada em novas tentativas? Envie um header Idempotency-Key exclusivo para cada solicitação. Uma nova tentativa com a mesma chave retorna a tarefa original em vez de criar uma nova tarefa.

Leitura relacionada

Se você está configurando a primeira chamada, comece pelo guia da API gpt-image-2.5-flare para obter um exemplo mínimo funcional e entender melhor o ciclo de vida das tarefas assíncronas. Para mais padrões de prompt além de fotografia de produtos, consulte Prompts do GPT Image 2.5 Flare: receitas prontas para copiar e colar com saídas reais. Os parâmetros e o schema completos estão na página do modelo, e as convenções gerais da API (autenticação, polling de tarefas, callbacks) estão na documentação da hiapi.

Pronto para experimentar no seu próprio catálogo? Obtenha uma chave de API no painel da hiapi e execute o exemplo de foto de estúdio acima na sua primeira foto de produto.