Gerar imagens de produtos de e-commerce com grok-imagine/image-to-image via API hiapi

O sucesso de um catálogo de produtos de e-commerce depende inteiramente da consistência. Um vendedor com 40 SKUs não precisa de 40 sessões fotográficas diferentes — precisa de um fundo bonito e de uma forma rápida de inserir cada produto nele. Esse é exatamente o caso de uso real da edição de imagens guiada por referência, e é exatamente para isso que o grok-imagine/image-to-image na API hiapi é bom: forneça a ele um cenário e uma foto de produto, e ele combina os dois em uma imagem limpa e alinhada à identidade da marca — sem máscaras manuais e sem etapa separada de recorte.

Este guia cobre o schema real e testado do modelo (não texto de marketing), o preço que você realmente paga, um script de processamento em lote para aplicar o mesmo fundo a um catálogo inteiro e um truque prático: controlar a proporção de saída entre as várias plataformas de e-commerce que exigem recortes diferentes.

O que o modelo realmente faz

grok-imagine/image-to-image recebe um prompt de texto e algumas imagens de referência e as funde em uma nova imagem. Para fotografia de produto, isso significa:

• Unificação de fundo — colocar cada foto de SKU diante do mesmo cenário estilizado (uma mesa, uma estante, um fundo de estúdio), sem precisar refotografar nada.
• Composição de cena — combinar o recorte do produto com uma imagem de referência de ambiente, fazendo com que iluminação e composição se correspondam.
• Transferência de estilo entre referências — levar o ajuste de cor ou os adereços de uma imagem para outra, mantendo o produto em si sem edições.

Tudo isso acontece em uma única chamada de tarefa, cobrada por imagem de saída, mais uma pequena taxa por cada imagem de referência enviada.

O schema real (verificado na API em produção, não na página de preços)

Fizemos uma sondagem direta em POST /v1/tasks com grok-imagine/image-to-image, e o schema de entrada desse modelo aceita exatamente dois campos:

{
  "model": "grok-imagine/image-to-image",
  "input": {
    "prompt": "string, required",
    "image_urls": ["array of public image URLs, required, max 3"]
  }
}

É só isso — não há resolution, não há aspect_ratio e não há parâmetro strength. Qualquer outra coisa no payload é rejeitada pelo schema estrito.

Há um erro que vale a pena corrigir: a página de preços da hiapi atualmente afirma que esse modelo suporta "até 6" imagens de referência. Testamos enviando 6 e 7 URLs de imagem na mesma requisição, e ambas foram rejeitadas:

{"error_code":"INVALID_REQUEST","message":"invalid input: image_urls: maxItems: got 6, want 3"}
{"error_code":"INVALID_REQUEST","message":"invalid input: image_urls: maxItems: got 7, want 3"}

Até o momento deste artigo, o limite realmente aplicado é de 3 imagens por chamada, e não 6. Se você vai construir um pipeline em torno desse modelo, planeje com 3 e trate qualquer texto de marketing que diga o contrário como desatualizado — antes de publicar uma automação que dependa desse limite, confirme sempre com uma chamada real a POST /v1/tasks, porque esses limites mudam conforme a plataforma evolui.

Proporção automática: a proporção da saída segue a sua primeira imagem de referência

O modelo não tem campo de entrada aspect_ratio, então de onde vem o formato da saída? Fizemos um teste controlado para descobrir: mesmo prompt, mesmas duas imagens de referência, apenas invertendo a ordem de image_urls.

Nesta renderização, a foto do produto (a mochila) foi listada em primeiro lugar em image_urls, seguida pela cena de fundo. A saída retornou como 1248×832 — uma imagem horizontal 3:2 compatível com a proporção da própria foto do produto.

Mesmo prompt, mesmas duas imagens — mas desta vez a cena de fundo foi listada em primeiro lugar. A saída retornou como 1024×1024, um recorte quadrado compatível com a proporção da imagem de referência da cena, e não com a do produto.

A regra é: a proporção de saída de grok-imagine/image-to-image é herdada da URL que aparece em primeiro lugar em image_urls. Ele não lê dicas de composição do seu prompt ("foto de produto" ou "cena ampla") — é puramente posicional. Uma vez que você sabe disso, é uma alavanca realmente útil: para atingir o recorte preferido de uma plataforma de e-commerce específica, basta reordenar o array de referências. Para listagens de produtos em estilo Instagram, quadradas, coloque a referência quadrada em primeiro lugar; para banners largos, coloque a referência horizontal em primeiro lugar.

Preços (verificados na tabela de preços em produção)

Modelo	Tipo de chamada	Preço
grok-imagine/text-to-image	Texto → imagem	$0.03 / imagem
grok-imagine/image-to-image	Edição guiada por referência (este guia)	$0.03 / imagem + $0.003 por imagem de referência
grok-imagine-quality/text-to-image	Texto → imagem, nível avançado	$0.07 / imagem (1K)
grok-imagine-quality/image-to-image	Edição guiada por referência, nível avançado	$0.08 / imagem (1K), $0.10 / imagem (2K), + $0.015 por imagem de referência

O nível básico grok-imagine/image-to-image usado neste guia não varia com a resolução e tem preço fixo — você não paga a sobretaxa de 2K/4K como no nível -quality. Para uma atualização de catálogo que combina dezenas de SKUs no mesmo cenário, $0.036 por imagem (uma foto de produto mais uma referência de cena) é o número com o qual você deve orçar. Antes de executar em grande volume, consulte novamente /en/pricing, porque as tarifas podem mudar.

Se você precisa de detalhes mais nítidos por imagem e aceita um aumento de preço de cerca de 3 vezes, o nível grok-imagine-quality é a versão de maior fidelidade do mesmo fluxo de trabalho. Para renderizações de produto puramente texto para imagem, sem nenhuma foto de referência, consulte o passo a passo de texto para imagem do nível básico.

Script de processamento em lote: um cenário, um catálogo inteiro

Abaixo está um loop Python minimalista que recebe uma cena de fundo reutilizável, combina-a com cada foto de produto em uma pasta, envia cada uma como tarefa independente e faz polling até a conclusão. Ele usa o schema confirmado acima e coloca a foto do produto em primeiro lugar, para que cada saída herde a proporção da própria foto do produto — se você quiser a proporção do cenário, inverta a ordem.

import os
import time
import requests

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

SCENE_URL = "https://static.hiapi.ai/blog/grok-imagine-image-to-image-ecommerce/scene-base.jpg"
PROMPT = (
    "Composite the product from the first reference photo naturally into the "
    "second reference's studio scene, matching its lighting and shadow direction. "
    "Keep the product's shape, color, and texture unchanged."
)


def submit(product_url: str) -> str:
    payload = {
        "model": "grok-imagine/image-to-image",
        "input": {
            "prompt": PROMPT,
            "image_urls": [product_url, SCENE_URL],  # product first -> output follows its ratio
        },
    }
    resp = requests.post(f"{API_BASE}/tasks", headers=HEADERS, json=payload, timeout=30)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_result(task_id: str, timeout_s: int = 300) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]
        if task["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
        time.sleep(5)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


if __name__ == "__main__":
    product_urls = [
        "https://your-storage.example.com/catalog/dripper-raw.jpg",
        "https://your-storage.example.com/catalog/sneaker-raw.jpg",
        "https://your-storage.example.com/catalog/backpack-raw.jpg",
    ]
    for url in product_urls:
        task_id = submit(url)
        output_url = wait_for_result(task_id)
        print(f"{url} -> {output_url}")

Para pipelines de produção, registre um callback.url na tarefa em vez de fazer polling em loop — consulte o catálogo de modelos da hiapi para a estrutura completa do payload de callback. Armazene o taskId junto com o SKU do seu produto, para que tarefas com falha possam ser repetidas sem reenviar o lote inteiro.

Exemplos com fotos reais de produtos

Ambas foram geradas com a mesma imagem de referência de cena de fundo, trocando apenas a foto do produto entre chamadas — a iluminação, a mesa e as plantas ao fundo permanecem consistentes em todo o "catálogo", que é exatamente o objetivo do fluxo de trabalho com cenário reutilizável.

Perguntas frequentes

É possível usar mais de 3 imagens de referência em uma única chamada? Não. O schema em produção impõe maxItems: 3 em image_urls — isso foi confirmado por testes diretos na API, independentemente do que o texto de marketing diga em outro lugar. Projete seus prompts em torno de no máximo 3 imagens de referência (normalmente: produto + cenário, ou produto + cenário + referência de estilo).

Como controlar a proporção da saída? O modelo não tem parâmetro aspect_ratio. A saída herda a proporção da primeira imagem em image_urls — reordene suas referências para atingir a proporção desejada.

Ele suporta geração puramente por texto, sem referências? Não — image_urls é um campo obrigatório. Para renderizações de produto puramente por texto, use grok-imagine/text-to-image, a $0.03/imagem.

Existe uma versão de maior fidelidade deste modelo? Sim, o grok-imagine-quality/image-to-image executa o mesmo fluxo de trabalho guiado por referência a $0.08/imagem (1K) ou $0.10/imagem (2K), mais $0.015 por imagem de referência, para oferecer detalhes mais nítidos.

Experimente agora

Obtenha uma chave de API no seu painel da hiapi, prepare uma cena de fundo, execute suas primeiras tarefas com alguns SKUs antes de decidir trocar o catálogo inteiro — a $0.036 por imagem, testar esse fluxo de trabalho em 10 produtos custa menos de um dólar.