Pro API: genera e ritocca 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 route.
Invia un'immagine
POST /images
{ "prompt": "portrait of a woman in a rainy street at night, neon reflections, cinematic",
"width": 832, "height": 1216 }
| Campo | Tipo | Default | Cosa fa |
|---|---|---|---|
prompt | string | obbligatorio | La scena. L'inglese dà i risultati più precisi. |
width, height | int | 1024 x 1024 | Dimensione in pixel. Formati consigliati: 1024 x 1024 (quadrato), 832 x 1216 (verticale), 1216 x 832 (orizzontale). |
mode | string | generation | edit, img2img o inpaint, vedi sotto. Assente significa generare dal prompt. |
image_b64 | string | Immagine sorgente in base64 (PNG o JPEG), obbligatoria per tutte e tre le modalità di ritocco. Al massimo 12 MB decodificati. | |
mask_b64 | string | Maschera in base64: obbligatoria per inpaint, facoltativa per edit. Dipingi in rosso le aree da ritoccare, alle stesse dimensioni dell'immagine sorgente. | |
lora | string | Un personaggio addestrato sull'account: il name restituito da GET /loras. Inserisci il suo trigger nel prompt. | |
lora2, lora2_strength | string, number | Un secondo personaggio e la sua intensità (da 0 a 1, default 1) per una scena con due persone. | |
steps | int | engine | Lascia vuoto. Il motore conosce il proprio valore. |
La risposta:
{ "jobId": "test-79634842-4586-46d4-ad52-d9ea236ae00d", "seed": 178078967, "cost": 1 }
Il seed viene estratto dal motore e restituito a titolo informativo. Non può essere impostato in input in
questa versione.
Le tre modalità di ritocco
Tutte e tre girano sullo stesso motore di editing basato su istruzioni, che preserva l'aspetto dell'immagine
sorgente. Quando fornisci un'immagine sorgente, width e height vengono letti dall'immagine
stessa e non è necessario inviarli.
mode | Input | Cosa fa il motore |
|---|---|---|
edit | image_b64 + prompt (+ mask_b64 facoltativa) | Applica l'istruzione all'intera immagine ("add sunglasses", "make it snow"). Con una maschera, la modifica si concentra nell'area rossa. |
inpaint | image_b64 + mask_b64 + prompt | Rigenera solo l'area rossa della maschera, seguendo l'istruzione. Il resto viene ricomposto pixel per pixel. |
img2img | image_b64 + prompt | Rielabora l'intera immagine seguendo il prompt mantenendone la composizione e l'aspetto: una variazione. |
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\"}"
Polling
GET /images/{jobId}
| Risposta | Significato |
|---|---|
{ "status": "pending", "phase": "IN_QUEUE" } | In coda |
{ "status": "pending", "phase": "IN_PROGRESS" } | In elaborazione |
{ "status": "completed", "cost": 1, "file_url": "/pro/v1/images/{jobId}/file", ... } | Completato, file pronto |
{ "status": "failed", "detail": "..." } | Fallito, e non viene addebitato nulla |
Esegui il polling ogni 3 secondi, non più spesso: la coda è condivisa.
Download
GET /images/{jobId}/file
Il PNG stesso, come corpo della risposta (Content-Type: image/png). Disponibile non appena lo
stato è completed, e 404 media_indisponibile una volta che il render è andato. Scaricalo
subito, non viene archiviato.
Annulla
POST /images/{jobId}/cancel
Annulla un render in coda o in esecuzione. Risponde { "ok": true }. Non viene addebitato nulla e il costo
riservato contro il limite giornaliero della chiave viene restituito.