Documentazione APIAutenticazione e idempotenza
Chiavi API, ambiti, ID richiesta e ripetizioni sicure
Autenticazione bearer
Crea e revoca le chiavi in Impostazioni → Chiavi API. Il segreto viene mostrato una sola volta. Invialo nell'header standard:
Authorization: Bearer sd_YOUR_KEYÈ accettato solo l'header Authorization. Non sono supportate le credenziali
nella query string né X-API-Key. Una chiave mancante, non valida, scaduta o
revocata restituisce 401 UNAUTHORIZED. Una chiave valida priva dell'ambito
dell'endpoint restituisce 403 FORBIDDEN.
Ambiti
| Ambito | Consente |
|---|---|
images:generate | creare job di generazione |
images:edit | creare job di modifica |
images:convert | creare job di conversione |
jobs:read | leggere i job dello stesso account |
credits:read | leggere il saldo attuale |
Usa chiavi ristrette distinte per ogni applicazione e ambiente. Revocare una chiave non influisce sui job già creati per l'account.
Idempotenza
Tutti e tre gli endpoint POST richiedono un Idempotency-Key di lunghezza
compresa tra 8 e 255 caratteri. Ripetere lo stesso endpoint con la stessa chiave
e la stessa richiesta canonica restituisce il job originale senza una nuova
riserva di crediti. Riutilizzare la chiave con contenuti diversi restituisce
409 IDEMPOTENCY_CONFLICT.
Nelle richieste multipart, anche i byte dell'immagine di partenza fanno parte dell'identità. Cambiare l'immagine caricata mantenendo la chiave è quindi un conflitto.
ID richiesta
Ogni risposta include X-Request-Id. I corpi di errore lo ripetono in
error.request_id. Gli ID richiesta si possono conservare senza rischi nei log
applicativi.