Chat Completions

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

The smallest request is a model id and one user message.

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."}]
  }'

The reply is one JSON object:

{
  "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
  }
}

Headers

Request headers

Reply headers

Request fields

Only messages is required. The Applied by column names the models on which a field changes the reply. The hosted open-weight models are the twelve ids of the model list; the Shannon 3 family is shannon-3, shannon-3-pro, shannon-3.1 and shannon-3.1-pro. Models & pricing

Other OpenAI fields, such as n, user, stream_options, parallel_tool_calls, presence_penalty, frequency_penalty, logit_bias, logprobs, metadata, store and prompt_cache_key, are accepted so that existing client code runs unchanged. They do not change the reply: there is always one choice, and a stream always ends with usage.

A field with the wrong JSON type, for example "max_tokens": "100", returns 422. A request without messages does too.

Tools, structured output, reasoning and web search each have their own page: Function Calling, Structured Outputs, Reasoning effort, Built-in Web Search.

A request with options

This request sets a system message, the sampling fields and the reasoning effort. It uses a hosted open-weight model, which applies all of them.

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"
  }'

The reply has the same shape as above. Its usage adds two details on the hosted open-weight models: the prompt tokens read from cache and the tokens spent on reasoning.

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

Output length

max_tokens does two things. First, it is the number of tokens set aside from your balance when the request starts. When the reply is complete, that amount is replaced by the tokens the request used. If max_tokens is larger than what is left of your balance, the request returns 429 Quota exceeded even when the reply itself would have fitted. Send a lower max_tokens to set aside less.

shannon-coder-1 is counted differently on this endpoint: each request is one of your plan's Shannon Coder calls, and no tokens are set aside for it. Limits and balance

Second, it limits the length of the reply on these models:

Without max_tokens or max_completion_tokens, the value is 4,096. On shannon-coder-1 it is 65,536.

Messages

Each message is an object with a role and a content. content is a string, or an array of parts when the message carries more than text.

With a Shannon 3 family id, put instructions that must hold into the user message.

On the Shannon tiers a request with no user text and no tools returns 400 No user message provided.

Content parts

Sizes, limits and the full list of forms have their own page. Images and files

The reply object

Finish reasons

A reply that is not streamed reports stop or tool_calls.

Usage

On the hosted open-weight models, prompt_tokens is your messages and tool definitions counted with the model's own tokenizer, plus the tokens of any images. The token counting endpoints return the same number before you send. Token counting

On the Shannon tiers, prompt_tokens counts everything the model read to write the reply, so it is larger than the text of your messages alone.

Streaming

With stream set to true the reply arrives as chat.completion.chunk events and ends with data: [DONE]. The last chunk before it carries finish_reason and usage; no stream_options are needed. The chunk shapes, keep-alive lines and errors inside a stream have their own page. Streaming

Errors

An error is a JSON object with an error member. Checks run in this order: API key, request body, model id, then balance. The table lists what this endpoint returns most often. The full list, with what to retry, has its own page. Error Handling

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