Autenticazione con una chiave API

Il gateway CLEVI autentica i percorsi compatibili con OpenAI e quelli compatibili con Anthropic usando un’unica chiave API.
Nel client è necessario configurare due valori: l’header di autenticazione che contiene la chiave e il base URL dell’SDK. Il formato dell’header e il base URL consentiti variano in base alla specifica.
Dopo aver completato la configurazione, è possibile verificare immediatamente l’autenticazione recuperando l’elenco dei modelli.
Se l’autenticazione non riesce, viene restituito 401; se, dopo l’autenticazione, non vengono soddisfatti i requisiti di autorizzazione o di limite, viene restituito 403.

Genera la chiave API nella schermata delle chiavi API della console. Nella stessa schermata puoi gestire la revoca della chiave e il suo ambito di utilizzo.

Header di autenticazione

Entrambe le specifiche inseriscono la chiave API in un singolo header della richiesta. È possibile usare l’header X-API-Key o l’header Authorization; il formato consentito varia in base alla specifica.

Nel percorso compatibile con OpenAI, quando si usa l’header Authorization è necessario il prefisso Bearer. Se si invia solo la chiave senza il prefisso, il gateway rifiuta la richiesta.

Il nome dell’header non distingue tra maiuscole e minuscole, quindi anche l’header x-api-key inviato dall’SDK Anthropic funziona senza modifiche. Se vengono specificati entrambi gli header, viene applicato prima il valore di X-API-Key.

base URL

Gli SDK già in uso possono continuare a essere utilizzati cambiando solo il base URL con uno degli indirizzi indicati di seguito. Poiché i due indirizzi differiscono per la presenza di /v1, specifica esattamente l’indirizzo corrispondente alla specifica.

Verifica dell’autenticazione

Dopo aver impostato la chiave e il base URL, puoi verificare l'autenticazione recuperando l'elenco dei modelli. Gli esempi di seguito eseguono la stessa richiesta con curl, OpenAI SDK e Anthropic SDK. Inserisci al posto di sk-... la chiave generata nella schermata delle chiavi API.

Quando recuperi l'elenco con curl, specifica il percorso completo fino a /v1/models per entrambi gli standard. Il primo comando utilizza l'header X-API-Key per il percorso compatibile con OpenAI, mentre il secondo utilizza l'header Authorization per il percorso compatibile con Anthropic.

curl https://platform.clevi.net/api/v2/aiservice/openai/v1/models \
  -H "X-API-Key: sk-..."

curl https://platform.clevi.net/api/v2/aiservice/anthropic/v1/models \
  -H "Authorization: Bearer sk-..." \
  -H "anthropic-version: 2023-06-01"

Con OpenAI SDK, specifica un indirizzo che includa /v1 in base_url.

from openai import OpenAI

client = OpenAI(
    api_key="sk-...",
    base_url="https://platform.clevi.net/api/v2/aiservice/openai/v1",
)

for model in client.models.list():
    print(model.id)

Con Anthropic SDK, specifica in base_url un indirizzo che termini prima di /v1.
Per l'autenticazione, utilizza invariato l'header x-api-key inviato dall'SDK.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-...",
    base_url="https://platform.clevi.net/api/v2/aiservice/anthropic",
)

for model in client.models.list(limit=20).data:
    print(model.id)

Se la risposta di uno qualsiasi degli esempi è 200, l'autenticazione è riuscita e data nella risposta contiene l'elenco dei modelli che puoi chiamare con questa chiave. Se ricevi 401, verifica la causa seguendo l'ordine indicato nella sezione successiva.

Autenticazione non riuscita

Se invii una chiave assente, scaduta o revocata, viene restituito 401. Se effettui una chiamata senza chiave sul percorso compatibile con OpenAI, viene restituito il corpo riportato di seguito; sul percorso compatibile con Anthropic, error.type è authentication_error.

{
  "error": {
    "message": "API key is required.",
    "type": "invalid_request_error"
  }
}

Se ricevi 401, esegui le verifiche nel seguente ordine.

1. Controlla lo stato della chiave nella schermata delle chiavi API. Se la chiave è scaduta o revocata, generane una nuova.
2. Verifica che il nome dell'header sia X-API-Key o Authorization.
3. Se utilizzi l'header Authorization sul percorso compatibile con OpenAI, verifica che includa il prefisso Bearer.

Dopo aver apportato le modifiche, esegui nuovamente il recupero dell'elenco dei modelli nella sezione Verifica dell'autenticazione e controlla che venga restituito 200.

Header utilizzati insieme

Tutti gli header seguenti sono facoltativi. Per facilitare il tracciamento dei problemi, consigliamo di specificare X-Request-Id.

Se gli errori 5xx si ripetono, segnalatelo all'assistenza e al supporto insieme a X-Request-Id. Se il valore è stato specificato direttamente, può essere confrontato immediatamente con i registri del client.