Avvio rapido

Fai una prima richiesta: ottieni la tua chiave, invia un messaggio e leggi la risposta. L'API parla i formati OpenAI e Anthropic, quindi l'SDK che usi già funziona dopo aver cambiato base URL e chiave.

1. Ottieni la tua chiave

Ogni account ha una chiave API. Accedi, apri Chiavi e utilizzo e copiala. La chiave funziona su ogni endpoint e con ogni modello. Chiavi e utilizzo

2. Punta il client all'API

Tutti gli endpoint si trovano sotto un unico base URL. Un SDK OpenAI lo accetta con /v1 alla fine; un SDK Anthropic lo accetta senza, perché aggiunge da sé /v1/messages.

Client	Base URL
SDK OpenAI e client compatibili con OpenAI	`https://api.shannon-ai.com/v1`
SDK Anthropic	`https://api.shannon-ai.com`

Tre endpoint producono testo. Raggiungono gli stessi modelli; scegli quello il cui formato è già usato dal tuo codice.

Endpoint	Formato
`POST /v1/chat/completions`	OpenAI Chat Completions
`POST /v1/messages`	Anthropic Messages
`POST /v1/responses`	OpenAI Responses

3. Invia una prima richiesta

Invia un messaggio user a shannon-3 sull'endpoint Chat Completions. Sostituisci YOUR_API_KEY con la tua chiave.

POST https://api.shannon-ai.com/v1/chat/completions

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!"}
    ],
    max_tokens=1024
)

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!' }
  ],
  max_tokens: 1024
});

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

package main

import (
    "context"
    "fmt"
    openai "github.com/sashabaranov/go-openai"
)

func main() {
    config := openai.DefaultConfig("YOUR_API_KEY")
    config.BaseURL = "https://api.shannon-ai.com/v1"
    client := openai.NewClientWithConfig(config)

    resp, err := client.CreateChatCompletion(
        context.Background(),
        openai.ChatCompletionRequest{
            Model: "shannon-3",
            Messages: []openai.ChatCompletionMessage{
                {Role: "user", Content: "Hello, Shannon!"},
            },
            MaxTokens: 1024,
        },
    )
    if err != nil {
        panic(err)
    }
    fmt.Println(resp.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!"}
    ],
    "max_tokens": 1024
  }'

Campo	Tipo	Default	Descrizione
`model`	`string`		L'id del modello che risponde. Gli id sono elencati in Modelli e prezzi.
`messages`	`array`		La conversazione finora: oggetti con `role` e `content`. L'ultimo messaggio `user` è il prompt. Obbligatorio.
`max_tokens`	`integer`	`4096`	Il budget di output della richiesta, da 1 a 65,536. La richiesta riserva questa quantità dal tuo saldo e viene addebitata per ciò che ha usato davvero.
`stream`	`boolean`	`false`	`true` invia la risposta pezzo per pezzo mentre viene scritta.

Il corpo della richiesta è JSON e richiede l'header Content-Type: application/json. L'elenco completo dei campi è nella pagina dell'endpoint. Chat Completions

La risposta

Una chiamata senza stream restituisce un unico oggetto JSON quando la risposta è completa. I testi e i numeri qui sotto sono esempi.

200 JSON

{
  "id": "chatcmpl-9b2f6c1e4a7d4f0f8a3c5d2e1b6a7c90",
  "object": "chat.completion",
  "created": 1791590400,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! What would you like to work on?",
        "reasoning_content": "A greeting. A short, friendly reply fits."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1386,
    "completion_tokens": 74,
    "total_tokens": 1460
  }
}

Campo	Tipo	Descrizione
`id`	`string`	`chatcmpl-` seguito da 32 caratteri esadecimali.
`object`	`string`	Sempre `chat.completion`.
`created`	`integer`	L'ora della risposta in secondi Unix.
`model`	`string`	L'id pubblicato del modello che ha risposto, anche quando hai inviato un alias o un'altra grafia.
`choices`	`array`	Sempre una sola voce, con `index` 0.
`choices[0].message.role`	`string`	Sempre `assistant`.
`choices[0].message.content`	`string \| null`	La risposta. Può essere `null` quando la risposta porta `tool_calls`.
`choices[0].message.reasoning_content`	`string \| null`	Il ragionamento del modello prima della sua risposta, oppure `null` quando non c'è.
`choices[0].message.tool_calls`	`array`	Presente solo quando il modello chiama uno dei tool che hai dichiarato.
`choices[0].finish_reason`	`string`	`stop` per una risposta, `tool_calls` quando il modello chiama un tool.
`usage.prompt_tokens`	`integer`	I token letti dal modello per questa risposta. Su `shannon-2-*` e sulla famiglia Shannon 3 possono essere più del testo che hai inviato.
`usage.completion_tokens`	`integer`	I token scritti dal modello.
`usage.total_tokens`	`integer`	Il totale. L'addebito di un modello Shannon si calcola da questo numero.

usage contiene conteggi di token, non denaro. Quanto la chiamata ha prelevato dal tuo saldo è mostrato per richiesta in Chiavi e utilizzo; come viene calcolato è in Limiti e saldo. Limiti e saldo
Ogni risposta, anche un errore e uno stream, ha l'header x-request-id. Se la tua richiesta contiene un header x-request-id, ne torna il valore; altrimenti il valore è di 12 caratteri esadecimali. Conservalo nei tuoi log: identifica questa singola richiesta.

La stessa chiamata come stream

Imposta stream su true per leggere la risposta mentre viene scritta. Tutto il resto della richiesta resta invariato.

from openai import OpenAI

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

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

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

import OpenAI from 'openai';

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

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

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}

curl -N -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!"}
    ],
    "max_tokens": 1024,
    "stream": true
  }'

Ogni frame dello stream è una riga che inizia con data: e contiene un oggetto JSON. Un frame, stampato su più righe:

Un frame

{
  "id": "chatcmpl-9b2f6c1e4a7d4f0f8a3c5d2e1b6a7c90",
  "object": "chat.completion.chunk",
  "created": 1791590400,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "Hello! "
      },
      "finish_reason": null
    }
  ]
}

Frame, in ordine	delta	finish_reason
Mentre il modello ragiona. Zero o più frame.	`{"reasoning_content": "…"}`	`null`
La risposta, pezzo per pezzo. Zero o più frame.	`{"content": "…"}`	`null`
L'ultimo frame JSON. Porta anche `usage`; non serve richiederlo.	`{}`	`"stop"`
La fine dello stream: la riga `data: [DONE]`.

La risposta ha stato 200 e content-type: text/event-stream. Ogni frame è una riga data: <json> seguita da una riga vuota.
Una riga : ping arriva ogni 15 secondi. È un commento che mantiene aperta la connessione; i client SSE la ignorano.
Un errore dopo l'apertura dello stream arriva come frame data: {"error": {…}}. Lo stato resta 200, quindi controlla i frame.

Streaming

Se la chiamata fallisce

Un errore è un oggetto JSON con un error che contiene type e message. Queste sono le risposte che una prima chiamata incontra più spesso.

Stato	Tipo	Messaggio	Cosa significa
`401`	`authentication_error`	`Missing authentication`	Nessuna chiave è arrivata all'API. Invia `Authorization: Bearer` seguito dalla tua chiave.
`401`	`authentication_error`	`Invalid API key`	La chiave non è la chiave attuale di un account. Copiala di nuovo da Chiavi e utilizzo.
`400`	`invalid_request_error`	`unknown model: <id>`	`model` non è un id pubblicato. Usa un id da Modelli e prezzi.
`422`	`invalid_request_error`	`Failed to deserialize the JSON body into the target type…`	Un campo ha il tipo JSON sbagliato, oppure manca `messages`.
`429`	`rate_limit_error`	`Quota exceeded. Upgrade your plan at shannon-ai.com/plan`	Il budget di output della richiesta non rientra nel tuo saldo.

Gestione errori

Dove andare dopo

Modelli e prezzi — Scegli un modello: id, finestre di contesto e prezzi.
Chat Completions — Ogni campo della richiesta, campo della risposta ed evento dello stream dell'endpoint che hai chiamato.
Streaming — I frame di uno stream, le righe keep-alive e gli errori dentro uno stream.
Chiamata di funzioni — Lascia che il modello chiami le tue funzioni.
Limiti e saldo — Cosa riserva e costa una richiesta, e quante richieste puoi inviare.
Playground API — Prova le richieste nel browser con la tua chiave.