API di outpainting: trasforma foto di prodotto in formati pubblicitari

Image Expander su SpicyAPI (spicyapi.ai) è il modo rapido per ricavare da una foto quadrata di prodotto un banner orizzontale e una story verticale: invii un'immagine e un rapporto d'aspetto, e restituisce la foto inserita in una cornice più grande con nuova scena dipinta attorno. Costa $0.024 per immagine, qualunque sia il rapporto scelto, non richiede prompt né maschera, e restituisce sempre un lato lungo di 1536 px. Il rovescio della medaglia: ridisegna anche una parte della tua foto, quindi è adatto agli sfondi, non ai dettagli esatti del prodotto. Un imballaggio perfettamente fedele richiede di rimettere l'originale in primo piano. Se devi controllare cosa viene dipinto, genera invece la scena nel nuovo rapporto con un modello di modifica immagine basato su prompt; la guida da foto di prodotto a layout pubblicitari lo fa per gli stessi tre formati.

Ritaglia, componi o estendi

• Ritaglia quando la foto ha già scena di riserva sui lati che ti servono. È gratis e conserva ogni pixel.
• Componi la tela (colore piatto o pannello accanto alla foto) quando il titolo ha bisogno di un'area pulita garantita. La scena generata non può prometterlo.
• Estendi quando la destinazione richiede più immagine di quella che hai scattato e un colore piatto sembrerebbe sbagliato: cielo sopra un verticale, piano e muro accanto a un quadrato. Le variazioni di forma moderate si fondono meglio; più la nuova forma si allontana dall'originale, più scena viene inventata.

Dimensioni di output per i sette rapporti

Il lato lungo è sempre 1536 px e il lato corto segue il rapporto. L'attività è spicyapi/image-expander-v1/edit e supporta questi valori:

Due conseguenze contano per la pianificazione. Prima, 4:5 e 1.91:1 non sono offerti: usa 3:4 e ritaglia 96 px di altezza per arrivare a 4:5 (1152 × 1440), oppure usa 16:9 e ritaglia circa 60 px per 1.91:1 (1536 × 804). Seconda, la sorgente viene scalata per adattarsi, quindi un risultato 16:9 da una foto quadrata mostra il prodotto alto al massimo 864 px, per quanto grande fosse l'originale. Se la destinazione richiede più pixel, ingrandisci l'immagine finale con il flusso della guida all'ingrandimento delle immagini invece di partire da una sorgente di qualità inferiore.

Quanta scena nuova richiede ogni salto

La foto viene scalata con un unico fattore per stare dentro la tela di destinazione; tutto il resto viene dipinto. Per un quadrato di 1200 × 1200 il fattore è 0.72 sia per 16:9 sia per 9:16, il che lascia una foto di 864 × 864 al centro della cornice e 672 px di scena nuova (44 % della tela). Una foto 16:9 trasformata in 9:16 è molto più difficile: la foto si riduce a 864 × 486 e il 68 % della cornice è inventato.

I salti grandi funzionano comunque. Un esempio pubblicato trasforma un ritratto su terrazza di 1280 × 720 in una cornice story a figura intera di 864 × 1536, dipingendo il resto dell'abito, le piastrelle del pavimento e il cielo:

L'altro va nella direzione opposta: un ritratto 2:3 ravvicinato diventa un'intestazione di 1536 × 864 con il muro scuro che prosegue su entrambi i lati, ed è esattamente lo spazio per il titolo che serve a un banner.

Cosa fa il modello alla tua foto

Gli esempi pubblicati di Image Expander mostrano tre cose che decidono come usare l'output:

1. La foto viene scalata per adattarsi, non ancorata a un bordo. Nel risultato della terrazza si trova a 462 px dal bordo superiore e 588 px da quello inferiore; nel risultato del ritratto, a 453 px dal lato sinistro e 507 px da quello destro. In entrambi i casi la foto è leggermente decentrata, quindi non contare su un centraggio esatto, e non puoi spostarla: non c'è un campo di ancoraggio né di riempimento. Colloca le zone di testo dove i lati lasciano spazio, oppure sposta il prodotto ritagliando il lato opposto del risultato.
2. La foto stessa viene in parte ridisegnata. Nel risultato della terrazza il volto, i capelli, le foglie di limone e le colonnine a destra differiscono dalla sorgente (la variazione media di pixel nell'area di origine è 30 su 255, includendo differenze di ricampionamento e compressione). La scena si legge come lo stesso scatto, ma i dettagli fini vengono rigenerati.
3. I bordi sono il punto debole. Cielo, carta da studio, intonaco e sabbia proseguono meglio. Un volto, una mano o una scritta tagliati dalla cornice devono essere inventati.

Confronta la sorgente con il risultato prima della consegna: una forte variazione di pixel su un'area di logo o etichetta significa che quell'area deve venire dall'originale. La regola pratica: usa il risultato come sfondo e rimetti sopra il prodotto reale quando deve essere esatto. Per una borsa o una bottiglia con etichetta, ritaglia il prodotto dall'originale con il flusso di rimozione dello sfondo, collocalo sulla scena estesa alla dimensione richiesta dal layout e ridisegna l'ombra di contatto. La guida da foto di prodotto a layout pubblicitari copre i passaggi di layout e protezione dell'etichetta per gli stessi tre formati, quindi qui non vengono ripetuti.

Scegli una sorgente che si estende bene

• Lascia un margine intorno al prodotto e tienilo libero dal bordo da cui crescerà. Un prodotto completo con spazio vuoto accanto si estende in modo più sicuro di un ritaglio stretto.
• Preferisci ambienti semplici: carta senza giunti, muro in intonaco, cielo, un piano con una sola linea d'orizzonte netta. Motivi ripetuti come piastrelle o strisce possono spostarsi di fase in corrispondenza della giunzione.
• Scegli il rapporto più vicino. Se un marketplace vuole 5:4, parti da 1:1 o da 4:3 invece che da una sorgente 9:16.

Provalo prima nel Playground

1. Apri la pagina dell'attività Image Expander e resta nella scheda Playground, in vista Form. Accedi con un account con saldo per eseguire.
2. In Input image trascina la tua foto, oppure usa Asset URL per un collegamento diretto (JPG, PNG o WebP, fino a 10 MB).
3. Scegli un rapporto in Aspect ratio (non Auto, che l'API non accetta) in base alla destinazione, per esempio 16:9 per un'intestazione o 9:16 per una story. Output format è PNG per impostazione predefinita; scegli JPEG o WebP per file più leggeri.
4. Controlla la stima del prezzo, poi esegui. Prova prima i rapporti che ti servono sulla sorgente più difficile: una giunzione sbagliata qui sarà sbagliata anche via API.

Il corpo della richiesta mostrato sotto il modulo è lo stesso JSON che l'API accetta, quindi una configurazione che funziona qui si copia direttamente nel codice.

Poi chiamalo dal codice

Installa l'SDK Python (pip install spicyapi), imposta SPICY_API_KEY nell'ambiente ed esegui una chiamata per sorgente e rapporto:

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

Caricamenti, attesa, errori e nuovi tentativi sono nel riferimento dell'SDK Python e nella guida alle attività asincrone. Cambia aspect_ratio e la chiave di idempotenza per ogni formato aggiuntivo; viene fatturata solo un'attività completata con successo.

Oppure fai eseguire tutto a un agente

Se un assistente deve produrre i formati al posto tuo, dagli la CLI o il server MCP. Entrambi mostrano il prezzo e chiedono conferma prima di una chiamata a pagamento. La Skill aggiunge istruzioni sopra l'uno o l'altro.

• CLI. spicyapi esegue un'attività da terminale o script (npx @spicyapi/cli funziona senza installazione):

``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 contiene lo stesso oggetto input di sopra, con l'URI spicy://.

• Server MCP. Aggiungi il server MCP al tuo assistente, poi chiedi: "Expand ./product-square.png to 9:16 and 16:9 with Image Expander." Chiama spicyapi_upload_file, poi spicyapi_task_create (che si ferma per la conferma del prezzo), poi 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 installa l'Agent Skill, che insegna a un assistente di programmazione a leggere lo schema attuale e a riutilizzare le chiavi di idempotenza invece di indovinare. Non può eseguire attività da solo, quindi usalo insieme alla CLI o a MCP.

Rivedi ogni risultato in tre passaggi

1. Prodotto: stesso numero di pezzi, silhouette, colore, etichetta e maniglia o tappo. Un logo modificato o una seconda tazza nella zona nuova è un rifiuto, non una scelta di stile.
2. Giunzione: segui il bordo del piano, il motivo del muro, l'orizzonte e la direzione della luce attraverso il vecchio bordo. Una cucitura dietro il prodotto conta; una in un angolo che ritaglierai, no.
3. Layout: sovrapponi il riquadro del titolo e le aree di sovrapposizione della piattaforma. Una story verticale può nascondere il prodotto sotto i controlli dell'interfaccia, quindi controlla le indicazioni attuali sulla safe area per quel posizionamento.

Se il problema è fuori dal tuo ritaglio, ritaglialo via. Se attraversa il prodotto o la zona di testo, cambia la sorgente (originale più ampio, inquadratura meno stretta, sfondo più neutro) oppure torna a una tela composta. Una nuova generazione con la stessa sorgente è un nuovo sorteggio, non una riparazione, quindi cambia prima qualcosa.

Costo di un set di tre formati

Ogni output completato costa $0.024, quindi un 16:9 e un 9:16 da una stessa sorgente sono 2 × $0.024 = $0.048, e tre output (per esempio 1:1, 16:9 e 9:16 da una sorgente 4:3) sono $0.072. Un lotto di 20 sorgenti a due rapporti è 40 chiamate, cioè $0.96; se 5 sorgenti richiedono un altro tentativo con una sorgente migliore, 45 chiamate, cioè $1.08. Sono esclusi i ritagli, l'ingrandimento e il tempo di design. Una richiesta completata viene fatturata qualunque sia l'aspetto del risultato, quindi correggi la sorgente prima di rilanciare invece di tirare di nuovo a sorte.

Domande frequenti

E se la mia foto è più grande di 1536 px? Torna a 1536 sul lato lungo, quindi può essere più piccola dell'originale. Ingrandisci in seguito se la destinazione richiede più pixel.

Posso usarla per creare un primo fotogramma 9:16 per un video? Sì, se la persona e la posa sono già complete; vedi la guida per trasformare un ritratto orizzontale in video verticale con l'IA. La pagina del modello riporta lo schema e il prezzo attuali.