رفتن به محتوا
فرمت Anthropic

فرمت Anthropic

POST /v1/messages درخواستی با فرمت Anthropic Messages می‌گیرد و با همان فرمت پاسخ می‌دهد، چه به‌صورت stream و چه بدون آن. از آن با SDK Anthropic و ابزارهای ساخته‌شده روی آن، مانند Claude Code، استفاده کنید: base URL را تنظیم کنید، کلید API Shannon خود را به کار ببرید و شناسه یک مدل Shannon را بنویسید.

POST https://api.shannon-ai.com/v1/messages

SDK Anthropic را به base URL مربوط به Shannon وصل کنید. SDK مقدار /v1/messages را اضافه می‌کند و کلید شما را در هدر x-api-key می‌فرستد.

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com",
)

message = client.messages.create(
    model="shannon-3",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

پاسخ یک پیام است که content آن فهرستی از بلوک‌هاست. بلوک‌ها را از روی type پیدا کنید: وقتی مدل استدلال کرده باشد، بلوک اول thinking است و متن بعد از آن می‌آید.

200 JSON
{
  "id": "msg_5f0c1e7a9b3d4c62a8e1f07d2b46c9a3",
  "type": "message",
  "role": "assistant",
  "model": "shannon-3",
  "content": [
    {
      "type": "thinking",
      "thinking": "The user wants a greeting in one sentence. Keep it short and friendly."
    },
    {
      "type": "text",
      "text": "Hello, it is good to meet you."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 1184,
    "output_tokens": 46
  }
}

هدرها

هدر مقدار توضیحات
x-api-key YOUR_API_KEY کلید API شما. به‌جای آن Authorization: Bearer YOUR_API_KEY هم پذیرفته می‌شود.
content-type application/json الزامی.
anthropic-version 2023-06-01 پذیرفته می‌شود، الزامی نیست. SDK Anthropic مقدار 2023-06-01 را می‌فرستد؛ پاسخ با هر مقداری همان فرمت را دارد.
anthropic-beta پذیرفته می‌شود، الزامی نیست.
x-request-id اختیاری. شناسه دلخواه شما برای درخواست. بدون تغییر در پاسخ برمی‌گردد؛ بدون آن، پاسخ شناسه‌ای با 12 نویسه هگزادسیمال دارد.

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

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

فیلد نوع پیش‌فرض توضیحات اعمال‌شده توسط
model string shannon-1.6-lite شناسه یک مدل Shannon از فهرست مدل‌ها. آن را با هر درخواست بفرستید. تطبیق به حروف بزرگ و کوچک حساس نیست. هر نام دیگری 400 unknown model برمی‌گرداند، بنابراین ابزاری که نام مدل‌های خودش را می‌فرستد باید روی شناسه Shannon تنظیم شود. همه مدل‌ها
messages array الزامی. گفتگو، قدیمی‌ترین پیام اول، با نقش‌های user و assistant. بخش «پیام‌ها و بلوک‌های محتوا» را در ادامه ببینید. همه مدل‌ها
system string | array دستورالعمل‌ها برای مدل: یک رشته یا آرایه‌ای از بلوک‌های متنی. بخش «System prompt» را در ادامه ببینید. مدل‌های open-weight میزبانی‌شده، shannon-1.6-*، shannon-2-*، shannon-coder-1
max_tokens integer 4096 حد بالای پاسخ، بر حسب توکن. در این endpoint اختیاری است؛ SDK Anthropic همیشه آن را می‌فرستد. مقداری خارج از بازه 1 تا 65,536 به همان بازه برگردانده می‌شود. همچنین مقداری است که تا پایان درخواست از موجودی شما کنار گذاشته می‌شود. مدل‌های open-weight میزبانی‌شده، shannon-1.6-lite، shannon-1.6-pro، shannon-coder-1
stream boolean false true پاسخ را به‌صورت server-sent events می‌فرستد. بخش «Streaming» را در ادامه ببینید. همه مدل‌ها
temperature number دمای نمونه‌برداری. روی مدل‌های open-weight میزبانی‌شده مقادیر بین 0 و 2 نگه داشته می‌شوند. مدل‌های open-weight میزبانی‌شده، shannon-1.6-lite، shannon-1.6-pro، shannon-coder-1
top_p number نمونه‌برداری هسته‌ای (nucleus). مدل‌های open-weight میزبانی‌شده
stop_sequences array حداکثر 4 رشته. پاسخ پیش از نخستین موردی که ظاهر شود پایان می‌یابد. stop_reason همچنان end_turn می‌ماند. مدل‌های open-weight میزبانی‌شده
tools array ابزارهایی که مدل می‌تواند فراخوانی کند، هرکدام به شکل {"name", "description", "input_schema"}. بخش «Tools» را در ادامه ببینید. همه مدل‌ها
tool_choice object {"type": "auto"} تصمیم را به مدل می‌سپارد، {"type": "any"} مدل را به فراخوانی یک ابزار وادار می‌کند، {"type": "tool", "name": "…"} او را به فراخوانی همان ابزار وادار می‌کند. مدل‌های open-weight میزبانی‌شده
thinking object اینکه مدل پیش از پاسخ چقدر استدلال کند. بخش «Thinking» را در ادامه ببینید. مدل‌های open-weight میزبانی‌شده
web_search boolean false افزونه‌ای از Shannon بر این فرمت: true به مدل اجازه می‌دهد پیش از پاسخ در وب جستجو کند. shannon-1.6-*، shannon-2-*، خانواده Shannon 3

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

metadata، top_k، service_tier و نشانگرهای cache_control روی بلوک‌ها پذیرفته می‌شوند تا کد کلاینت موجود بدون تغییر اجرا شود. آن‌ها پاسخ را تغییر نمی‌دهند؛ کش کردن پرامپت روی مدل‌های open-weight میزبانی‌شده خودکار است.

پاسخ JSON مطابق یک schema در Chat Completions با response_format و در Responses با text.format درخواست می‌شود. خروجی‌های ساختاریافته

درخواست با system prompt و thinking

این درخواست یک system prompt، یک بودجه thinking، یک temperature و یک stop sequence می‌فرستد. از یک مدل open-weight میزبانی‌شده استفاده می‌کند که همه آن‌ها را اعمال می‌کند.

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com",
)

message = client.messages.create(
    model="DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    max_tokens=4096,
    system="You are a physics teacher. Answer in two sentences.",
    thinking={"type": "enabled", "budget_tokens": 2048},
    temperature=0.3,
    stop_sequences=["\n\n"],
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
)

for block in message.content:
    if block.type == "thinking":
        print("reasoning:", block.thinking)
    elif block.type == "text":
        print("answer:", block.text)
print(message.usage)

در مدل‌های open-weight میزبانی‌شده، usage توکن‌های خوانده‌شده از کش پرامپت را جدا از دیگر توکن‌های ورودی گزارش می‌کند.

200 JSON
{
  "usage": {
    "input_tokens": 31,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "output_tokens": 62
  }
}

System prompt

system یک رشته است یا آرایه‌ای از بلوک‌های متنی به شکل [{"type": "text", "text": "…"}]. متن بلوک‌ها با یک خط جدید به هم متصل می‌شوند.

مدل‌های open-weight میزبانی‌شده، shannon-1.6-lite، shannon-1.6-pro، shannon-2-lite، shannon-2-pro و shannon-coder-1 آن را اعمال می‌کنند. با شناسه‌ای از خانواده Shannon 3، دستورالعمل‌هایی را که باید رعایت شوند در پیام کاربر بگذارید.

پیام‌ها و بلوک‌های محتوا

هر پیام یک role دارد، user یا assistant، و یک content. content یک رشته است یا آرایه‌ای از بلوک‌ها.

بلوک توضیحات در دسترس روی
{"type": "text", "text": "…"} متن. همه مدل‌ها
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "…"}}
{"type": "image", "source": {"type": "url", "url": "…"}}
یک تصویر در پیام user، به‌صورت base64 یا با URL. خانواده Shannon 3، shannon-1.6-lite، shannon-1.6-pro و مدل‌های open-weight میزبانی‌شده‌ای که ورودی تصویر را فهرست کرده‌اند
{"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": "…"}} یک سند (PDF، Word، PowerPoint یا Excel) در پیام user، به‌صورت base64 یا با URL. خانواده Shannon 3
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} در پیام assistant: فراخوانی ابزاری که مدل در پاسخ قبلی انجام داده است. همه مدل‌ها
{"type": "tool_result", "tool_use_id": "toolu_…", "content": "…"} در پیام user: نتیجه آن فراخوانی. content یک رشته است یا فهرستی از بلوک‌های متنی. همه مدل‌ها

می‌توانید content یک پاسخ قبلی را همان‌طور که هست پس بفرستید: بلوک‌های text و tool_use خوانده می‌شوند و بلوک‌های thinking نادیده گرفته می‌شوند.

در سطوح Shannon، تصاویر و اسناد از آخرین پیام user خوانده می‌شوند. اندازه‌ها و محدودیت‌ها صفحه خودشان را دارند. تصاویر و فایل‌ها

Thinking

مدل‌های open-weight میزبانی‌شده thinking را به یک میزان تلاش استدلال نگاشت می‌کنند. بدون این فیلد، میزان تلاش بالاست.

شکل budget_tokens اثر
{"type": "disabled"} بدون استدلال. پاسخ بلوک thinking ندارد.
{"type": "enabled", "budget_tokens": 2048} ≤ 2,048 تلاش کم.
{"type": "enabled", "budget_tokens": 8192} ≤ 8,192 تلاش متوسط.
{"type": "enabled", "budget_tokens": 16000} > 8,192 تلاش بالا.

مدلی که استدلال می‌کند، استدلال خود را به شکل بلوک {"type": "thinking", "thinking": "…"} پیش از متن برمی‌گرداند. سطوح Shannon که استدلال می‌کنند نیز آن را می‌فرستند.

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

Tools

ابزار تابعی است که کد شما اجرا می‌کند. هر کدام را با name، description و input_schema توصیف کنید. وقتی مدل ابزاری بخواهد، پاسخ شامل بلوک tool_use است و stop_reason برابر tool_use می‌شود.

تعریف یک ابزار در tools:

tools
[
  {
    "name": "get_weather",
    "description": "Current weather for a city.",
    "input_schema": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string"
        }
      },
      "required": [
        "city"
      ]
    }
  }
]

content پاسخی که آن را فراخوانی می‌کند:

200 content
[
  {
    "type": "text",
    "text": ""
  },
  {
    "type": "tool_use",
    "id": "toolu_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
    "name": "get_weather",
    "input": {
      "city": "Paris"
    }
  }
]

ابزار را اجرا کنید، سپس درخواست را دوباره بفرستید و فراخوانی و یک بلوک tool_result را به messages اضافه کنید:

messages
[
  {
    "role": "user",
    "content": "What is the weather in Paris?"
  },
  {
    "role": "assistant",
    "content": [
      {
        "type": "tool_use",
        "id": "toolu_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
        "name": "get_weather",
        "input": {
          "city": "Paris"
        }
      }
    ]
  },
  {
    "role": "user",
    "content": [
      {
        "type": "tool_result",
        "tool_use_id": "toolu_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
        "content": "{\"temperature_c\": 18, \"sky\": \"cloudy\"}"
      }
    ]
  }
]

tool_choice

شکل اثر اعمال‌شده توسط
{"type": "auto"} مدل تصمیم می‌گیرد که ابزاری فراخوانی کند یا نه. این پیش‌فرض است. همه مدل‌ها
{"type": "any"} مدل باید یکی از ابزارها را فراخوانی کند. مدل‌های open-weight میزبانی‌شده
{"type": "tool", "name": "…"} مدل باید ابزار نام‌برده را فراخوانی کند. مدل‌های open-weight میزبانی‌شده

فقط ابزارهایی که input_schema دارند خوانده می‌شوند. جستجوی وب در این endpoint ابزار نیست: فیلد web_search را تنظیم کنید.

حلقه ابزار به‌طور کامل در صفحه خودش توضیح داده شده است. فراخوانی توابع

پاسخ

فیلد نوع توضیحات ارسال‌شده توسط
id string msg_ و پس از آن 32 نویسه هگزادسیمال. همه مدل‌ها
type string همیشه message. همه مدل‌ها
role string همیشه assistant. همه مدل‌ها
model string شناسه استاندارد مدلی که پاسخ داد. همه مدل‌ها
content array بلوک‌های پاسخ، به این ترتیب: thinking اگر مدل استدلال کرده باشد، text، و سپس به ازای هر فراخوانی ابزار یک tool_use. همه مدل‌ها
stop_reason string دلیل پایان پاسخ. مقادیر را در ادامه ببینید. همه مدل‌ها
usage object input_tokens و output_tokens. همه مدل‌ها
sources array فقط در درخواستی با web_search: true که جستجویش چیزی پیدا کرده باشد: نتایجی که به مدل داده شده، هر کدام با index، title و url. [1] در پاسخ همان ورودی با index برابر 1 است. در یک stream همراه رویداد message_delta می‌آید. shannon-1.6-*، shannon-2-*، خانواده Shannon 3
usage.cache_read_input_tokens integer cache_read_input_tokens بخشی از پرامپت است که از کش خوانده شده؛ input_tokens بقیه است. cache_creation_input_tokens همیشه 0 است. مدل‌های open-weight میزبانی‌شده

بلوک‌های پاسخ

بلوک توضیحات
{"type": "thinking", "thinking": "…"} استدلال مدل. عضو signature وجود ندارد.
{"type": "text", "text": "…"} متن پاسخ. وقتی پاسخ یک فراخوانی ابزار باشد، می‌تواند خالی باشد.
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} یک فراخوانی ابزار. input یک شیء JSON است. نتیجه را با همان id پس بفرستید.

stop_reason

stop_reason توضیحات ارسال‌شده توسط
end_turn مدل پاسخ خود را تمام کرد، یا یکی از stop_sequences شما ظاهر شد. همه مدل‌ها
tool_use پاسخ شامل یک یا چند فراخوانی ابزار است. همه مدل‌ها
max_tokens پاسخ در حد خروجی بریده شد. خانواده Shannon 3، shannon-1.6-lite، shannon-1.6-pro، shannon-coder-1، در streamها

Streaming

برای server-sent events مقدار stream را true بگذارید. هر فریم یک خط event: با نام رویداد و یک خط data: با یک شیء JSON دارد که نام را در type تکرار می‌کند. ابزارهای کمکی stream در SDK Anthropic این رویدادها را برای شما می‌خوانند:

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com",
)

with client.messages.stream(
    model="shannon-3",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain server-sent events in three sentences."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    message = stream.get_final_message()

print()
print(message.stop_reason, message.usage)

رویدادها، به ترتیب رسیدنشان:

رویداد داده زمان
message_start message همیشه اول است. message شامل شناسه، نقش، مدل، یک content خالی و یک usage است که از صفر شروع می‌شود.
content_block_start index, content_block یک بلوک باز می‌شود. content_block یک بلوک text یا thinking خالی است، یا یک بلوک tool_use با id و name خودش.
content_block_delta index, delta {"type": "thinking_delta", "thinking"} یک تکه از استدلال، برای بلوک thinking.
content_block_delta index, delta {"type": "text_delta", "text"} یک تکه از پاسخ، برای بلوک text.
content_block_delta index, delta {"type": "input_json_delta", "partial_json"} آرگومان‌های یک فراخوانی ابزار، کامل در یک delta، برای بلوک tool_use.
content_block_stop index بلوک با این index کامل شد.
message_delta delta {stop_reason, stop_sequence}, usage پایان پاسخ: delta.stop_reason و usage درخواست.
message_stop همیشه آخر است.

بلوک‌ها با index به ترتیب باز شدنشان شماره‌گذاری می‌شوند و هر بلوک پیش از باز شدن بلوک بعدی کامل می‌شود. هر بلوک را از روی نوعش بخوانید، نه شماره‌اش: یک stream می‌تواند ابتدا یک بلوک text خالی باز کند، سپس بلوک thinking و پاسخ را در یک بلوک text بعدی تحویل دهد.

200 text/event-stream
event: message_start
data: {"type":"message_start","message":{"id":"msg_5f0c…","type":"message","role":"assistant","model":"shannon-3","content":[],"usage":{"input_tokens":0,"output_tokens":0}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"thinking","thinking":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"thinking_delta","thinking":"Three sentences: what it is, how it is framed, why it is used."}}

event: ping
data: {"type": "ping"}

event: content_block_stop
data: {"type":"content_block_stop","index":1}

event: content_block_start
data: {"type":"content_block_start","index":2,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":2,"delta":{"type":"text_delta","text":"Server-sent events let a server push text over one HTTP reply."}}

event: content_block_stop
data: {"type":"content_block_stop","index":2}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"input_tokens":1190,"output_tokens":84}}

event: message_stop
data: {"type":"message_stop"}

Keep-alive

ارسال‌شده توسط توضیحات
خانواده Shannon 3، shannon-1.6-lite، shannon-1.6-pro، shannon-coder-1 یک رویداد ping با داده {"type": "ping"}، هر 15 ثانیه.
مدل‌های open-weight میزبانی‌شده یک خط توضیح : keepalive، هر 15 ثانیه تا وقتی مدل مشغول کار است.

streamی که با خطا مواجه می‌شود

خطا پس از شروع stream یک رویداد error با همان بدنه پاسخ خطا است: {"type": "error", "error": {"type", "message"}}. رویدادهای پایانی، message_delta و message_stop، همچنان بعد از آن می‌آیند. پاسخ را ناموفق در نظر بگیرید و درخواست را دوباره بفرستید.

خطاها

خطاها از بدنه خطای Anthropic استفاده می‌کنند: type برابر error است و شیء error شامل type و message است. جدول، رایج‌ترین مواردی را که این endpoint برمی‌گرداند فهرست می‌کند. فهرست کامل، همراه با اینکه کدام را دوباره امتحان کنید، صفحه خودش را دارد. مدیریت خطا

400 JSON
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: no-such-model"
  }
}
وضعیت نوع پیام زمان
401 authentication_error Missing authentication
Invalid API key
هیچ کلید API ارسال نشده، یا کلید ناشناخته یا ابطال‌شده است.
400 invalid_request_error unknown model: <id> model شناسه مدل Shannon نیست.
400 invalid_request_error No user message provided سطوح Shannon: درخواست نه متن کاربر دارد و نه tools.
400 invalid_request_error <id> does not accept image input یک تصویر به مدل open-weight میزبانی‌شده‌ای فرستاده شد که ورودی تصویر ندارد.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … messages وجود ندارد، یا نوع JSON یک فیلد نادرست است.
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan max_tokens از باقی‌مانده موجودی شما بزرگ‌تر است.
429 rate_limit_error Too many requests. Retry in <n>s. محافظت در برابر هجوم درخواست (flood protection): بیش از 120 درخواست در یک دقیقه روی حساب شما.
429 rate_limit_error Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan shannon-coder-1: فراخوانی‌های Shannon Coder پلن شما برای بازه 4 ساعته فعلی مصرف شده‌اند.
500 server_error The model backend failed to answer. Please retry. مدل پاسخی تولید نکرد. درخواست را دوباره بفرستید.
502 api_error The model backend failed to answer. Please retry. مدل پاسخی تولید نکرد. درخواست را دوباره بفرستید.

شمارش توکن‌ها

POST /v1/messages/count_tokens همان بدنه درخواست پیام (model، system، messages، tools) را می‌گیرد و {"input_tokens": n} برمی‌گرداند: تعداد توکن‌های ورودی که برای این درخواست محاسبه می‌شد. این شمارش برای مدل‌های open-weight میزبانی‌شده انجام می‌شود، رایگان است و در محافظت در برابر هجوم درخواست (flood protection) به حساب نمی‌آید.

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com",
)

count = client.messages.count_tokens(
    model="DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    system="You are a physics teacher. Answer in two sentences.",
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
)

print(count.input_tokens)

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