Guida: genera e modifica immagini

Crea immagini dal testo, modifica foto con immagini di riferimento e usa gli strumenti per sfondo, upscaling e pulizia, con scelta dei modelli e costi.

Le immagini sono la cosa più veloce ed economica da generare, quindi il posto migliore per imparare l’API. La maggior parte dei modelli di immagini finisce in meno di un minuto, perciò puoi usare ?wait=60 e ricevere l’immagine nella stessa risposta.

Da testo a immagine

curl -X POST "https://api.popnow.ai/api/v1/jobs/createTask?wait=60" \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "black-forest-labs/flux-2-klein-9b/text-to-image",
    "input": {
      "prompt": "Product photo of a ceramic coffee mug on a linen tablecloth, soft window light, shallow depth of field",
      "aspect_ratio": "4:3"
    }
  }'

Il risultato è in data.output.assets[0].url. Se la risposta è un 202, il modello ha impiegato più di 60 secondi; leggi l’attività con recordInfo.

Quale modello

Vuoi	Prova	Perché
Bozze velocissime ed economiche	`alibaba/z-image-turbo/text-to-image`	Una decina di secondi e uno o due crediti per immagine
Buona qualità generale a basso prezzo	`black-forest-labs/flux-2-klein-9b/text-to-image`	Veloce, nitido, segue bene il prompt
Testo leggibile, poster, diagrammi	`google/nano-banana-2.1/text-to-image`, `openai/gpt-image-2/text-to-image`	Forti con scritte e impaginazione; fino al 4K
Più opzioni in una chiamata	Modelli con `num_outputs`	Un’attività, più immagini

I prezzi cambiano per modello e opzione. Modelli indica il prezzo di partenza di ciascuno; la sua pagina di riferimento elenca tutte le fasce.

Modifica con immagini di riferimento

I modelli di modifica finiscono con /edit e ricevono le immagini di partenza in image_urls, nell’ordine in cui il prompt le cita:

{
  "model": "google/nano-banana-2.1/edit",
  "input": {
    "prompt": "Turn the scene into a bright summer afternoon and keep the composition",
    "image_urls": ["https://media.popnow.ai/movie/lighthouse.webp"]
  }
}

Di’ cosa deve restare uguale, non solo cosa cambiare; i modelli di modifica prendono alla lettera «mantieni il volto e la posa».
Con più riferimenti, chiamali per posizione: «metti la giacca della seconda immagine alla persona della prima».
I file locali passano prima da un caricamento; quelli che riusi vanno nella tua libreria di asset.

Strumenti in un passaggio

Gli strumenti di PopNow ricevono una sola immagine e non richiedono prompt:

ID modello	Cosa fa
`popnow/background-remover-v1/edit`	Scontorna il soggetto su sfondo trasparente
`popnow/image-upscaler-v1/upscale`	Ingrandisce e rende più nitida un’immagine
`popnow/object-eraser-v1/edit`	Rimuove un oggetto che indichi
`popnow/image-expander-v1/edit`	Allarga l’immagine oltre i bordi

{ "model": "popnow/background-remover-v1/edit",
  "input": { "image_url": "https://media.popnow.ai/movie/lighthouse.webp" } }

Impostazioni che contano

aspect_ratio e resolution sono le due impostazioni che cambiano più spesso il prezzo. Nel dubbio chiedi a jobs/quote.
seed: se lo ometti ne viene scelto uno a caso e restituito nell’input dell’attività. Rimanda quel numero per ottenere una variante vicina a un risultato che ti piace; un seed fisso rende i tentativi confrontabili, ma non promette un’immagine identica.
output_format: png conserva trasparenza e dettagli; jpeg è più leggero.
Le impostazioni sconosciute vengono rifiutate: controlla lo schema del modello invece di copiare le impostazioni di un altro.

Prompt che funzionano

Descrivi l’immagine come se dessi istruzioni a un fotografo o a un illustratore: soggetto, ambientazione, composizione, luce, stile. «Una tazza di ceramica, vista dall’alto, su una tovaglia di lino, luce del mattino dalla finestra, colori tenui» batte «una bella foto di una tazza». Metti prima la cosa più importante ed evita lunghe liste di parole di stile che tirano in direzioni diverse.

Errori che puoi incontrare

content_rejected — il modello ha rifiutato il prompt o il riferimento. Riformula o prova un altro modello.
invalid_asset — un riferimento non è stato letto. Verifica che l’URL restituisca proprio l’immagine, oppure carica il file.
unsupported_combination — questo modello ora non gestisce questa combinazione di impostazioni; cambia quella citata nel messaggio.

Tutti rilasciano la trattenuta, quindi un’immagine fallita non costa nulla.