Panoramica

Endpoint

Ogni endpoint si trova sotto un unico URL di base ed è servito tramite HTTPS.

https://api.shannon-ai.com

I tre endpoint che producono testo raggiungono gli stessi modelli. Scegli quello il cui formato è già usato dal tuo codice.

Nozioni di base sulle richieste

• Il corpo di ogni POST è un solo oggetto JSON, fino a 32 MiB.
• Un campo che l'API non conosce non causa errori e non ha effetto. Una richiesta scritta per un altro provider non fallisce a causa di un campo in più.
• Un campo noto con il tipo JSON sbagliato, o un campo obbligatorio mancante, riceve come risposta 422. Un corpo che non è JSON valido riceve come risposta 400.
• model è uno degli id in Modelli e prezzi. Maiuscole e minuscole non contano.

Una risposta è JSON, oppure uno stream di server-sent events quando la richiesta imposta stream su true. Ogni endpoint risponde nel proprio formato. Ogni risposta ha l'header x-request-id.

Cosa supera una richiesta

Una richiesta viene verificata in un ordine fisso prima che un modello venga eseguito. Risponde il primo controllo che fallisce, quindi un 401 non ti dice ancora nulla sul corpo.

Forma degli errori

Un errore è un oggetto JSON con un error che contiene type e message. /v1/messages lo racchiude come si aspettano gli SDK Anthropic; ogni altro percorso usa la forma OpenAI.

{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

• Leggi type e message. code e param sono presenti solo in alcuni errori: trattali come facoltativi. param è sempre null.
• Dopo l'avvio di uno stream, lo stato è già 200. Un errore arriva allora come frame di errore all'interno dello stream.
• Ogni risposta di errore porta l'header x-request-id.

Gestione errori

Fatturazione e saldo

• C'è un solo saldo per account, e chat e API lo condividono: prima la quota del piano di oggi, poi il credito acquistato. L'API non ha una quota propria.
• Una richiesta riserva il proprio budget di output (max_tokens, default 4,096) e viene poi addebitata per i token realmente usati, al prezzo del modello.
• Ogni risposta riporta i suoi conteggi di token in usage. La pagina Chiavi e utilizzo mostra il saldo e quanto è costata ogni richiesta.
• Ogni richiesta è servita allo stesso modo. L'unico limite alla frequenza delle richieste è la flood protection: 120 richieste al minuto per account. Le richieste inviate in parallelo attendono in coda.

Limiti e saldo Modelli e prezzi Chiavi e utilizzo

Campi che dipendono dal modello

Ogni modello accetta la stessa richiesta. Alcuni campi hanno effetto solo su certi modelli; la tabella indica dove. Le pagine degli endpoint elencano ogni campo.

Chat Completions

Se arrivi da un SDK OpenAI

• Imposta l'URL di base su https://api.shannon-ai.com/v1 e la chiave sulla tua chiave Shannon. Le chiamate a Chat Completions e Responses funzionano poi con l'SDK così com'è.
• model deve essere un id Shannon. Il nome di un modello di un altro provider, come gpt-4o, riceve come risposta 400 e unknown model.
• Il ragionamento arriva in un campo a parte: reasoning_content accanto a content, sia nel messaggio sia nei delta dello stream.
• Uno stream porta sempre usage nell'ultimo chunk, insieme a finish_reason.
• Una chiamata di tool in uno stream arriva come un unico chunk con la stringa arguments completa.
• Una risposta ha una sola choice.
• I percorsi dell'API OpenAI che non compaiono nella tabella qui sopra, come /v1/embeddings, ricevono risposta 404.

Se arrivi da un SDK Anthropic

• Imposta l'URL di base su https://api.shannon-ai.com, senza /v1, e la chiave sulla tua chiave Shannon. L'SDK la invia come x-api-key.
• model deve essere un id Shannon.
• max_tokens è facoltativo su questa API. Il suo default è 4,096.
• Una risposta contiene blocchi di contenuto di tipo thinking, text e tool_use. Il primo blocco non è sempre il testo: scegli i blocchi in base al type.
• stop_reason è end_turn o tool_use. Uno stream di un modello Shannon può terminare anche con max_tokens.
• anthropic-version e anthropic-beta sono accettati, quindi l'SDK funziona senza modifiche. Una richiesta non ne ha bisogno.
• Gli errori su /v1/messages hanno la forma Anthropic: {"type": "error", "error": {…}}.

Gli strumenti di programmazione che parlano questi formati si configurano allo stesso modo: URL di base, chiave e un id Shannon come modello. Strumenti CLI per la programmazione