تخطَّ إلى المحتوى
تنسيق Anthropic

تنسيق Anthropic

يقبل POST /v1/messages طلباً بصيغة Anthropic Messages ويجيب بالصيغة نفسها، مبثوثاً أو غير مبثوث. استخدمه مع Anthropic SDK ومع الأدوات المبنية عليه، مثل Claude Code: اضبط عنوان base URL، واستخدم مفتاح Shannon API الخاص بك، وسمِّ معرّف نموذج Shannon.

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

وجّه Anthropic SDK إلى عنوان Shannon الأساسي (base URL). تضيف الحزمة /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 مقبولة، وليست مطلوبة. ترسل حزمة Anthropic SDK القيمة 2023-06-01؛ وللرد الصيغة نفسها أياً كانت القيمة.
anthropic-beta مقبولة، وليست مطلوبة.
x-request-id اختيارية. معرّفك الخاص للطلب. يعود دون تغيير في الرد؛ ومن دونه يحمل الرد معرّفاً من 12 رمزاً سداسياً عشرياً.

حقول الطلب

الحقل messages وحده مطلوب. يسمّي العمود يطبّقه النماذج التي يغيّر فيها الحقل الرد. النماذج المفتوحة الأوزان المستضافة هي المعرّفات الاثنا عشر في قائمة النماذج؛ وعائلة 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 تعليمات للنموذج: سلسلة نصية أو مصفوفة من كتل النص. انظر توجيهات النظام أدناه. النماذج المفتوحة الأوزان المستضافة، shannon-1.6-*، shannon-2-*، shannon-coder-1
max_tokens integer 4096 الحد الأعلى للرد، بالـ tokens. اختياري في نقطة النهاية هذه؛ وترسله حزمة Anthropic SDK دائماً. تُنقل القيمة الخارجة عن النطاق من 1 إلى 65,536 إلى ذلك النطاق. وهو أيضاً المقدار المحجوز من رصيدك أثناء تشغيل الطلب. النماذج المفتوحة الأوزان المستضافة، shannon-1.6-lite، shannon-1.6-pro، shannon-coder-1
stream boolean false تؤدي true إلى إرسال الرد كأحداث يرسلها الخادم (server-sent events). انظر البث أدناه. جميع النماذج
temperature number درجة حرارة أخذ العينات. في النماذج المفتوحة الأوزان المستضافة تُحصر القيم بين 0 و2. النماذج المفتوحة الأوزان المستضافة، shannon-1.6-lite، shannon-1.6-pro، shannon-coder-1
top_p number أخذ العينات النووي (nucleus sampling). النماذج المفتوحة الأوزان المستضافة
stop_sequences array حتى 4 سلاسل نصية. تنتهي الإجابة قبل أول واحدة منها تظهر. تبقى stop_reason على end_turn. النماذج المفتوحة الأوزان المستضافة
tools array الأدوات التي يجوز للنموذج استدعاؤها، كل واحدة بصيغة {"name", "description", "input_schema"}. انظر الأدوات أدناه. جميع النماذج
tool_choice object {"type": "auto"} يترك القرار للنموذج، و{"type": "any"} يجعله يستدعي أداة، و{"type": "tool", "name": "…"} يجعله يستدعي تلك الأداة. النماذج المفتوحة الأوزان المستضافة
thinking object مقدار استدلال النموذج قبل أن يجيب. انظر التفكير أدناه. النماذج المفتوحة الأوزان المستضافة
web_search boolean false إضافة من Shannon إلى الصيغة: تتيح true للنموذج البحث في الويب قبل أن يجيب. shannon-1.6-*، shannon-2-*، عائلة Shannon 3

من دون max_tokens تكون القيمة 4,096، وتكون 65,536 في shannon-coder-1.

تُقبل metadata وtop_k وservice_tier وعلامات cache_control على الكتل حتى تعمل شيفرة العميل الحالية دون تغيير. لا تغيّر هذه الحقول الرد؛ فالتخزين المؤقت للمطالبات على النماذج المفتوحة الأوزان المستضافة تلقائي.

يُطلب جواب JSON وفق مخطط عبر response_format في Chat Completions وعبر text.format في Responses. مخرجات منظمة

طلب مع توجيهات النظام والتفكير

يرسل هذا الطلب توجيهات نظام وميزانية تفكير ودرجة حرارة وتسلسل إيقاف. ويستخدم نموذجاً مفتوح الأوزان مستضافاً، يطبّق كل ذلك.

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)

في النماذج المفتوحة الأوزان المستضافة يعرض usage الـ tokens المقروءة من ذاكرة التخزين المؤقت للمطالبات بمعزل عن بقية tokens المدخلة.

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

توجيهات النظام

system سلسلة نصية، أو مصفوفة من كتل النص بالشكل [{"type": "text", "text": "…"}]. تُضم نصوص الكتل بفاصل سطر.

تطبّقه النماذج المفتوحة الأوزان المستضافة، و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، والنماذج المفتوحة الأوزان المستضافة التي تدعم إدخال الصور
{"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 بجهد استدلال. من دون الحقل يكون الجهد عالياً.

الشكل 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 التي تستدل كذلك.

تُشرح مستويات الجهد في صفحتها الخاصة. جهد الاستدلال

الأدوات

الأداة دالة تشغّلها شيفرتك. صِف كل واحدة بـ 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"} يجب أن يستدعي النموذج إحدى الأدوات. النماذج المفتوحة الأوزان المستضافة
{"type": "tool", "name": "…"} يجب أن يستدعي النموذج الأداة المسماة. النماذج المفتوحة الأوزان المستضافة

تُقرأ فقط الأدوات التي لها input_schema. البحث في الويب ليس أداة في نقطة النهاية هذه: اضبط الحقل 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. وفي البث يأتي مع الحدث 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. النماذج المفتوحة الأوزان المستضافة

كتل الرد

الكتلة الوصف
{"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 على true للحصول على أحداث يرسلها الخادم (server-sent events). لكل إطار سطر event: باسم الحدث وسطر data: بكائن JSON يكرر الاسم في type. تقرأ مساعدات البث في Anthropic SDK هذه الأحداث نيابة عنك:

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"} وسائط استدعاء الأداة، كاملة في دلتا واحدة، لكتلة tool_use.
content_block_stop index اكتملت الكتلة ذات index هذا.
message_delta delta {stop_reason, stop_sequence}, usage نهاية الرد: delta.stop_reason، وusage الخاص بالطلب.
message_stop دائماً أخيراً.

تُرقَّم الكتل بحسب index وفق ترتيب فتحها، وتكتمل كتلة واحدة قبل أن تُفتح التالية. اقرأ كل كتلة بحسب نوعها لا برقمها: قد يفتح البث كتلة 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"}

إبقاء الاتصال حياً

يرسله الوصف
عائلة Shannon 3، shannon-1.6-lite، shannon-1.6-pro، shannon-coder-1 حدث ping ببيانات {"type": "ping"}، كل 15 ثانية.
النماذج المفتوحة الأوزان المستضافة سطر تعليق : keepalive، كل 15 ثانية أثناء عمل النموذج.

بث يفشل

الفشل بعد بدء البث يصل كحدث error بنفس نص رد الخطأ: {"type": "error", "error": {"type", "message"}}. وتتبعه أحداث الإغلاق message_delta وmessage_stop. اعتبر الرد فاشلاً وأعد إرسال الطلب.

الأخطاء

تستخدم الأخطاء نص الخطأ الخاص بـ Anthropic: قيمة type هي error، ويحتوي الكائن error على type وmessage. يسرد الجدول ما تعيده نقطة النهاية هذه في الغالب. أما القائمة الكاملة، مع ما يجب إعادة محاولته، فلها صفحتها الخاصة. معالجة الأخطاء

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 أُرسلت صورة إلى نموذج مفتوح الأوزان مستضاف لا يدعم إدخال الصور.
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. الحماية من الإغراق: أكثر من 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. لم ينتج النموذج رداً. أعد إرسال الطلب.

حساب الـ tokens

يقبل POST /v1/messages/count_tokens نفس نص طلب الرسالة (model وsystem وmessages وtools) ويعيد {"input_tokens": n}: عدد tokens المدخلة التي سيُحاسَب عليها الطلب. يعمل مع النماذج المفتوحة الأوزان المستضافة، وهو مجاني ولا تحتسبه الحماية من الإغراق.

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)

للعد صفحته الخاصة، مع نقطة نهاية النص العادي والحدود. عدّ الـ tokens