Chat Completions

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

A menor requisição é um id de modelo e uma mensagem de usuário.

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

A resposta é um objeto 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
  }
}

Headers

Headers da requisição

Headers da resposta

Campos da requisição

Apenas messages é obrigatório. A coluna Aplicado por indica os modelos nos quais um campo muda a resposta. Os modelos open-weight hospedados são os doze ids da lista de modelos; a família Shannon 3 é shannon-3, shannon-3-pro, shannon-3.1 e shannon-3.1-pro. Modelos e preços

Outros campos da OpenAI, como n, user, stream_options, parallel_tool_calls, presence_penalty, frequency_penalty, logit_bias, logprobs, metadata, store e prompt_cache_key, são aceitos para que o código de cliente existente rode sem alterações. Eles não mudam a resposta: há sempre uma única choice, e um stream sempre termina com o uso.

Um campo com o tipo JSON errado, por exemplo "max_tokens": "100", retorna 422. Uma requisição sem messages também.

Ferramentas, saída estruturada, raciocínio e busca na web têm, cada um, uma página própria: Chamada de funções, Saídas estruturadas, Esforço de raciocínio, Busca web integrada.

Uma requisição com opções

Esta requisição define uma mensagem de sistema, os campos de amostragem e o esforço de raciocínio. Ela usa um modelo open-weight hospedado, que aplica todos eles.

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

A resposta tem o mesmo formato de cima. Seu usage acrescenta dois detalhes nos modelos open-weight hospedados: os tokens de prompt lidos do cache e os tokens gastos com raciocínio.

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

Tamanho da saída

max_tokens faz duas coisas. Primeiro, é o número de tokens reservados do seu saldo quando a requisição começa. Quando a resposta termina, essa quantia é substituída pelos tokens que a requisição usou. Se max_tokens for maior do que o que resta do seu saldo, a requisição retorna 429 Quota exceeded mesmo que a própria resposta coubesse. Envie um max_tokens menor para reservar menos.

shannon-coder-1 é contado de outra forma neste endpoint: cada requisição é uma das chamadas do Shannon Coder do seu plano, e nenhum token é reservado para ela. Limites e saldo

Segundo, ele limita o tamanho da resposta nestes modelos:

Sem max_tokens nem max_completion_tokens, o valor é 4,096. Em shannon-coder-1, é 65,536.

Mensagens

Cada mensagem é um objeto com um role e um content. content é uma string ou um array de partes quando a mensagem traz mais do que texto.

Com um id da família Shannon 3, coloque as instruções que precisam valer na mensagem user.

Nos níveis Shannon, uma requisição sem texto de usuário e sem tools retorna 400 No user message provided.

Partes de conteúdo

Tamanhos, limites e a lista completa de formas têm página própria. Imagens e arquivos

O objeto de resposta

Motivos de término

Uma resposta sem streaming informa stop ou tool_calls.

Uso

Nos modelos open-weight hospedados, prompt_tokens são suas mensagens e definições de ferramenta contadas com o tokenizador do próprio modelo, mais os tokens de eventuais imagens. Os endpoints de contagem de tokens retornam o mesmo número antes de você enviar. Contagem de tokens

Nos níveis Shannon, prompt_tokens conta tudo o que o modelo leu para escrever a resposta, então é maior do que apenas o texto das suas mensagens.

Streaming

Com stream definido como true, a resposta chega como eventos chat.completion.chunk e termina com data: [DONE]. O último chunk antes dele traz finish_reason e usage; não é preciso stream_options. Os formatos dos chunks, as linhas de keep-alive e os erros dentro de um stream têm página própria. Streaming

Erros

Um erro é um objeto JSON com um membro error. As verificações são feitas nesta ordem: chave de API, corpo da requisição, id do modelo e, por fim, saldo. A tabela lista o que este endpoint retorna com mais frequência. A lista completa, com o que tentar de novo, tem página própria. Tratamento de erros

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