Autenticazione

Ogni chiamata API che crea, legge o fattura qualcosa include la chiave API nell'header Authorization. (L'unica eccezione è il catalogo pubblico dei modelli usato per la valutazione: non richiede una chiave.)

Authorization: Bearer sk-spicy-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

L'API nativa (/api/v1/*) accetta soltanto chiavi bearer: niente cookie né parametri nella query.

Gli endpoint di compatibilità per testo e video (/v1, /v1beta) usano la stessa chiave e accettano anche l'header x-api-key degli SDK Anthropic e l'header x-goog-api-key degli SDK Google GenAI, così gli SDK ufficiali funzionano cambiando soltanto l'URL di base: consulta Testo e streaming. Quei due header non hanno effetto su /api/v1 e nessun endpoint accetta una chiave nella query string dell'URL.

Chiavi API e console sono separate

Soltanto /api/v1, /v1 e /v1beta accettano chiavi API. La console web usa una propria sessione nel browser. Quindi l'accesso alla console non può essere usato come chiave API e una chiave API esposta non permette di accedere alla console. Inviare il tipo sbagliato di credenziale restituisce sempre 401, mai un errore di permessi.

Come è fatta una chiave

Un prefisso fisso sk-spicy- seguito da 48 caratteri esadecimali minuscoli.

Il prefisso è intenzionale: è meglio ricevere una notifica dalla scansione che scoprirlo quando qualcun altro ha già consumato il saldo.

Creare una chiave

1. Apri Console → Chiavi API e fai clic su Crea chiave.
2. Assegnale un nome legato al servizio che la userà (production backend, staging worker). Dovrai riconoscerla quando la revochi.
3. Se vuoi, apri Avanzate per impostare limiti di spesa, un elenco di modelli consentiti, un elenco di IP consentiti e una data di scadenza. Puoi modificarli tutti in seguito.
4. Copia la chiave oppure fai clic su Salva come file e conferma di averla conservata. Dopo la chiusura della finestra, la chiave non può più essere mostrata.

Creare chiavi richiede il ruolo di proprietario, amministratore o sviluppatore nel team e la chiave appartiene al team selezionato in alto a sinistra nella console: utilizzo e limiti vengono conteggiati per quel team. Ogni team può avere fino a 50 chiavi attive. Prima che la chiave possa eseguire attività a pagamento, il tuo account deve anche avere un'email verificata e un saldo; consulta Configurazione dell'account.

Dove conservare la chiave

• Sul computer, per i test: export SPICY_API_KEY="…" nel terminale (resta valido finché non chiudi la finestra), oppure un file .env caricato dal tuo codice. Aggiungi .env a .gitignore prima del primo commit.
• Su un server o una piattaforma di hosting: usa le impostazioni per i segreti o le variabili d'ambiente e leggi SPICY_API_KEY dall'ambiente nel tuo codice.
• Non incollare mai la chiave nel codice sorgente, in una chat, in uno screenshot, in un ticket di assistenza o nel prompt di un assistente AI.

Non distribuire mai una chiave al client

Lo stesso vale per binari mobili, client desktop, notebook pubblici, log CI e qualsiasi cosa finisca in un output di curl -v incollato in un ticket di assistenza.

I tuoi strumenti nel tuo browser sono un caso diverso. L'API accetta chiamate dai browser, quindi gli strumenti che esegui per te stesso, come l'estensione SillyTavern o un'app di roleplay in cui incolli la tua chiave, possono chiamarla direttamente. La regola precedente riguarda l'inserimento di una chiave in qualcosa che altre persone caricano. Assegna a ciascuno di questi strumenti una chiave propria con un limite giornaliero, così puoi vedere la sua spesa e revocarla separatamente.

Restrizioni per chiave

Configura queste restrizioni nella console, quando crei la chiave o in seguito. Vengono applicate sul server.

La scheda di ciascuna chiave mostra i limiti attuali, che puoi modificare lì in qualsiasi momento.

I limiti conteggiano sia il denaro bloccato per le attività in esecuzione sia quello già speso, quindi una chiave può raggiungere il limite mentre le attività sono ancora in corso. msg indica quale limite è stato raggiunto. Un 40202 il cui msg menziona la quota della piattaforma non riguarda la tua chiave: crearne un'altra non aiuta, quindi riprova più tardi.

L'elenco di IP consentiti viene confrontato con il tuo vero indirizzo pubblico visto dalla nostra rete perimetrale, non con l'indirizzo dell'ultimo proxy. Il tuo indirizzo di uscita è l'IP pubblico da cui provengono le richieste del server: la maggior parte delle piattaforme di hosting lo indica nelle impostazioni di rete e sulla tua macchina curl https://ifconfig.me lo mostra.

Le attività appartengono alla chiave che le ha create

Un'attività è visibile attraverso l'API soltanto alla chiave API che l'ha creata. Con qualsiasi altra chiave, anche dello stesso team:

Due cose non sono legate alla chiave. I webhook di un'attività vengono consegnati anche dopo la revoca della chiave che l'ha creata. E ogni attività del team, qualunque sia la chiave che l'ha creata, è elencata sotto Console → Log, dove il dettaglio di ogni attività mostra la Chiave utilizzata.

Rotazione

• Una chiave per ambiente (produzione / staging / locale), così puoi revocarne una senza toccare le altre.
• Rotazione pianificata: crea la nuova chiave e invia con essa soltanto le nuove attività. Mantieni attiva la vecchia chiave finché ogni attività che ha creato non abbia raggiunto uno stato finale (al massimo entro il suo deadlineAt) e tu abbia raccolto i risultati, poi revocala. Usa questa sequenza soltanto quando la vecchia chiave è ancora affidabile.
• La revoca ha effetto immediato e non può essere annullata. Non c'è una cache da attendere né un modo per riattivare la chiave; devi crearne una nuova.

Dopo un'esposizione

Se si è verificata una spesa inattesa, contattaci tramite Console → Assistenza con gli ID delle attività o i valori di request_id.

Come appare un errore

{
  "code": 401,
  "msg": "Credentials are invalid or expired",
  "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2"
}

Anche lo stato HTTP è 401. Ogni errore di autenticazione restituisce code: 401 e msg indica di che tipo è:

Basa la logica sul code, non sul testo: la formulazione può cambiare e segue la tua lingua degli errori. Trovi ulteriori dettagli su come distinguerli in Errori.

Quando è l'account stesso a non poter chiamare l'API (email non verificata, account sospeso), ricevi invece 403. Cambiare chiave non aiuta in quel caso.