Autenticazione

Authorization: Bearer YOUR_API_KEY

x-api-key: YOUR_API_KEY

Header accettati

Entrambi gli header vengono letti su ogni endpoint /v1, qualunque sia il formato dell'endpoint. Invia uno dei due.

Con un SDK OpenAI, imposta la chiave e l'URL di base; l'SDK invia Authorization: Bearer.

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1"
)

response = client.chat.completions.create(
    model="shannon-3",
    messages=[
        {"role": "user", "content": "Hello, Shannon!"}
    ]
)

print(response.choices[0].message.content)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.shannon-ai.com/v1'
});

const response = await client.chat.completions.create({
  model: 'shannon-3',
  messages: [
    { role: 'user', content: 'Hello, Shannon!' }
  ]
});

console.log(response.choices[0].message.content);

curl -X POST "https://api.shannon-ai.com/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shannon-3",
    "messages": [
      {"role": "user", "content": "Hello, Shannon!"}
    ]
  }'

Con un SDK Anthropic, imposta la chiave e l'URL di base senza /v1; l'SDK invia x-api-key.

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com"
)

message = client.messages.create(
    model="shannon-3",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Shannon!"}
    ]
)

print("".join(block.text for block in message.content if block.type == "text"))

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.shannon-ai.com'
});

const message = await client.messages.create({
  model: 'shannon-3',
  max_tokens: 1024,
  messages: [
    { role: 'user', content: 'Hello, Shannon!' }
  ]
});

console.log(message.content.filter((block) => block.type === 'text').map((block) => block.text).join(''));

curl -X POST "https://api.shannon-ai.com/v1/messages" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shannon-3",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello, Shannon!"}
    ]
  }'

Quali endpoint richiedono una chiave

La tua chiave

• Una chiave è sk- seguito da 43 caratteri tra A–Z, a–z, 0–9, - e _: 46 caratteri in totale.
• Ogni account ha esattamente una chiave. Viene creata la prima volta che apri Chiavi e utilizzo.
• La chiave dà accesso completo all'API per il tuo account: ogni endpoint, ogni modello e l'intero saldo.
• Una chiave non ha data di scadenza. Funziona finché non la ruoti o la revochi.

Ruotare e revocare

Ruoti e revochi la chiave nella pagina Chiavi e utilizzo. Chiavi e utilizzo

• Entrambe hanno effetto subito: la richiesta successiva con la vecchia chiave riceve 401. Considera 60 secondi come limite massimo prima che la vecchia chiave sia rifiutata ovunque.
• Tutti i client dell'account usano la stessa chiave, quindi una rotazione li raggiunge tutti. Inserisci la nuova chiave nei tuoi client subito dopo la rotazione.
• Saldo, utilizzo e flood protection appartengono all'account, non alla chiave. Una nuova chiave prosegue con lo stesso saldo e lo stesso conteggio di richieste per il minuto in corso.

Errori

Ogni errore di autenticazione ha stato 401 e tipo authentication_error. Il messaggio distingue i casi.

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key",
    "code": "invalid_api_key",
    "param": null
  }
}

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

• Su ogni percorso tranne /v1/messages l'oggetto error contiene anche code: "invalid_api_key", anche per una chiave mancante, e param: null.
• La chiave viene verificata prima che il corpo sia letto. Una richiesta senza una chiave valida riceve 401 anche quando il suo corpo non è valido o è troppo grande.
• Un valore Authorization: Bearer che non inizia con sk- non viene trattato come chiave API. Riceve 401 con un messaggio che indica che il token non è valido o è scaduto.

Browser e CORS

• L'API risponde alle richieste cross-origin dei browser solo per un elenco fisso di origini. Il JavaScript in una pagina di un'altra origine non può leggere le risposte /v1.
• Chiama l'API dal tuo server e fai parlare la tua pagina con il tuo server. Così la chiave resta anche fuori dal sorgente della pagina.
• Il codice lato server e gli strumenti a riga di comando non sono interessati: questa regola è applicata solo dai browser.
• Un accesso su shannon-ai.com non autentica le richieste /v1. I cookie non vengono letti lì; la chiave è l'unica credenziale.
• Per un'origine consentita, un browser può inviare content-type, authorization, x-api-key, anthropic-version, anthropic-beta, openai-beta e x-request-id, e può leggere l'header di risposta x-request-id.

Proteggere la chiave

• Tieni la chiave su un server. Non inserirla in pagine web, app mobili o repository pubblici: chi la possiede può spendere l'intero tuo saldo.
• Carica la chiave da una variabile d'ambiente o da un secret store invece di scriverla nel codice.
• Se la chiave potrebbe essere trapelata, ruotala in Chiavi e utilizzo. La vecchia chiave smette subito di funzionare.
• Dopo una fuga di dati, leggi l'elenco delle richieste in Chiavi e utilizzo. Mostra tutte le richieste effettuate dalla chiave negli ultimi 30 giorni.