Soluzione API di modifica
Gli endpoint di modifica accettano almeno due input: l’immagine e l’istruzione. Far entrare l’immagine – come URL pubblico, come upload confermato o come data URI inline – è il punto in cui si blocca la maggior parte delle integrazioni.
La sfida
Il prompt è la parte facile. L’altra parte è un file che vive sul telefono dei tuoi utenti, deve arrivare al modello senza esporre un bucket privato e deve stare dentro limiti applicati prima ancora che l’attività esista.
01
Un campo immagine dichiarato accetta un URL HTTPS pubblico, un file URI spicy:// confermato o un data URI inline. L’inline è limitato a 1 MiB decodificati e 8.388.608 pixel per immagine, dentro un corpo di richiesta da 2 MiB. Tutto ciò che è più grande deve passare da un ticket di upload.
02
Un link firmato può puntare a un bucket privato se i nostri server scaricano il file senza cookie né un altro login. Mantienilo valido durante l’elaborazione. IP privati, loopback e credenziali user:password nell’URL sono rifiutati.
03
Il nome pubblico della chiamata finisce in /edit, lo schema di solito richiede image_url o image_urls, e alcuni endpoint aggiungono mask_url o strength. Un valore di model da testo a immagine infilato in un flusso di modifica fallisce la validazione invece di adattarsi.
L’approccio
Per i file degli utenti chiedi un ticket di upload, fai la PUT del numero esatto di byte con tutti gli header restituiti, conferma e passa l’URI spicy:// nel campo immagine del modello. Il riferimento diventa del tuo account, viene controllato una volta sola e si riusa su più attività senza ricaricarlo.
Ticket, PUT, conferma, creazione. I media già raggiungibili pubblicamente saltano i primi tre passaggi.
Ticket → PUT → commit → create
POST /api/v1/common/upload-url
{ "contentType": "image/png", "bytes": 482113 }
→ { "fileId": "fil_01k3…", "uploadUrl": "https://…", "method": "PUT", "headers": { … } }
PUT <uploadUrl> # exactly 482113 bytes, every returned header replayed
POST /api/v1/files/fil_01k3…/commit
→ { "status": "ready", "uri": "spicy://f/fil_01k3…", "sha256": "…" }POST /api/v1/jobs/createTask
{
"model": "<publisher>/<model>/edit",
"input": {
"prompt": "Replace the background with an overcast beach at dusk",
"image_urls": ["spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"]
}
}Contratto
| Campo o header | Valore o limite |
|---|---|
| POST /api/v1/common/upload-url | JPEG · PNG · WebP · GIF ≤ 10 MiB |
| POST /api/v1/files/{fileId}/commit | returns spicy://f/fil_… |
| inline data URI | ≤ 1 MiB decoded · ≤ 8192 px per side |
| request body | ≤ 2 MiB · ≤ 16 images |
Scorri in orizzontale per vedere tutte le colonne.
Integrazione
Scelta
Verifiche
La conferma confronta byte salvati e tipo di media con il ticket, verifica la firma dell’immagine e calcola uno SHA-256 prima che il file diventi citabile.
I data URI vengono conservati come file legati all’account. L’input normalizzato restituito da recordInfo contiene file URI, mai i byte Base64 originali.
Il materiale che carichi resta un giorno; i risultati generati restano 14 giorni. Entrambe le finestre sono pubblicate, non trattate account per account.
Prima del lancio
Domande frequenti
Modelli
Ogni link apre la pagina di quella famiglia di modelli: input, limiti, politica sui contenuti e prezzo attuale per unità.
Continua
Invia un’immagine che hai già più un’istruzione. Come entra il riferimento, quali sono i limiti in pixel e su cosa fattura un endpoint di modifica.
