طلب واستخدام Claude Messages API

Anthropic Claude هو نظام محادثة بالذكاء الاصطناعي قوي للغاية، فما عليك سوى إدخال نص توجيهي ليُنشئ ردودًا سلسة وطبيعية في غضون ثوانٍ قليلة. Claude Messages API هو تنسيق API أصلي رسمي من Anthropic، ويختلف عن التنسيق المتوافق مع OpenAI (Chat Completion)، إذ يستخدم بنية الطلبات والاستجابات الخاصة بـ Anthropic، مما يتيح الاستفادة بصورة أفضل من قدرات Claude الفريدة، مثل إدخال المحتوى متعدد الوسائط، واستدعاء الأدوات، والتفكير العميق (Extended Thinking)، وغيرها من الميزات المتقدمة. توضح هذه الوثيقة بشكل أساسي عملية استخدام عمليات Claude Messages API، وباستخدامها يمكننا استدعاء وظيفة المحادثة في Claude عبر واجهة أصلية متسقة مع Anthropic الرسمية.

عملية التقديم

لاستخدام Claude Messages API، انتقل أولًا إلى وحدة تحكم Ace Data Cloud للحصول على API Token الخاص بك، واحتفظ به للاستخدام لاحقًا.

إذا لم تكن قد سجلت الدخول أو أنشأت حسابًا بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك إلى التسجيل وتسجيل الدخول، وبعد الإكمال ستعود تلقائيًا إلى الصفحة الحالية. يمكن لـ API Token واحد استدعاء جميع خدمات المنصة، ولا حاجة للتقديم بشكل منفصل لكل خدمة. سيمنحك أول تقديم رصيدًا مجانيًا لتجربة الخدمة مجانًا؛ وعندما يكون الرصيد غير كافٍ، يمكنك شحن الرصيد العام من وحدة التحكم.

📘 الوثائق الكاملة: Claude Messages API →

الاستخدام الأساسي

مسار طلب Claude Messages API هو /v1/messages، وهو متوافق مع Anthropic API الرسمي. نحتاج إلى توفير ثلاثة معلمات إلزامية على الأقل:

model: اختر نموذج Claude المراد استخدامه. لا يتوفر claude-opus-5-5 إلا عبر Messages API، ويدعم سياقًا من مليون Token، وحدًا أقصى للإخراج يبلغ 128K Token، ويُفعّل دائمًا التفكير التكيفي. أحدث نموذج رائد هو claude-fable-5-1 (سياق مليون Token، وحد أقصى للإخراج يبلغ 128K Token)؛ ولا يزال claude-fable-5 السابق محفوظًا للتوافق. انضم claude-sonnet-5-5 إلى واجهة سلسلة Messages الأصلية، ويدعم إدخال الصور والتفكير التكيفي؛ وأسعار المراجع الرسمية للمدخلات والمخرجات وقراءة التخزين المؤقت هي 2 و10 و0.20 دولار لكل مليون Token على التوالي.
messages: مصفوفة الرسائل المُدخلة، تحتوي كل رسالة على role (الدور) وcontent (المحتوى)، حيث يدعم role كلاً من user وassistant.
max_tokens: الحد الأقصى لعدد token في الإخراج، ويُستخدم لتقييد طول الرد الواحد.

المعلمات الاختيارية الشائعة:

system: نص التوجيه النظامي، يُستخدم لتعيين سلوك النموذج ودوره.
temperature: عشوائية التوليد، بين 0 و1، وكلما زادت القيمة أصبح الرد أكثر تشتتًا.
stream: ما إذا كان سيتم استخدام استجابة متدفقة، ويمكن بتعيينه إلى true تحقيق تأثير الإرجاع حرفًا بحرف.
stop_sequences: تسلسلات إيقاف مخصصة، يتوقف النموذج عن التوليد عند مواجهة هذه النصوص.
top_p: معلمة أخذ العينات النوية، وتتحكم مع temperature في عشوائية التوليد.
top_k: أخذ العينات من بين أعلى K خيارات احتمالًا فقط.
tools: تعريف الأدوات، يُستخدم للسماح للنموذج باستدعاء وظائف خارجية.
tool_choice: التحكم في كيفية استخدام النموذج للأدوات المقدمة.
cache_control: إنشاء نقطة توقف للتخزين المؤقت تلقائيًا عند آخر كتلة محتوى قابلة للتخزين المؤقت في الطلب؛ ويمكن أيضًا كتابتها على كتلة محتوى محددة.

مثال cURL

curl -X POST 'https://api.acedata.cloud/v1/messages' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Hello, Claude"
      }
    ]
  }'

مثال Python

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

بعد الاستدعاء، تكون النتيجة المعادة كما يلي:

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hi! My name is Claude. How can I help you today?"
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 15
  }
}

شرح حقول النتيجة المعادة:

id: المعرّف الفريد لهذه الرسالة.
type: يكون دائمًا message.
role: يكون دائمًا assistant.
content: مصفوفة محتوى الرد، يحتوي كل عنصر على type (مثل text) والمحتوى المقابل.
model: اسم النموذج الذي يعالج الطلب.
stop_reason: سبب التوقف. تشمل القيم المستقرة end_turn وmax_tokens وstop_sequence وtool_use وpause_turn (يمكن إرجاع محتوى assistant الحالي كما هو للمتابعة) وrefusal وmodel_context_window_exceeded.
stop_sequence: إذا توقف بسبب تسلسل إيقاف مخصص، يعرض نص تسلسل الإيقاف المطابق.
stop_details: عندما يكون stop_reason هو refusal، قد يتضمن فئة الرفض ووصفًا.
usage: إحصائيات استخدام token. يمثل input_tokens المدخلات غير المخزنة مؤقتًا؛ ويمثل cache_creation_input_tokens وcache_read_input_tokens الكتابة إلى التخزين المؤقت والقراءة منه على التوالي؛ ويمثل output_tokens إجمالي عدد token في الإخراج. إذا أُعيد output_tokens_details.thinking_tokens، فهذه القيمة مجموعة فرعية من output_tokens، ولا تُضف مرة أخرى عند حساب الإجمالي أو التكلفة. قد تكون هذه التفاصيل null أو يتم حذفها عند عدم وجود عدّ موثوق.
usage.cache_creation: تفاصيل اختيارية لمدة TTL للكتابة إلى التخزين المؤقت، تشمل ephemeral_5m_input_tokens وephemeral_1h_input_tokens. عند وجود الكائن، يساوي مجموع القيمتين cache_creation_input_tokens؛ ويعني كون الحقل null أو محذوفًا عدم وجود تفصيل TTL متاح في الاستجابة الحالية، ولا يمكن تفسيره على أنه 0.
usage.cost: قد تتضمن الاستجابات غير المتدفقة كائن استهلاك الرصيد المسجل من Ace Data Cloud، حيث يمثل amount الاستهلاك الفعلي لهذه المرة، ويمثل currency وحدة القياس، ويمثل list_amount المبلغ قبل الخصم (إن وجد). سعر قراءة التخزين المؤقت الرسمي الأساسي لـ Fable 5.1 هو $0.25/مليون Token، وأسعار الكتابة إلى التخزين المؤقت الأساسية لمدة 5 دقائق وساعة واحدة هي $12.50 و$20/مليون Token على التوالي؛ ويُحتسب السعر الفعلي للمنصة وفق خصم الباقة.

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

يدعم Claude Messages API تعيين نص التوجيه النظامي عبر حقل system، ويُستخدم لتعريف سلوك النموذج ودوره وسياقه.

مثال Python

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "system": "你是一位专业的中文翻译助手，请将用户输入的英文翻译成中文。",
    "messages": [
        {"role": "user", "content": "The quick brown fox jumps over the lazy dog."}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

من خلال تعيين موجّه system، يمكن التحكم بدقة في دور Claude وسلوكه.

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

تدعم هذه الواجهة أيضًا الاستجابة المتدفقة؛ ما عليك سوى تعيين المعلمة stream إلى true للحصول على تأثير الإرجاع التدريجي، وهو مناسب جدًا لتنفيذ العرض حرفًا بحرف في صفحات الويب.

مثال Python

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "stream": True,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}

response = requests.post(url, json=payload, headers=headers, stream=True)
for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))

تُرجع الاستجابة المتدفقة بتنسيق Server-Sent Events ‏(SSE)، حيث يبدأ كل سطر بالبادئتين event: وdata:. وتشمل أنواع الأحداث المتدفقة:

message_start: بداية الرسالة، وتتضمن المعلومات الأساسية للرسالة واسم النموذج.
content_block_start: بداية كتلة المحتوى.
content_block_delta: تحديث تزايدي لكتلة المحتوى، ويتضمن جزء النص المُنشأ حديثًا.
content_block_stop: نهاية كتلة المحتوى.
message_delta: تحديث تزايدي على مستوى الرسالة، ويتضمن stop_reason ومعلومات usage النهائية. يجب قراءة القيمة الموثوقة لـ output_tokens_details.thinking_tokens من آخر message_delta.usage فقط، ولا تجمعها عبر الأحداث.
message_stop: نهاية الرسالة.

يكون تأثير الإخراج كما يلي:

event: message_start
data: {"type":"message_start","message":{"id":"msg_01XFDUDYJgAACzvnptvVoYEL","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-20250514","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":12,"output_tokens":0}}}

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

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

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"! My name is"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Claude. How can I help you today?"}}

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

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

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

يمكن ملاحظة أن حدث content_block_delta في الاستجابة المتدفقة يتضمن محتوى النص المُنشأ تدريجيًا، ويمكن الحصول على الرد الكامل عبر دمج جميع text_delta.

مثال JavaScript

const options = {
  method: "POST",
  headers: {
    accept: "application/json",
    authorization: "Bearer {token}",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-sonnet-4-20250514",
    max_tokens: 1024,
    stream: true,
    messages: [{ role: "user", content: "Hello, Claude" }],
  }),
};

const response = await fetch("https://api.acedata.cloud/v1/messages", options);
const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
}

محادثات متعددة الجولات

إذا كنت ترغب في ربط وظيفة المحادثات متعددة الجولات، فيجب ترتيب رسائل دورَي user وassistant بالتناوب في مصفوفة messages، وتمرير سجل المحادثة السابق بالكامل معها.

مثال Python

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, my name is Alice."},
        {"role": "assistant", "content": "Hello Alice! Nice to meet you. How can I help you today?"},
        {"role": "user", "content": "What is my name?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

تكون نتيجة الإرجاع كما يلي:

{
  "id": "msg_01Y1wfQmd89g968TVbFu57Yc",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Your name is Alice, as you just told me!"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 40,
    "output_tokens": 14
  }
}

من خلال تمرير سجل المحادثة الكامل في messages، يستطيع Claude تقديم إجابات دقيقة بالاستناد إلى السياق.

نموذج التفكير العميق

إن thinking وthinking summary لدى Claude مفهومان مختلفان: يمكن للنموذج إجراء استدلال داخلي، لكن واجهة API لن تُرجع سلسلة التفكير الأصلية. عند الحاجة إلى عرض عملية الاستدلال، فإن ما تُرجعه API هو ملخص مُعالَج. يوصى حاليًا باستخدام adaptive thinking، والتحكم في إجمالي جهد الاستدلال عبر output_config.effort:

import requests

url = "https://api.acedata.cloud/v1/messages"
headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}
payload = {
    "model": "claude-opus-5",
    "max_tokens": 16000,
    "thinking": {
        "type": "adaptive",
        "display": "summarized"
    },
    "output_config": {
        "effort": "high"
    },
    "messages": [
        {"role": "user", "content": "What is the sine of 30 degrees?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

تكون كتلة thinking في الاستجابة بالشكل التالي:

{
  "type": "thinking",
  "thinking": "The problem asks for a standard trigonometric value...",
  "signature": "opaque-signature"
}

display: "summarized" يعيد ملخصًا مقروءًا للتفكير؛ وهو ليس سلسلة التفكير الأصلية.
display: "omitted" يعيد thinking: ""، لكنه يحتفظ بـ opaque signature لدعم المحادثات اللاحقة.
display: "updates" هو وضع Anthropic التجريبي (beta)، ويتطلب إرفاق anthropic-beta: thinking-display-updates-2026-08-18. التعريف الرسمي هو إخفاء نص الاستدلال وعرض تحديثات تقدم قصيرة بين استدعاءات الأدوات. تقوم المنصة بتمرير هذا المعامل ورأس beta كما هو، ولن تجبره على التحويل إلى summarized؛ ويعتمد المحتوى الناتج الفعلي على دعم النموذج المحدد.
يتم تمرير thinking وoutput_config وeffort ومعاملات أخذ العينات والحقول الإضافية الجديدة كما هي. لا تحافظ المنصة على تعداد قيم أو قيود تركيبية مشفرة مسبقًا حسب النموذج، ولا تقوم تلقائيًا بتعديل أوضاع thinking؛ وما إذا كانت هذه المعاملات مقبولة يتم تحديده بواسطة النموذج المحدد، وسيتم إرجاع أخطاء المعاملات التي يعيدها النموذج إلى العميل.
القيمة الافتراضية لـ display في Fable 5.1 وFable 5 وOpus 5 وSonnet 5 وOpus 4.8 وOpus 4.7 هي omitted؛ أما Opus 4.6 وSonnet 4.6 والنماذج الأقدم التي تدعم thinking فتستخدم افتراضيًا summarized.
يؤثر Display فقط على المحتوى المعاد وزمن الاستجابة في البث، ولا يعطل الاستدلال ولا يقلل من تكلفة رموز thinking.
ما إذا كان thinking مفعّلًا افتراضيًا وقيمة display الافتراضية هما مسألتان مستقلتان. يقوم Opus 5 وSonnet 5 بتمكين adaptive thinking افتراضيًا؛ بالنسبة إلى Opus 5، فإن حذف thinking يعادل adaptive، وحذف output_config.effort يعادل high. أما Opus 4.8 و4.7 و4.6 فتحتاج إلى تفعيل صريح.
يشترك التفكير والنص النهائي معًا في ميزانية إخراج max_tokens. عندما تكون الميزانية صغيرة جدًا، قد يستهلك thinking معظم الحصة، مما يجعل النص الأساسي فارغًا أو يتم اقتطاعه؛ يرجى زيادة max_tokens، أو استخدام low / medium effort للتحكم في استثمار الاستدلال.
بالنسبة للنماذج التي تسمح بإيقاف thinking، يمكن تمرير thinking: {"type":"disabled"}. تعتمد الأوضاع الجديدة مثل between_tools وتركيبات effort على النموذج المحدد؛ ولا تقوم المنصة بالرفض المسبق بناءً على قواعد النماذج القديمة.
يمكن تمرير ميزانية التفكير الثابتة عبر budget_tokens؛ وعادةً ما تستخدم النماذج الجديدة thinking.type=adaptive وoutput_config.effort. يعتمد دعم الميزانية الثابتة أو إيقاف التفكير على القدرات الحالية للنموذج المحدد.
في المحادثات متعددة الجولات واستدعاءات الأدوات، يجب إعادة تمرير كتلة thinking الكاملة التي يعيدها assistant بالإضافة إلى signature كما هي؛ لا تقم بتعديل أو إنشاء signature بشكل ذاتي.
تمرير المعاملات كما هي لا يعني أن كل نموذج يدعم جميع الوظائف. لا تزال الاستدعاءات عبر البروتوكولات المختلفة تحتاج إلى تحويل، كما أن نطاق دعم redacted_thinking والأخطاء يتم تحديده بواسطة خدمة النموذج التي تعالج الطلب فعليًا.

في طلبات البث، ينتج summarized قيمة thinking_delta؛ بينما لا ينتج omitted قيمة thinking_delta، ويحتفظ فقط بدورة حياة كتلة thinking وsignature_delta.

النماذج المرئية

يدعم Claude الإدخالات متعددة الوسائط، ويمكنه معالجة النصوص والصور في الوقت نفسه. في Messages API، يمكن استخدام القدرات المرئية من خلال ضبط content على تنسيق مصفوفة وتمرير كتل محتوى الصور.

استخدام صور بترميز Base64

import base64
import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

# قراءة الصورة وترميزها
with open("image.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data
                    }
                },
                {
                    "type": "text",
                    "text": "ما الموجود في هذه الصورة؟"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

استخدام صور عبر URL

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://cdn.acedata.cloud/ueugot.png"
                    }
                },
                {
                    "type": "text",
                    "text": "ما الموجود في هذه الصورة؟"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

مثال cURL

curl -X POST 'https://api.acedata.cloud/v1/messages' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "url",
              "url": "https://cdn.acedata.cloud/ueugot.png"
            }
          },
          {
            "type": "text",
            "text": "What'\''s in this image?"
          }
        ]
      }
    ]
  }'

تشمل تنسيقات الصور المدعومة: image/jpeg، image/png، image/gif، image/webp.

المستندات وPDF

يستخدم PDF كتلة محتوى document، ويدعم مصدرين مستقرين هما Base64 وURL. يجب أن يستخدم مصدر Base64 نوع application/pdf:

import base64

with open("report.pdf", "rb") as f:
    pdf_data = base64.standard_b64encode(f.read()).decode("utf-8")

payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "messages": [{
        "role": "user",
        "content": [
            {
                "type": "document",
                "source": {
                    "type": "base64",
                    "media_type": "application/pdf",
                    "data": pdf_data
                },
                "title": "Quarterly report"
            },
            {"type": "text", "text": "Summarize this PDF."}
        ]
    }]
}

يُكتب مصدر URL بصيغة {"type":"url","url":"https://example.com/report.pdf"}. كما يدعم document مصادر text/plain وcontent المكوّنة من كتل text/image؛ وتشمل الحقول الاختيارية title وcontext وcitations. مصدر file_id الخاص بـ Files API هو وظيفة beta مستقلة، ولا يدخل ضمن العقد المستقر لهذه الواجهة.

التخزين المؤقت للتلميحات

يقوم cache_control في المستوى الأعلى تلقائيًا بوضع نقطة التخزين المؤقت عند آخر كتلة قابلة للتخزين المؤقت:

payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral", "ttl": "5m"},
    "system": "You are an expert on this reference material.",
    "messages": [{"role": "user", "content": "Summarize the key points."}]
}

عند الحاجة إلى التحكم الدقيق في الموضع، يمكن أيضًا كتابة cache_control نفسه على كتل محتوى text وimage وdocument وtool_use وtool_result أو على تعريفات الأدوات. يدعم ttl القيمتين 5m (الافتراضية) و1h؛ يرجى تحديد كتابة التخزين المؤقت وإصابته عبر usage.cache_creation_input_tokens وusage.cache_read_input_tokens. عندما توفّر الاستجابة usage.cache_creation، فإن ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens. إذا كانت cache_creation تساوي null أو تم حذفها، فهذا يعني أن هناك فقط إجمالي كتابة التخزين المؤقت، ولا يوجد تقسيم موثوق لـ TTL؛ في هذه الحالة لا تتعامل مع أي bucket على أنه 0 معروف، وتظل الفوترة والإجمالي معتمدين على حقل aggregate. مثال على النتيجة المُعادة:

{
  "id": "msg_01NCrxpZmV17bhQJJRQEFEb9",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image shows an API request configuration interface for what appears to be an AI chat completion service. The interface includes parameters for model selection, messages, stream mode, and max tokens settings."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1570,
    "output_tokens": 52
  }
}

استدعاء الأدوات (Tool Use)

تدعم Claude Messages API أصليًا ميزة استدعاء الأدوات، مما يسمح للنموذج باستدعاء أدوات/دوال تقومون بتعريفها مسبقًا عند الحاجة.

مثال Python

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "What's the weather like in San Francisco?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

عندما يقرر النموذج استدعاء أداة، سيحتوي content في النتيجة المُعادة على كتلة محتوى من نوع tool_use:

{
  "id": "msg_01Aq9w938a90dw8q",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Let me check the weather in San Francisco for you."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lgs",
      "name": "get_weather",
      "input": {
        "location": "San Francisco, CA"
      }
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 120,
    "output_tokens": 68
  }
}

لاحظ أن stop_reason هو tool_use، مما يشير إلى أن النموذج يحتاج إلى استدعاء الأداة. بعد استلام هذه النتيجة، تحتاجون إلى تنفيذ دالة الأداة وإعادة النتيجة إلى النموذج بصيغة tool_result:

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "What's the weather like in San Francisco?"},
        {
            "role": "assistant",
            "content": [
                {"type": "text", "text": "Let me check the weather in San Francisco for you."},
                {"type": "tool_use", "id": "toolu_01A09q90qw90lq917835lgs", "name": "get_weather", "input": {"location": "San Francisco, CA"}}
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lgs",
                    "content": "Sunny, 72°F"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

سيولّد النموذج الرد النهائي باللغة الطبيعية بناءً على النتيجة التي تُعيدها الأداة.

الفرق عن Chat Completion API

يوفّر Ace Data Cloud في الوقت نفسه تنسيقي Claude API، والفروقات الرئيسية بينهما كما يلي: يمثل usage.input_tokens في Messages API الإدخال غير المخزن مؤقتًا فقط، ويُعد cache_read_input_tokens وcache_creation_input_tokens فئات فوترة مستقلة؛ وتُحسب الثلاثة بشكل منفصل وفقًا للأسعار المقابلة.

الميزة	Messages API (`/v1/messages`)	Chat Completion API (`/v1/chat/completions`)
التنسيق	تنسيق Anthropic الأصلي	تنسيق متوافق مع OpenAI
مطالبة النظام	حقل `system` مستقل	يتم تمريرها عبر `role: "system"` في `messages`
بنية الاستجابة	مصفوفة `content` (تدعم أنواعًا متعددة)	مصفوفة `choices` (تتضمن `message`)
تنسيق البث	أحداث SSE (أنواع أحداث متعددة)	أسطر SSE `data`
التفكير العميق	`thinking` الأصلي و`output_config.effort`	الاستراتيجية الافتراضية للنموذج والمعلمات المتوافقة
استدعاء الأدوات	`tools` الأصلي + `input_schema`	تنسيق `tools` المتوافق مع OpenAI
إحصاءات Token	`output_tokens_details.thinking_tokens`	`completion_tokens_details.reasoning_tokens`

إذا كان نظامكم قد تكامل بالفعل مع API بتنسيق OpenAI، فيمكنكم استخدام Chat Completion API للتبديل بسلاسة. إذا كنتم تحتاجون إلى استخدام جميع القدرات الأصلية لـ Claude، فيوصى باستخدام Messages API.

معالجة الأخطاء

تستخدم استجابات الأخطاء للواجهة العامة envelope منصة Ace Data Cloud: error.code هو رمز خطأ ثابت، وerror.message هو الوصف، ويُستخدم trace_id لتتبع الطلب. تتضمن حالات HTTP الشائعة ما يلي:

400: معلمات الطلب أو محتوى البروتوكول غير صالح.
401: رمز التفويض غير صالح أو مفقود أو منتهي الصلاحية.
403: الوصول محظور أو الرصيد غير كافٍ أو الحصة مقيدة.
404: API أو النموذج غير موجود.
413: جسم الطلب كبير جدًا.
429: طلبات كثيرة جدًا.
500 / 503 / 504: خطأ في الخدمة، أو غير متاحة مؤقتًا، أو انتهت مهلة المعالجة.

مثال على استجابة خطأ

{
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

بنية الخطأ هذه هي عقد وقت التشغيل الخاص بـ Ace Data Cloud، وليست مساوية لـ envelope الخطأ الرسمي لـ Anthropic؛ يرجى التعامل معها وفقًا لحالة HTTP وerror.code.

الخلاصة

من خلال هذا المستند، تعرّفتَ بالفعل على كيفية استخدام Claude Messages API لاستدعاء قدرات المحادثة في Claude بتنسيق Anthropic الأصلي. يدعم Messages API وظائف غنية مثل المحادثات الأساسية، ومطالبات النظام، والاستجابات المتدفقة، والمحادثات متعددة الجولات، والتفكير العميق، والفهم البصري، وملفات PDF، والتخزين المؤقت للمطالبات، واستدعاء الأدوات. إذا كانت لديك أي أسئلة، فلا تتردد في الاتصال بفريق الدعم الفني لدينا.

البداية

دردشة الذكاء الاصطناعي

صورة الذكاء الاصطناعي

فيديو الذكاء الاصطناعي

الصوت الذكي

الويب والبيانات

CAPTCHA

الهوية

Coding

المزيد من الأدلة

طلب واستخدام Claude Messages API

عملية التقديم

الاستخدام الأساسي

مثال cURL

مثال Python

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

مثال Python

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

مثال Python

مثال JavaScript

محادثات متعددة الجولات

مثال Python

نموذج التفكير العميق

النماذج المرئية

استخدام صور بترميز Base64

استخدام صور عبر URL

مثال cURL

المستندات وPDF

التخزين المؤقت للتلميحات

استدعاء الأدوات (Tool Use)

مثال Python

الفرق عن Chat Completion API

معالجة الأخطاء

مثال على استجابة خطأ

الخلاصة

​عملية التقديم

​الاستخدام الأساسي

​مثال cURL

​مثال Python

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

​مثال Python

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

​مثال Python

​مثال JavaScript

​محادثات متعددة الجولات

​مثال Python

​نموذج التفكير العميق

​النماذج المرئية

​استخدام صور بترميز Base64

​استخدام صور عبر URL

​مثال cURL

​المستندات وPDF

​التخزين المؤقت للتلميحات

​استدعاء الأدوات (Tool Use)

​مثال Python

​الفرق عن Chat Completion API

​معالجة الأخطاء

​مثال على استجابة خطأ

​الخلاصة

عملية التقديم

الاستخدام الأساسي

مثال cURL

مثال Python

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

مثال Python

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

مثال Python

مثال JavaScript

محادثات متعددة الجولات

مثال Python

نموذج التفكير العميق

النماذج المرئية

استخدام صور بترميز Base64

استخدام صور عبر URL

مثال cURL

المستندات وPDF

التخزين المؤقت للتلميحات

استدعاء الأدوات (Tool Use)

مثال Python

الفرق عن Chat Completion API

معالجة الأخطاء

مثال على استجابة خطأ

الخلاصة