Chat Completions

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

La plus petite requête est un id de modèle et un message utilisateur.

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 réponse est un objet 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
  }
}

En-têtes

En-têtes de requête

En-têtes de réponse

Champs de requête

Seul messages est obligatoire. La colonne Appliqué par nomme les modèles sur lesquels un champ modifie la réponse. Les modèles open-weight hébergés sont les douze ids de la liste des modèles ; la famille Shannon 3 comprend shannon-3, shannon-3-pro, shannon-3.1 et shannon-3.1-pro. Modèles et tarifs

D'autres champs OpenAI, comme n, user, stream_options, parallel_tool_calls, presence_penalty, frequency_penalty, logit_bias, logprobs, metadata, store et prompt_cache_key, sont acceptés pour que le code client existant fonctionne sans changement. Ils ne modifient pas la réponse : il y a toujours un seul choix, et un flux se termine toujours par l'utilisation.

Un champ avec un mauvais type JSON, par exemple "max_tokens": "100", renvoie 422. Une requête sans messages aussi.

Les outils, la sortie structurée, le raisonnement et la recherche web ont chacun leur propre page : Appel de fonction, Résultats structurés, Effort de raisonnement, Recherche Web intégrée.

Une requête avec des options

Cette requête définit un message système, les champs d'échantillonnage et l'effort de raisonnement. Elle utilise un modèle open-weight hébergé, qui les applique tous.

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 réponse a la même forme que ci-dessus. Son usage ajoute deux détails sur les modèles open-weight hébergés : les tokens de prompt lus dans le cache et les tokens dépensés en raisonnement.

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

Longueur de sortie

max_tokens fait deux choses. D'abord, c'est le nombre de tokens réservés sur votre solde au début de la requête. Quand la réponse est terminée, ce montant est remplacé par les tokens que la requête a utilisés. Si max_tokens est supérieur à ce qui reste de votre solde, la requête renvoie 429 Quota exceeded même si la réponse elle-même aurait tenu. Envoyez un max_tokens plus bas pour réserver moins.

shannon-coder-1 est compté différemment sur ce point de terminaison : chaque requête est l'un des appels Shannon Coder de votre forfait, et aucun token n'est réservé pour elle. Limites et solde

Ensuite, il limite la longueur de la réponse sur ces modèles :

Sans max_tokens ni max_completion_tokens, la valeur est 4,096. Sur shannon-coder-1, elle est 65,536.

Messages

Chaque message est un objet avec un role et un content. content est une chaîne, ou un tableau de parties quand le message porte plus que du texte.

Avec un id de la famille Shannon 3, placez les instructions qui doivent être respectées dans le message user.

Sur les niveaux Shannon, une requête sans texte utilisateur et sans tools renvoie 400 No user message provided.

Parties de contenu

Les tailles, les limites et la liste complète des formes ont leur propre page. Images et fichiers

L'objet de réponse

Raisons de fin

Une réponse hors streaming indique stop ou tool_calls.

Utilisation

Sur les modèles open-weight hébergés, prompt_tokens correspond à vos messages et définitions d'outils comptés avec le tokenizer propre au modèle, plus les tokens des éventuelles images. Les points de terminaison de comptage de tokens renvoient le même nombre avant l'envoi. Décompte de tokens

Sur les niveaux Shannon, prompt_tokens compte tout ce que le modèle a lu pour écrire la réponse ; il est donc supérieur au seul texte de vos messages.

Streaming

Avec stream à true, la réponse arrive sous forme d'événements chat.completion.chunk et se termine par data: [DONE]. Le dernier chunk avant celui-ci porte finish_reason et usage ; aucun stream_options n'est nécessaire. Les formes de chunk, les lignes keep-alive et les erreurs dans un flux ont leur propre page. Diffusion en continu

Erreurs

Une erreur est un objet JSON avec un membre error. Les vérifications s'exécutent dans cet ordre : clé API, corps de la requête, id du modèle, puis solde. Le tableau liste ce que ce point de terminaison renvoie le plus souvent. La liste complète, avec ce qu'il faut réessayer, a sa propre page. Gestion des erreurs

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