Chat Completions

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

La richiesta più piccola è un id di modello e un messaggio dell'utente.

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": "Say hello in one sentence."}],
)

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: "Say hello in one sentence." }],
});

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

curl 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": "Say hello in one sentence."}]
  }'

La risposta è un oggetto JSON:

{
  "id": "chatcmpl-5f0c1e7a9b3d4c62a8e1f07d2b46c9a3",
  "object": "chat.completion",
  "created": 1791625200,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello, it is good to meet you.",
        "reasoning_content": "The user wants a greeting in one sentence. Keep it short and friendly."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1184,
    "completion_tokens": 46,
    "total_tokens": 1230
  }
}

Header

Header della richiesta

Header della risposta

Campi della richiesta

Solo messages è obbligatorio. La colonna Applicato da indica i modelli su cui un campo cambia la risposta. I modelli open-weight ospitati sono i dodici id dell'elenco dei modelli; la famiglia Shannon 3 è shannon-3, shannon-3-pro, shannon-3.1 e shannon-3.1-pro. Modelli e prezzi

Altri campi OpenAI, come n, user, stream_options, parallel_tool_calls, presence_penalty, frequency_penalty, logit_bias, logprobs, metadata, store e prompt_cache_key, sono accettati così il codice client esistente funziona senza modifiche. Non cambiano la risposta: c'è sempre una sola choice, e uno stream termina sempre con l'utilizzo.

Un campo con il tipo JSON sbagliato, per esempio "max_tokens": "100", restituisce 422. Lo stesso vale per una richiesta senza messages.

Tool, output strutturato, ragionamento e ricerca web hanno ciascuno una pagina propria: Chiamata di funzioni, Output strutturati, Sforzo di ragionamento, Ricerca web integrata.

Una richiesta con opzioni

Questa richiesta imposta un messaggio di sistema, i campi di campionamento e lo sforzo di ragionamento. Usa un modello open-weight ospitato, che li applica tutti.

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="DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    messages=[
        {"role": "system", "content": "You are a physics teacher. Answer in two sentences."},
        {"role": "user", "content": "Why is the sky blue?"},
    ],
    max_tokens=512,
    temperature=0.3,
    top_p=0.9,
    seed=7,
    stop=["\n\n"],
    reasoning_effort="low",
)

message = response.choices[0].message
print(message.reasoning_content)  # the reasoning
print(message.content)            # the answer
print(response.usage)

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: "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
  messages: [
    { role: "system", content: "You are a physics teacher. Answer in two sentences." },
    { role: "user", content: "Why is the sky blue?" },
  ],
  max_tokens: 512,
  temperature: 0.3,
  top_p: 0.9,
  seed: 7,
  stop: ["\n\n"],
  reasoning_effort: "low",
});

const message = response.choices[0].message;
console.log(message.reasoning_content); // the reasoning
console.log(message.content);           // the answer
console.log(response.usage);

curl https://api.shannon-ai.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    "messages": [
      {"role": "system", "content": "You are a physics teacher. Answer in two sentences."},
      {"role": "user", "content": "Why is the sky blue?"}
    ],
    "max_tokens": 512,
    "temperature": 0.3,
    "top_p": 0.9,
    "seed": 7,
    "stop": ["\n\n"],
    "reasoning_effort": "low"
  }'

La risposta ha la stessa forma di quella sopra. Il suo usage aggiunge due dettagli sui modelli open-weight ospitati: i token del prompt letti dalla cache e i token spesi per il ragionamento.

{
  "usage": {
    "prompt_tokens": 31,
    "completion_tokens": 62,
    "total_tokens": 93,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 21
    }
  }
}

Lunghezza dell'output

max_tokens fa due cose. Primo, è il numero di token messi da parte dal tuo saldo quando la richiesta inizia. Quando la risposta è completa, quella quantità viene sostituita dai token effettivamente usati dalla richiesta. Se max_tokens è maggiore di ciò che resta del tuo saldo, la richiesta restituisce 429 Quota exceeded anche se la risposta stessa ci sarebbe stata. Invia un max_tokens più basso per mettere da parte meno.

shannon-coder-1 su questo endpoint è conteggiato in modo diverso: ogni richiesta è una delle chiamate Shannon Coder del tuo piano e non viene messo da parte alcun token. Limiti e saldo

Secondo, limita la lunghezza della risposta su questi modelli:

Senza max_tokens o max_completion_tokens, il valore è 4,096. Su shannon-coder-1 è 65,536.

Messaggi

Ogni messaggio è un oggetto con un role e un content. content è una stringa, oppure un array di parti quando il messaggio contiene più del solo testo.

Con un id della famiglia Shannon 3, inserisci nel messaggio user le istruzioni che devono valere.

Sui livelli Shannon una richiesta senza testo dell'utente e senza tools restituisce 400 No user message provided.

Parti di contenuto

Dimensioni, limiti e l'elenco completo delle forme hanno una pagina propria. Immagini e file

L'oggetto della risposta

Motivi di conclusione

Una risposta senza streaming riporta stop o tool_calls.

Utilizzo

Sui modelli open-weight ospitati, prompt_tokens sono i tuoi messaggi e le definizioni dei tool contati con il tokenizer del modello stesso, più i token delle eventuali immagini. Gli endpoint di conteggio dei token restituiscono lo stesso numero prima dell'invio. Conteggio dei token

Sui livelli Shannon, prompt_tokens conta tutto ciò che il modello ha letto per scrivere la risposta, quindi è maggiore del solo testo dei tuoi messaggi.

Streaming

Con stream impostato su true la risposta arriva come eventi chat.completion.chunk e termina con data: [DONE]. L'ultimo chunk prima di esso porta finish_reason e usage; non servono stream_options. Le forme dei chunk, le righe keep-alive e gli errori all'interno di uno stream hanno una pagina propria. Streaming

Errori

Un errore è un oggetto JSON con un membro error. I controlli vengono eseguiti in quest'ordine: chiave API, corpo della richiesta, id del modello, poi saldo. La tabella elenca ciò che questo endpoint restituisce più spesso. L'elenco completo, con cosa riprovare, ha una pagina propria. Gestione errori

{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: no-such-model"
  }
}