Chat Completions

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

کوچک‌ترین درخواست یک شناسه مدل و یک پیام کاربر است.

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

پاسخ یک شیء 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
  }
}

هدرها

هدرهای درخواست

هدرهای پاسخ

فیلدهای درخواست

فقط messages الزامی است. ستون اعمال‌شده توسط مدل‌هایی را نام می‌برد که یک فیلد روی آن‌ها پاسخ را تغییر می‌دهد. مدل‌های open-weight میزبانی‌شده دوازده شناسه فهرست مدل‌ها هستند؛ خانواده Shannon 3 شامل shannon-3، shannon-3-pro، shannon-3.1 و shannon-3.1-pro است. مدل‌ها و قیمت‌ها

فیلدهای دیگر OpenAI، مانند n، user، stream_options، parallel_tool_calls، presence_penalty، frequency_penalty، logit_bias، logprobs، metadata، store و prompt_cache_key، پذیرفته می‌شوند تا کد کلاینت موجود بدون تغییر اجرا شود. آن‌ها پاسخ را تغییر نمی‌دهند: همیشه یک choice وجود دارد و stream همیشه با usage پایان می‌یابد.

فیلدی با نوع JSON نادرست، برای مثال "max_tokens": "100"، 422 برمی‌گرداند. درخواست بدون messages هم همین‌طور.

ابزارها، خروجی ساختاریافته، استدلال و جستجوی وب هرکدام صفحه خودشان را دارند: فراخوانی توابع, خروجی‌های ساختاریافته, میزان تلاش استدلال, جستجوی وب داخلی.

درخواست با گزینه‌ها

این درخواست یک پیام system، فیلدهای نمونه‌برداری و میزان تلاش استدلال را تنظیم می‌کند. از یک مدل open-weight میزبانی‌شده استفاده می‌کند که همه آن‌ها را اعمال می‌کند.

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

پاسخ همان شکل بالا را دارد. usage آن در مدل‌های open-weight میزبانی‌شده دو جزئیات اضافه می‌کند: توکن‌های پرامپت خوانده‌شده از کش و توکن‌های صرف‌شده برای استدلال.

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

طول خروجی

max_tokens دو کار می‌کند. اول، تعداد توکن‌هایی است که هنگام شروع درخواست از موجودی شما کنار گذاشته می‌شود. وقتی پاسخ کامل شود، این مقدار با توکن‌هایی که درخواست مصرف کرده جایگزین می‌شود. اگر max_tokens از باقی‌مانده موجودی شما بزرگ‌تر باشد، درخواست 429 Quota exceeded برمی‌گرداند، حتی اگر خود پاسخ جا می‌شد. برای کنار گذاشتن مقدار کمتر، max_tokens پایین‌تری بفرستید.

shannon-coder-1 در این endpoint متفاوت شمرده می‌شود: هر درخواست یکی از فراخوانی‌های Shannon Coder پلن شماست و هیچ توکنی برای آن کنار گذاشته نمی‌شود. محدودیت‌ها و موجودی

دوم، طول پاسخ را در این مدل‌ها محدود می‌کند:

بدون max_tokens یا max_completion_tokens مقدار 4,096 است. روی shannon-coder-1 برابر 65,536.

پیام‌ها

هر پیام یک شیء با role و content است. content یک رشته است یا، وقتی پیام چیزی بیش از متن دارد، آرایه‌ای از بخش‌ها.

با شناسه‌ای از خانواده Shannon 3، دستورالعمل‌هایی را که باید رعایت شوند در پیام user بگذارید.

در سطوح Shannon، درخواستی بدون متن کاربر و بدون tools 400 No user message provided برمی‌گرداند.

بخش‌های محتوا

اندازه‌ها، محدودیت‌ها و فهرست کامل شکل‌ها صفحه خودشان را دارند. تصاویر و فایل‌ها

شیء پاسخ

دلایل پایان

پاسخی که stream نمی‌شود stop یا tool_calls گزارش می‌کند.

مصرف

در مدل‌های open-weight میزبانی‌شده، prompt_tokens پیام‌ها و تعریف ابزارهای شماست که با توکنایزر خود مدل شمرده می‌شود، به‌علاوه توکن‌های تصاویر. endpointهای شمارش توکن پیش از ارسال همین عدد را برمی‌گردانند. شمارش توکن

در سطوح Shannon، prompt_tokens هر چیزی را که مدل برای نوشتن پاسخ خوانده می‌شمارد، پس از متن پیام‌های شما به‌تنهایی بزرگ‌تر است.

Streaming

وقتی stream برابر true باشد، پاسخ به‌صورت رویدادهای chat.completion.chunk می‌رسد و با data: [DONE] پایان می‌یابد. آخرین chunk پیش از آن finish_reason و usage را دارد؛ به stream_options نیازی نیست. شکل chunkها، خطوط keep-alive و خطاها داخل stream صفحه خودشان را دارند. استریم

خطاها

خطا یک شیء JSON با عضو error است. بررسی‌ها به این ترتیب انجام می‌شوند: کلید API، بدنه درخواست، شناسه مدل و سپس موجودی. جدول رایج‌ترین مواردی را که این endpoint برمی‌گرداند فهرست می‌کند. فهرست کامل، همراه با اینکه کدام را دوباره امتحان کنید، صفحه خودش را دارد. مدیریت خطا

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