Developer guide
Autenticazione con una chiave API
L’header in cui inserire la chiave API e il base URL da impostare nell’SDK
Questa pagina descrive come autenticarsi al gateway CLEVI con una chiave API.
Sia il percorso compatibile con OpenAI sia quello compatibile con Anthropic usano una sola chiave per l’autenticazione,
ma l’header in cui inserire la chiave e il base URL da impostare nell’SDK variano in base alla specifica.
Header di autenticazione
Entrambe le specifiche compatibili usano una sola chiave API per l’autenticazione. La chiave viene rilasciata nella schermata delle chiavi API della console; nella stessa schermata è possibile gestirne la revoca e l’ambito di utilizzo.
| Header | Compatibile con OpenAI | Compatibile con Anthropic |
|---|---|---|
| X-API-Key: <키> | Disponibile | Disponibile |
| Authorization: Bearer <키> | Disponibile | Disponibile |
| Authorization: <키> (senza Bearer) | Rifiutato | Disponibile |
Il nome dell’header non fa distinzione tra maiuscole e minuscole. Anche x-api-key inviato dall’SDK Anthropic funziona così com’è.
base URL
È sufficiente sostituire il base URL dell’SDK in uso con uno degli indirizzi riportati di seguito. I due indirizzi differiscono per la presenza di /v1.
| Specifica | base URL | Regola del percorso |
|---|---|---|
| Compatibile con OpenAI | https://platform.clevi.net/api/v2/aiservice/openai/v1 | Includere /v1 nel base URL. |
| Compatibile con Anthropic | https://platform.clevi.net/api/v2/aiservice/anthropic | L’SDK Anthropic aggiunge automaticamente /v1 al percorso, quindi il base URL termina prima di /v1. |
Verifica dell’autenticazione
Inserendo la chiave e il base URL e recuperando l’elenco dei modelli, è possibile verificare subito se l’autenticazione è riuscita. I tre esempi seguenti eseguono la stessa richiesta con curl, OpenAI SDK e Anthropic SDK.
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"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)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)Al posto di sk-... inserire la chiave rilasciata nella schermata delle chiavi API.
- Se la risposta è 200, l’autenticazione è riuscita. data contiene l’elenco dei modelli che possono essere chiamati con questa chiave.
- Se la risposta è 401, verificare seguendo l’ordine indicato nella sezione relativa al fallimento dell’autenticazione riportata di seguito.
Header utilizzati insieme
Sono tutti facoltativi. Per tracciare i problemi, è consigliabile includere X-Request-Id.
| Header | Utilizzo | Se omesso |
|---|---|---|
| X-Request-Id | Identificatore per il tracciamento delle richieste. Nelle risposte compatibili con Anthropic viene restituito nell'header request-id. | Viene emesso dal server. |
| X-Region-Code | Regione della chiamata | È global. |
| X-Product-Sku (disponibile anche come query product_sku) | Specifica direttamente il Product SKU da utilizzare per la fatturazione. L'header ha la precedenza sulla query ed è utilizzato principalmente nei percorsi audio e voice. | È necessario nei percorsi voice. audio/speech e audio/transcriptions scelgono il Product tramite model nel corpo della richiesta. |
| anthropic-version / anthropic-beta | Vengono inoltrati così come sono nei percorsi compatibili con Anthropic. | La versione è 2023-06-01. |
Errore di autenticazione
Se non invii una chiave o invii una chiave scaduta o revocata, viene restituito 401. Se effettui una chiamata senza chiave nel percorso compatibile con OpenAI, viene restituito il corpo riportato di seguito; nel percorso compatibile con Anthropic, error.type è authentication_error.
{
"error": {
"message": "API key is required.",
"type": "invalid_request_error"
}
}- Controlla lo stato della chiave nella schermata delle chiavi API. Se la chiave è scaduta o revocata, emettine una nuova.
- Verifica che il nome dell'header sia X-API-Key o Authorization.
- Se utilizzi Authorization nel percorso compatibile con OpenAI, verifica il prefisso Bearer.