صيغة Anthropic للمحادثة (Messages)

الوثائق الرسمية

Anthropic Messages

📝 مقدّمة

يمكن استدعاء جميع نماذج Claude على البوابة بشكلٍ أصلي عبر صيغة Anthropic Messages API. هذه هي الصيغة الموصى بها عند استخدام حِزم Anthropic الرسمية أو أدوات مثل Claude Code.

📮 نقطة الوصول

POST /v1/messages

المصادقة

تُستخدم ترويسات بنمط Anthropic:

x-api-key: $WS_API_KEY
anthropic-version: 2023-06-01

كما تُقبل الترويسة Authorization: Bearer $WS_API_KEY أيضًا.

💡 أمثلة الطلبات

محادثة أساسية ✅

curl http://baseurl/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $WS_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'

مثال على الاستجابة:

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-6",
  "content": [
    {"type": "text", "text": "Hello! How can I help you today?"}
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 10,
    "output_tokens": 12
  }
}

موجّه النظام (System Prompt) ✅

curl http://baseurl/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $WS_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-haiku-4-5-20251001",
    "max_tokens": 1024,
    "system": "You are a professional translator. Translate everything to Arabic.",
    "messages": [
      {"role": "user", "content": "Good morning!"}
    ]
  }'

الاستجابة المتدفقة ✅

curl http://baseurl/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $WS_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "stream": true,
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

أحداث التدفق:

event: message_start
data: {"type":"message_start","message":{"id":"msg_...","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-6","usage":{"input_tokens":10}}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}

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

إدخال الصور ✅

curl http://baseurl/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $WS_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {"type": "url", "url": "https://example.com/photo.jpg"}
          },
          {"type": "text", "text": "Describe this image."}
        ]
      }
    ]
  }'

كما يُدعم base64: ‏"source": {"type": "base64", "media_type": "image/jpeg", "data": "..."}.

استخدام الأدوات (Tool Use) ✅

curl http://baseurl/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $WS_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 1024,
    "tools": [
      {
        "name": "get_weather",
        "description": "Get the current weather for a given location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "City name"}
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {"role": "user", "content": "What is the weather in Riyadh?"}
    ]
  }'

مثال على الاستجابة:

{
  "id": "msg_01Aq9w938a90dw8q",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-4-8",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "Riyadh"}
    }
  ],
  "stop_reason": "tool_use"
}

استخدام الحزمة الرسمية

import anthropic

client = anthropic.Anthropic(
    api_key="sk-...",                     # مفتاح WS API الخاص بك
    base_url="http://baseurl",
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude!"}],
)
print(message.content[0].text)

📋 معاملات جسم الطلب

المعامل	النوع	مطلوب	الوصف
model	string	نعم	معرّف نموذج Claude، راجع دليل النماذج
max_tokens	integer	نعم	الحد الأقصى لعدد الرموز المولّدة
messages	array	نعم	رسائل متناوبة بين user وassistant. المحتوى نص أو مصفوفة كتل محتوى (text وimage وtool_use وtool_result)
system	string / array	لا	موجّه النظام
stream	boolean	لا	بثّ الاستجابة عبر أحداث SSE
temperature	number	لا	‏0–1. الافتراضي 1
top_p	number	لا	أخذ عينات نووي
top_k	integer	لا	أخذ العينات من أفضل K خيارًا فقط
stop_sequences	array	لا	تسلسلات إيقاف مخصّصة
tools	array	لا	تعريفات الأدوات (name وdescription وinput_schema)
tool_choice	object	لا	‏{"type":"auto"} / {"type":"any"} / {"type":"tool","name":"..."}
thinking	object	لا	التفكير الموسّع، مثل {"type":"enabled","budget_tokens":10000}
metadata	object	لا	مثل {"user_id": "..."}

📥 حقول الاستجابة

الحقل	النوع	الوصف
id	string	المعرّف الفريد للرسالة
type	string	دائمًا message
role	string	دائمًا assistant
model	string	النموذج المستخدم
content	array	كتل المحتوى: text وtool_use وthinking
stop_reason	string	‏end_turn أو max_tokens أو stop_sequence أو tool_use
usage	object	‏input_tokens وoutput_tokens وعدّادات رموز قراءة/كتابة ذاكرة التخزين المؤقت