Chat Completions

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

Yêu cầu nhỏ nhất gồm một model id và một tin nhắn người dùng.

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

Phản hồi là một đối tượng 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 của yêu cầu

Header của phản hồi

Các trường yêu cầu

Chỉ messages là bắt buộc. Cột Áp dụng bởi nêu tên các model mà một trường làm thay đổi phản hồi. Các model open-weight hosted là mười hai id trong danh sách model; dòng Shannon 3 gồm shannon-3, shannon-3-pro, shannon-3.1 và shannon-3.1-pro. Model và giá

Các trường OpenAI khác, như n, user, stream_options, parallel_tool_calls, presence_penalty, frequency_penalty, logit_bias, logprobs, metadata, store và prompt_cache_key, được chấp nhận để mã client hiện có chạy không cần sửa. Chúng không làm thay đổi phản hồi: luôn chỉ có một choice, và stream luôn kết thúc bằng usage.

Một trường có kiểu JSON sai, ví dụ "max_tokens": "100", trả về 422. Yêu cầu không có messages cũng vậy.

Tool, đầu ra có cấu trúc, suy luận và tìm kiếm web đều có trang riêng: Gọi hàm, Đầu ra có cấu trúc, Mức độ suy luận, Tìm kiếm web tích hợp.

Một yêu cầu có tùy chọn

Yêu cầu này đặt một tin nhắn system, các trường lấy mẫu và mức độ suy luận. Nó dùng một model open-weight hosted, áp dụng tất cả các tùy chọn đó.

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

Phản hồi có cùng cấu trúc như trên. usage của nó thêm hai chi tiết trên các model open-weight hosted: số token prompt đọc từ cache và số token dùng cho suy luận.

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

Độ dài đầu ra

max_tokens làm hai việc. Thứ nhất, đó là số token được giữ lại từ số dư của bạn khi yêu cầu bắt đầu. Khi phản hồi hoàn tất, lượng đó được thay bằng số token yêu cầu đã dùng. Nếu max_tokens lớn hơn phần còn lại trong số dư của bạn, yêu cầu trả về 429 Quota exceeded ngay cả khi bản thân phản hồi vẫn vừa. Hãy gửi max_tokens thấp hơn để giữ lại ít hơn.

shannon-coder-1 được tính khác trên endpoint này: mỗi yêu cầu là một lượt gọi Shannon Coder trong gói của bạn, và không có token nào được giữ lại cho nó. Giới hạn và số dư

Thứ hai, nó giới hạn độ dài phản hồi trên các model sau:

Khi không có max_tokens hoặc max_completion_tokens, giá trị là 4,096. Trên shannon-coder-1 là 65,536.

Tin nhắn

Mỗi tin nhắn là một đối tượng có role và content. content là một chuỗi, hoặc một mảng các phần khi tin nhắn mang nhiều hơn văn bản.

Với id thuộc dòng Shannon 3, hãy đặt các chỉ dẫn bắt buộc phải giữ vào tin nhắn user.

Trên các bậc Shannon, yêu cầu không có văn bản người dùng và không có tools trả về 400 No user message provided.

Các phần nội dung

Kích thước, giới hạn và danh sách đầy đủ các dạng có trang riêng. Hình ảnh và tệp

Đối tượng phản hồi

Lý do kết thúc

Phản hồi không streaming báo stop hoặc tool_calls.

Usage

Trên các model open-weight hosted, prompt_tokens là các tin nhắn và định nghĩa tool của bạn được đếm bằng tokenizer riêng của model, cộng thêm token của các hình ảnh nếu có. Các endpoint đếm token trả về cùng con số này trước khi bạn gửi. Đếm token

Trên các bậc Shannon, prompt_tokens đếm mọi thứ model đã đọc để viết phản hồi, nên lớn hơn riêng văn bản các tin nhắn của bạn.

Streaming

Khi stream được đặt thành true, phản hồi đến dưới dạng các sự kiện chat.completion.chunk và kết thúc bằng data: [DONE]. Chunk cuối trước đó mang finish_reason và usage; không cần stream_options. Cấu trúc chunk, dòng keep-alive và lỗi bên trong stream có trang riêng. Truyền phát

Lỗi

Lỗi là một đối tượng JSON có thành phần error. Các bước kiểm tra chạy theo thứ tự này: API key, nội dung yêu cầu, model id, rồi số dư. Bảng liệt kê những gì endpoint này trả về thường xuyên nhất. Danh sách đầy đủ, kèm những lỗi nên thử lại, có trang riêng. Xử lý lỗi

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