Gerar imagens de produtos de e-commerce com seedream-4.5/image-to-image via API hiapi

Um catálogo de produtos não é uma única foto — é o mesmo SKU apresentado em dezenas de contextos: foto de produto em fundo branco, cena de lifestyle, retoque após troca de componentes pelo fornecedor e versões que combinam com o fundo sazonal da marca. Refotografar ou regenerar do zero a cada vez quebra a consistência, porque um prompt totalmente novo desenha um produto ligeiramente diferente.

seedream-4.5/image-to-image existe exatamente para isso. Ele recebe sua foto real do produto — ou várias imagens de referência ao mesmo tempo — mais uma instrução de edição em linguagem natural, e retorna uma imagem editada que preserva a geometria, os materiais e a identidade da marca do produto real, alterando apenas o que você pedir: o fundo, detalhes de desgaste ou o ajuste de cor necessário para manter uma identidade visual unificada. Na hiapi, ele roda pelo mesmo endpoint assíncrono /v1/tasks que todos os outros modelos, a US$ 0,045 por imagem.

Os dois exemplos abaixo são chamadas de API reais, mostrando os prompts exatos e as imagens geradas.

Por que editar em vez de regenerar

Text-to-image e image-to-image resolvem problemas diferentes:

• Text-to-image cria o produto do zero a partir de uma descrição. Bom para design conceitual, ruim para catálogo de produtos — pergunte duas vezes e você terá duas canecas diferentes.
• Edição image-to-image parte da sua foto real do produto. O modelo trata a imagem de referência como a verdade fundamental de forma, proporção e identidade da marca, e altera apenas o que o prompt especifica. É por isso que é seguro para listagens de produtos reais: o produto na saída ainda é o seu produto.

O fluxo de trabalho prático é: mantenha uma foto base limpa para cada SKU (uma foto de estúdio comum serve como referência) e então execute seedream-4.5/image-to-image uma vez para cada contexto que você precisa — cena de lifestyle, substituição de fundo, fundo consistente com a marca, correção de detalhes — em vez de refotografar ou criar um prompt do zero todas as vezes.

Exemplo 1: substituição de fundo por cena de lifestyle

Referência base: uma foto de estúdio comum de um coador de cerâmica pour-over sobre fundo branco.

Prompt de edição enviado ao modelo:

Mantenha a forma exata, a cor do esmalte e as proporções do coador de cerâmica pour-over
inalteradas. Coloque-o sobre uma bancada de cozinha de madeira quente, ao lado de uma caneca
de cerâmica fumegante e um saco de café de juta aberto. Iluminação lateral quente de hora
dourada, profundidade de campo rasa, sombras suaves. Não altere o coador de forma alguma —
altere apenas a cena ao redor.

O resultado preserva o contorno e a cor do esmalte do coador, reconhecíveis pixel a pixel, enquanto o coloca em uma cena de lifestyle que uma foto de produto comum não conseguiria produzir sozinha — sem refilmagem, sem etapa separada de composição.

Exemplo 2: unificar produtos sobre fundo de marca

Referência base: uma foto de estúdio comum de um tênis de lona branco.

Prompt de edição enviado ao modelo:

Mantenha a costura, os ilhoses, os cadarços e a textura da lona do tênis exatamente como
mostrado. Substitua o fundo por um fundo de estúdio terracota sólido e coloque o tênis
sobre um pedestal terracota combinando. Iluminação de estúdio suave e uniforme vinda do
canto superior esquerdo, sombra de contato sutil. Não altere a forma, a cor nem qualquer
detalhe impresso do tênis.

Esse é o padrão para unificar visualmente um catálogo de produtos: escolha um tratamento de fundo e execute a foto base de cada SKU com a mesma instrução de edição. O produto varia de uma imagem para outra; o fundo, a direção da luz e o tom permanecem consistentes, porque é o prompt que os controla — não o produto.

Chamando a API diretamente

seedream-4.5/image-to-image roda pelo endpoint de tarefas assíncronas da hiapi. Envie a tarefa, faça polling até concluir e baixe o resultado.

curl:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-4.5/image-to-image",
    "input": {
      "prompt": "Mantenha o produto exatamente como mostrado. Substitua o fundo por um fundo de estúdio terracota sólido e um pedestal combinando. Iluminação de estúdio suave e uniforme vinda do canto superior esquerdo.",
      "image_urls": ["https://your-storage.example.com/base-product-photo.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

A resposta retorna um task_id. Faça polling em GET /v1/tasks/{task_id} até que status seja succeeded e então leia a URL da imagem em output[0].url. Essa URL tem prazo de validade — baixe-a imediatamente.

Python (enviar tarefa + polling + download):

import os
import time
import requests

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


def edit_product_image(prompt: str, image_urls: list[str],
                        aspect_ratio: str = "1:1", resolution: str = "2K") -> bytes:
    resp = requests.post(
        f"{API_BASE}/tasks",
        headers=HEADERS,
        json={
            "model": "seedream-4.5/image-to-image",
            "input": {
                "prompt": prompt,
                "image_urls": image_urls,
                "aspect_ratio": aspect_ratio,
                "resolution": resolution,
            },
        },
        timeout=30,
    )
    resp.raise_for_status()
    task_id = resp.json()["task_id"]

    while True:
        poll = requests.get(f"{API_BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        poll.raise_for_status()
        data = poll.json()
        if data["status"] == "succeeded":
            image_url = data["output"][0]["url"]
            return requests.get(image_url, timeout=30).content
        if data["status"] == "failed":
            raise RuntimeError(f"task {task_id} failed: {data.get('error')}")
        time.sleep(3)

Edição em lote de um catálogo de produtos

O padrão acima se generaliza diretamente para um catálogo de produtos: mantenha uma lista de (sku, base_photo_url), aplique a mesma instrução de edição a cada entrada — ou uma variação por SKU — e grave os resultados com o SKU como chave.

CATALOG = [
    {"sku": "dripper-ceramic-01", "base_url": "https://your-storage.example.com/dripper-01.jpg"},
    {"sku": "sneaker-canvas-white", "base_url": "https://your-storage.example.com/sneaker-white.jpg"},
    {"sku": "mug-stoneware-02", "base_url": "https://your-storage.example.com/mug-02.jpg"},
]

BACKDROP_PROMPT = (
    "Mantenha a forma exata, os materiais e qualquer marca impressa do produto "
    "inalterados. Substitua o fundo por um fundo de estúdio terracota sólido "
    "e um pedestal combinando. Iluminação de estúdio suave e uniforme vinda do "
    "canto superior esquerdo, sombra de contato sutil. Não altere o produto em si."
)

for item in CATALOG:
    image_bytes = edit_product_image(
        prompt=BACKDROP_PROMPT,
        image_urls=[item["base_url"]],
        aspect_ratio="1:1",
        resolution="2K",
    )
    with open(f"{item['sku']}-branded.jpg", "wb") as f:
        f.write(image_bytes)
    print(f"{item['sku']}: done")

A US$ 0,045 por imagem, um tratamento de fundo para um catálogo de 50 SKUs custa cerca de US$ 2,25 — e, como cada tarefa roda de forma independente, é possível paralelizar em um pool de threads ou fila de tarefas em vez de executar sequencialmente.

image_urls aceita até 14 imagens de referência por chamada, então variações mais avançadas podem entregar ao modelo vários ângulos do mesmo produto (frente, lateral, detalhe) de uma vez, quando uma única referência não basta para uma edição complexa.

Perguntas frequentes

O seedream-4.5/image-to-image altera o produto em si ou apenas a cena? Ele segue estritamente a instrução de edição. Se o prompt descrever apenas mudanças de fundo, iluminação ou contexto e pedir explicitamente para preservar o produto, a forma, a cor e os detalhes impressos do produto permanecem consistentes entre edições — é exatamente por isso que ele serve para catálogos de produtos reais e não apenas para imagens conceituais únicas.

Quantas imagens de referência podem ser enviadas por chamada? No máximo 14 URLs públicas de imagem em image_urls. A maioria das edições de um único produto precisa apenas de uma (a foto base); várias referências ajudam quando você quer que o modelo reconcilie detalhes de vários ângulos do mesmo item.

Quais resoluções são suportadas? resolution aceita 2K ou 4K. Este modelo não tem a opção 1K.

Quanto custa editar um catálogo inteiro em lote? US$ 0,045 por imagem, independentemente da resolução. Um catálogo de 100 SKUs com uma edição custa cerca de US$ 4,50.

Posso executar edições em paralelo para acelerar tarefas em lote? Sim — cada tarefa é independente, então enviar várias chamadas /v1/tasks simultaneamente (respeitando o limite de taxa da sua conta) e fazer polling delas em paralelo é a maneira mais rápida de processar catálogos grandes.

Experimente você mesmo

Para a referência completa de parâmetros e preços atualizados, consulte a página do modelo e a página de preços. Para o formato exato de requisição/resposta do endpoint de tarefas acima, veja a documentação de criação de tarefas. Se você está montando um fluxo de trabalho semelhante com outro nível de modelo, o guia de e-commerce do seedream-5.0-lite aprofunda o padrão de ancorar um único SKU e depois editar.

Obtenha uma chave de API e faça sua primeira edição em uma foto real de produto — o código acima pode ser copiado e colado hoje mesmo para rodar na API hiapi.