Chiavi e indirizzo API
MarkdownDove ottenere la chiave, quale indirizzo usare nei diversi SDK e come trasmettere la chiave.
Guida completa
Chiave API
La chiave si crea nell’area personale su ailoot.ai dopo la registrazione. Ha questo aspetto: sk-…. Puoi creare più chiavi: separate per computer di lavoro, server e ciascuna applicazione — è più semplice revocarne una senza toccare le altre.
Puoi impostare per la chiave limite totale di spesa, validità, elenchi di IP consentiti e bloccati e limiti di spesa per finestre di 5 ore, 1 giorno e 7 giorni. Se una restrizione interviene, ricevi un errore chiaro: api_key_quota_exhausted (limite totale esaurito), usage_limit_reached (finestra di spesa della chiave esaurita — attendi il rinnovo della finestra o aumenta il limite), api_key_expired oppure permission_denied (ad esempio richiesta da un IP non consentito).
Indirizzo API
Regola principale: per i client OpenAI compatibili l’indirizzo include /v1, per Anthropic e Gemini non lo include.
| Client | Indirizzo di base | Destinazione della richiesta |
|---|---|---|
| OpenAI SDK e client compatibili | https://api.ailoot.ai/v1 | /v1/chat/completions, /v1/responses, /v1/embeddings |
| Anthropic SDK, Claude Code | https://api.ailoot.ai | /v1/messages |
| Google GenAI SDK, Gemini CLI | https://api.ailoot.ai | /v1beta/models/{model}:generateContent |
| Il client chiede l’indirizzo completo | https://api.ailoot.ai/v1/chat/completions | come indicato |
Come trasmettere la chiave
Ailoot accetta la chiave in uno qualsiasi dei tre header — quello inviato dal tuo SDK va bene:
| Header | Chi lo invia così |
|---|---|
Authorization: Bearer sk-… | OpenAI SDK, la maggior parte dei client |
x-api-key: sk-… | Anthropic SDK, Claude Code con ANTHROPIC_API_KEY |
x-goog-api-key: sk-… | Google GenAI SDK, Gemini CLI |
Nei percorsi /v1/… la chiave nell’indirizzo (?key= oppure ?api_key=) non è accettata: la richiesta riceve 400 con il codice invalid_request e un messaggio che segnala la chiave nell’indirizzo. Così non finisce nei log o nella cronologia del browser. Se la chiave è già stata inserita nell’indirizzo, è meglio crearne una nuova.
Nei percorsi Gemini /v1beta/… per compatibilità con Google è accettato ?key= — con la priorità più bassa, dopo gli header. ?api_key= viene rifiutato anche lì con 400. È comunque più sicuro inviare la chiave nell’header x-goog-api-key.
Variabili d’ambiente
È comodo creare una variabile unica e usarla nelle impostazioni dei vari programmi:
# ~/.zshrc o ~/.bashrc
export AILOOT_API_KEY="sk-..."
# per i programmi che leggono i nomi standard
export OPENAI_BASE_URL="https://api.ailoot.ai/v1"
export OPENAI_API_KEY="$AILOOT_API_KEY"
export ANTHROPIC_BASE_URL="https://api.ailoot.ai"
export ANTHROPIC_AUTH_TOKEN="$AILOOT_API_KEY"setx AILOOT_API_KEY "sk-..."
# per i programmi che leggono i nomi standard
setx OPENAI_BASE_URL "https://api.ailoot.ai/v1"
setx OPENAI_API_KEY "sk-..."
setx ANTHROPIC_BASE_URL "https://api.ailoot.ai"
setx ANTHROPIC_AUTH_TOKEN "sk-..."
# riavvia il terminale affinché le variabili vengano caricateVerifica della chiave
Il modo più economico per verificare la chiave è richiedere l’elenco dei modelli: è gratuito.
curl -s https://api.ailoot.ai/v1/models \
-H "Authorization: Bearer $AILOOT_API_KEY"