Pro API: generare e ritoccare immagini

Un'immagine costa 1 credito, qualunque sia la modalità. La generazione da un prompt e il ritocco di un'immagine che fornisci tu passano entrambi per la stessa rotta.

POST /images/quote accetta lo stesso corpo e risponde con il prezzo senza creare nulla, sempre { "cost": 1, ... } in questo caso. Esiste per simmetria con i video, dove il prezzo può variare.

Invia un'immagine

POST /images

{ "prompt": "portrait of a woman in a rainy street at night, neon reflections, cinematic",
  "width": 832, "height": 1216 }

La risposta:

{ "jobId": "test-79634842-4586-46d4-ad52-d9ea236ae00d", "seed": 178078967, "cost": 1 }

Il seed viene restituito nella risposta, che tu lo abbia fornito o sia stato estratto casualmente: conservalo per rendere di nuovo la stessa immagine, o una sua variazione.

Richiedere più immagini contemporaneamente

Con count superiore a 1, una sola richiesta avvia più rendering, ognuno con il proprio seed, e la risposta li elenca tutti:

{ "count": 4, "requested": 4, "cost_total": 4,
  "jobs": [ { "jobId": "...", "seed": 178078967, "cost": 1 }, { "jobId": "...", "seed": 903412, "cost": 1 } ],
  "errors": [],
  "jobId": "...", "seed": 178078967, "cost": 1 }

Due cose da leggere con attenzione.

Il jobId, il seed e il cost del primo rendering vengono ripetuti al livello superiore. È lì perché i client scritti prima delle batch continuino a funzionare senza modifiche, non perché il primo sia più importante. Fai il polling di ogni elemento di jobs, non solo di quello.

E confronta count con requested. Un rifiuto a metà, per mancanza di crediti o perché la chiave ha raggiunto il limite giornaliero, interrompe la batch nel punto in cui si trova: requested è quello che hai chiesto, count è quello che è effettivamente partito, e errors spiega perché si è fermato. Un client che presuppone che i due siano uguali perde rendering in silenzio.

POST /images/quote accetta anche count e calcola il prezzo dell'intera batch. I video non hanno count: una richiesta, un clip.

Le tre modalità di ritocco

Tutte e tre girano sullo stesso motore di editing guidato da istruzioni, che preserva l'aspetto dell'immagine sorgente. Quando fornisci un'immagine sorgente, width e height vengono lette dall'immagine stessa e non è necessario inviarle.

In edit, il server sceglie da solo il modo migliore di trattare il ritocco, come l'app:

• con una maschera: legge l'istruzione e sceglie tra sostituire il contenuto della zona (un altro oggetto, un altro capo, un volto: la zona viene ridisegnata in base a ciò che deve comparirvi) e modificare ciò che c'è (colore, materiale, luce). Con un lora di personaggio, la zona viene sempre ridisegnata, volto compreso;
• senza maschera, con un lora di personaggio ("replace the woman with kara..."): il server trova la persona della foto e la ridisegna con il personaggio; se non trova nessuno, l'istruzione si applica a tutta l'immagine, come prima.

Stesso prezzo in ogni caso (1 credito per immagine). La scelta si vede nel risultato, non nella risposta.

IMG=$(base64 -w0 photo.png)
curl -s $B/images -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d "{\"mode\":\"edit\",\"prompt\":\"add a red scarf, keep everything else identical\",\"image_b64\":\"$IMG\"}"

Crea un'immagine con personaggi, oggetti e un'ambientazione

Aggiungi un oggetto multiref a POST /images e il server fa recitare i tuoi personaggi (Personaggi), i tuoi oggetti e animali e un'ambientazione (Soggetti) insieme in una sola immagine, ognuno riconoscibile, come la schermata «Crea un'immagine» dell'app. Chiama ognuno con @Nome nel prompt, in inglese.

{ "prompt": "@Mia hands a cup of coffee to @Tom on a sunny terrace, both smiling",
  "multiref": {
    "characters": [
      { "character_id": "chr_8f3a...", "name": "Mia", "view": 1 },
      { "character_id": "chr_21bc...", "name": "Tom", "lora": "tom_v1", "strength": 1.0, "lora_pass": 0.55 }
    ],
    "subjects": [ { "subject_id": "sub_...", "name": "Mug" } ],
    "location": { "subject_id": "sub_...", "name": "Terrace" }
  },
  "width": 1344, "height": 768, "seed": 42, "count": 1 }

• Al massimo 4 soggetti (personaggi, oggetti e animali). Senza LoRA, solo da immagini: al massimo 4 riferimenti, ambientazione compresa. Il server sceglie il metodo in base ai riferimenti, e colloca ciascuno nell'ordine di characters e poi di subjects, da sinistra a destra.
• Un @Nome che non corrisponde a nessun riferimento viene rifiutato (unknown_mention); un riferimento assente dal prompt viene inviato comunque.
• Prezzo: una passata costa il prezzo di un'immagine (1 credito). Un'immagine semplice è 1 passata; più personaggi interpretati da un LoRA, 1 più una passata per LoRA (al massimo 4); solo da immagini, una passata per ogni riferimento oltre il primo; un mix, entrambe le cose. Il totale (passate x count) viene riservato all'invio e addebitato una sola volta, all'immagine finale: un errore o un annullamento non costa nulla. POST /images/quote con lo stesso corpo dà il prezzo esatto, il metodo e le sue passate, senza avviare nulla.
• Risposta 202: { "jobId": "mri_...", "seed", "cost", "method", "passes", "billed_passes" } (con count 2: jobs e cost_total). Polling, download e annullamento usano le solite rotte qui sotto; durante il rendering, progress indica la passata in corso ("2/3"). Un'immagine richiede da 1 a 3 minuti.
• L'immagine finale resta disponibile per 1 ora, e 10 minuti dopo il suo primo download. Una passata fallita dà status: "failed" con reason: "render_failed"; un annullamento, reason: "cancelled".
• Errori: invalid_count, invalid_view, invalid_lora_pass, invalid_subject_image, invalid_size, character_not_ready, più quelli di Multi-Ref (unknown_character, unknown_subject, unknown_lora, unknown_mention, multiref_too_many_references, invalid_strength...). Vedi Limiti ed errori.

Polling

GET /images/{jobId}

Fai il polling ogni 3 secondi, non più spesso: la coda è condivisa.

Download

GET /images/{jobId}/file

Il file PNG vero e proprio, come corpo della risposta (Content-Type: image/png). Disponibile non appena lo stato è completed, e 404 media_unavailable una volta che il rendering è scaduto. Scaricalo subito, non viene archiviato.

Annullamento

POST /images/{jobId}/cancel

Annulla un rendering in coda o in esecuzione. Risponde { "ok": true }. Non viene addebitato nulla, e il costo riservato al limite giornaliero della chiave viene restituito.