API de outpainting: transforme fotos de produto em formatos de anúncio

O Image Expander no SpicyAPI (spicyapi.ai) é o jeito rápido de tirar de uma foto quadrada de produto um banner horizontal e um story vertical: você envia uma imagem e uma proporção, e ele devolve a foto encaixada em um quadro maior, com nova cena pintada ao redor. Custa $0,024 por imagem, qualquer que seja a proporção, não pede prompt nem máscara, e sempre devolve um lado maior de 1536 px. O detalhe é que ele também redesenha parte da sua foto, então serve para fundos, não para o detalhe exato do produto. Embalagem com pixel exato exige recolocar o original por cima. Se você precisa controlar o que é pintado, gere a cena na nova proporção com um modelo de edição de imagem baseado em prompt; o guia de foto de produto para layouts de anúncio faz isso para os mesmos três formatos.

Recorte, componha ou expanda

• Recorte quando a foto já tem cena de sobra nos lados de que você precisa. É grátis e mantém cada pixel.
• Componha a tela (cor sólida ou painel ao lado da foto) quando o título precisa de uma área limpa garantida. A cena gerada não pode prometer isso.
• Expanda quando o destino precisa de mais imagem do que você fotografou e uma cor sólida ficaria errada: céu acima de um vertical, bancada e parede ao lado de um quadrado. Mudanças de forma moderadas se misturam melhor; quanto mais a nova forma se afasta do original, mais cena é inventada.

Tamanhos de saída para as sete proporções

O lado maior é sempre 1536 px e o lado menor segue a proporção. A tarefa é spicyapi/image-expander-v1/edit e ela aceita estes valores:

Duas consequências importam no planejamento. Primeira, 4:5 e 1.91:1 não são oferecidas: use 3:4 e recorte 96 px da altura para chegar a 4:5 (1152 × 1440), ou use 16:9 e recorte cerca de 60 px para 1.91:1 (1536 × 804). Segunda, a fonte é redimensionada para caber, então um resultado 16:9 a partir de uma foto quadrada mostra seu produto com no máximo 864 px de altura, por maior que fosse o original. Se o destino precisar de mais pixels, amplie a imagem final com o fluxo do guia de ampliação de imagens em vez de começar de uma fonte de qualidade menor.

Quanto de cena nova cada salto exige

A foto é redimensionada por um único fator para caber dentro da tela de destino; todo o resto é pintado. Para um quadrado de 1200 × 1200, o fator é 0.72 tanto para 16:9 quanto para 9:16, o que deixa uma foto de 864 × 864 no centro do quadro e 672 px de cena nova (44% da tela). Uma foto 16:9 transformada em 9:16 é muito mais difícil: a foto encolhe para 864 × 486 e 68% do quadro é inventado.

Saltos grandes também funcionam. Um exemplo publicado transforma um retrato de varanda de 1280 × 720 em um quadro de story de corpo inteiro de 864 × 1536, com o resto do vestido, os ladrilhos do piso e o céu pintados:

O outro vai no sentido contrário: um retrato 2:3 fechado vira um cabeçalho de 1536 × 864 com a parede escura continuando dos dois lados, que é exatamente o espaço de título que um banner precisa.

O que o modelo faz com a sua foto

Os exemplos publicados do Image Expander mostram três coisas que decidem como você usa a saída:

1. A foto é redimensionada para caber, não fixada em uma borda. No resultado da varanda ela fica a 462 px da borda superior e 588 px da inferior; no resultado de retrato, a 453 px da esquerda e 507 px da direita. Nos dois casos a foto ficou levemente fora do centro, então não conte com centralização exata, e você não pode movê-la: não há campo de âncora nem de preenchimento. Coloque as zonas de texto onde as bordas deixarem espaço, ou desloque o produto recortando o lado oposto do resultado.
2. A própria foto é redesenhada em parte. No resultado da varanda, o rosto, o cabelo, as folhas de limão e os balaústres à direita diferem da fonte (a mudança média de pixel dentro da área de origem é 30 de 255, incluindo diferenças de reamostragem e compressão). A cena se lê como a mesma foto, mas os detalhes finos são regenerados.
3. As bordas são o ponto fraco. Céu, papel de estúdio, reboco e areia são os que melhor continuam. Um rosto, uma mão ou um texto cortados pela borda precisam ser inventados.

Compare sua fonte com o resultado antes de publicar: uma grande mudança de pixel em uma área de logo ou rótulo significa que essa região precisa vir do original. A regra prática: use o resultado como fundo e volte a colocar o produto real por cima quando ele precisar ser exato. Para uma bolsa ou garrafa com rótulo, recorte o produto do original com o fluxo de remoção de fundo, coloque-o sobre a cena expandida no tamanho que o layout pedir e redesenhe a sombra de contato. O guia de foto de produto para layouts de anúncio cobre as etapas de layout e de proteção de rótulo para os mesmos três formatos, então elas não se repetem aqui.

Escolha uma fonte que expanda bem

• Deixe margem ao redor do produto e mantenha-a livre da borda de onde ele vai crescer. Um produto completo com espaço vazio ao lado expande com mais segurança que um recorte apertado.
• Prefira ambientes simples: papel sem emenda, parede de reboco, céu, uma bancada com uma única linha de horizonte nítida. Padrões repetidos como ladrilhos ou listras podem sair de fase na emenda.
• Escolha a proporção mais próxima. Se um marketplace quer 5:4, parta de 1:1 ou de 4:3 em vez de uma fonte 9:16.

Teste primeiro no Playground

1. Abra a página da tarefa Image Expander e fique na aba Playground, na visão Form. Entre com uma conta com saldo para executar.
2. Em Input image, solte sua foto, ou use Asset URL para um link direto (JPG, PNG ou WebP, até 10 MB).
3. Escolha uma proporção em Aspect ratio (não Auto, que a API não aceita) para o destino, por exemplo 16:9 para um cabeçalho ou 9:16 para um story. Output format é PNG por padrão; escolha JPEG ou WebP para arquivos menores.
4. Confira a estimativa de preço e execute. Teste primeiro as proporções que você precisa na sua fonte mais difícil: uma emenda ruim aqui será ruim pela API.

O corpo da requisição mostrado abaixo do formulário é o mesmo JSON que a API aceita, então uma configuração que funciona aqui vai direto para o código.

Depois chame pelo código

Instale o SDK de Python (pip install spicyapi), defina SPICY_API_KEY no ambiente e execute uma chamada por fonte e por proporção:

import uuid

from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

photo = client.upload_file("./product-square.png")  # local files become spicy:// URIs

task = client.create_task(
    model="spicyapi/image-expander-v1/edit",
    input_data={"image_url": photo["uri"], "aspect_ratio": "9:16", "output_format": "png"},
    idempotency_key=str(uuid.uuid4()),  # new key per new request; reuse only to retry the same one
)

final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"Task {task['taskId']} ended as {final['state']}")

print(output_assets(final)[0]["url"])  # copy it to your own storage now

Uploads, espera, erros e novas tentativas estão na referência do SDK de Python e no guia de tarefas assíncronas. Mude aspect_ratio e a chave de idempotência para cada formato extra; só uma tarefa bem-sucedida é cobrada.

Ou deixe um agente executar

Se um assistente deve produzir os formatos para você, entregue a ele a CLI ou o servidor MCP. Os dois mostram o preço e pedem confirmação antes de uma chamada paga. A Skill acrescenta instruções por cima de qualquer um deles.

• CLI. spicyapi executa uma tarefa a partir de um terminal ou script (npx @spicyapi/cli funciona sem instalação):

``bash spicyapi files upload ./product-square.png # prints a spicy:// URI spicyapi tasks create --model spicyapi/image-expander-v1/edit \ --input-file input.json --idempotency-key product-square-9x16-v1 --wait ``

input.json contém o mesmo objeto input acima, com a URI spicy://.

• Servidor MCP. Adicione o servidor MCP ao seu assistente e então pergunte: "Expand ./product-square.png to 9:16 and 16:9 with Image Expander." Ele chama spicyapi_upload_file, depois spicyapi_task_create (que para para sua confirmação de preço) e depois spicyapi_task_wait.

``json { "mcpServers": { "spicyapi": { "command": "npx", "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"], "env": { "SPICY_API_KEY": "YOUR_SPICY_API_KEY" } } } } ``

• Skill. npx skills add spicyapi-ai/spicy-skill instala o Agent Skill, que ensina um assistente de programação a ler o esquema atual e reutilizar chaves de idempotência em vez de adivinhar. Ele não executa tarefas sozinho, então use-o junto com a CLI ou o MCP.

Revise cada resultado em três passadas

1. Produto: mesma quantidade de itens, silhueta, cor, rótulo e alça ou tampa. Um logotipo mudado ou uma segunda caneca na área nova é reprovação, não escolha de estilo.
2. Emenda: acompanhe a borda da bancada, o padrão da parede, o horizonte e a direção da luz através da borda antiga. Uma costura atrás do produto importa; uma em um canto que você vai recortar, não.
3. Layout: sobreponha a caixa do título e as áreas de sobreposição da plataforma. Um story vertical pode esconder o produto sob os controles da interface, então confira a orientação atual de safe area para esse posicionamento.

Se o problema estiver fora do seu recorte, recorte-o. Se ele cruzar o produto ou a zona de texto, mude a fonte (original mais largo, enquadramento menos apertado, fundo mais neutro) ou volte para uma tela composta. Uma nova geração com a mesma fonte é um novo sorteio, não um conserto, então mude alguma coisa primeiro.

Custo de um conjunto de três formatos

Cada saída concluída custa $0,024, então um 16:9 e um 9:16 a partir de uma mesma fonte são 2 x $0,024 = $0,048, e três saídas (por exemplo 1:1, 16:9 e 9:16 a partir de uma fonte 4:3) são $0,072. Um lote de 20 fontes em duas proporções dá 40 chamadas, ou $0,96; se 5 fontes precisarem de mais uma tentativa com uma fonte melhor, são 45 chamadas, ou $1,08. Isso não inclui recortes, ampliação e tempo de design. Uma requisição concluída é cobrada seja qual for a aparência do resultado, então corrija a fonte antes de rodar de novo em vez de sortear outra vez.

Perguntas frequentes

E se minha foto for maior que 1536 px? Ela volta com 1536 no lado maior, então pode ficar menor que o original. Amplie depois se o destino precisar de mais pixels.

Posso usar para fazer um primeiro quadro 9:16 de vídeo? Sim, se a pessoa e a pose já estiverem completas; veja o guia para transformar um retrato horizontal em vídeo vertical com IA. A página do modelo traz o esquema e o preço atuais.