طلب واستخدام واجهة برمجة تطبيقات رسائل كلود

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

عملية الطلب

لاستخدام واجهة برمجة تطبيقات رسائل كلود، يجب أولاً الذهاب إلى وحدة التحكم في Ace Data Cloud للحصول على رمز API الخاص بك، للاحتفاظ به كنسخة احتياطية.

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

📘 الوثيقة الكاملة: واجهة برمجة تطبيقات رسائل كلود →

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

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

model: اختيار نموذج كلود المستخدم. الطراز الرائد الأحدث هو claude-fable-5-1 (سياق 1 مليون توكن، أقصى إخراج 128K توكن)؛ لا يزال الطراز الأصلي claude-fable-5 متوافقًا.
messages: مصفوفة الرسائل المدخلة، تحتوي كل رسالة على role (دور) و content (محتوى)، حيث يدعم role كل من user و assistant.
max_tokens: الحد الأقصى لعدد توكنات الإخراج، يستخدم لتحديد طول الرد في مرة واحدة.

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

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: إحصائيات استخدام التوكن. input_tokens هو الإدخال غير المخزن؛ cache_creation_input_tokens و cache_read_input_tokens هما على التوالي الكتابة والقراءة من التخزين المؤقت؛ output_tokens هو عدد توكنات الإخراج. السعر الرسمي لقراءة التخزين المؤقت لـ Fable 5.1 هو $0.25/مليون توكن، وسعر الكتابة للتخزين المؤقت لمدة 5 دقائق و1 ساعة هو$ 12.50 و$20/مليون توكن على التوالي؛ يتم حساب الأسعار الفعلية للمنصة وفقًا لخصومات الحزم. قد تحتوي الاستجابة غير المتدفقة أيضًا على cost المسجل من Ace Data Cloud.

كلمات التحفيز النظامية

تدعم واجهة برمجة تطبيقات رسائل كلود تعيين كلمات تحفيز النظام من خلال حقل 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، يمكن التحكم بدقة في دور كلود وسلوكه.

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

تدعم هذه الواجهة أيضًا الاستجابة المتدفقة، حيث يمكن تعيين معلمة 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": "مرحبًا، كلود"}
    ]
}

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

تعود الاستجابة المتدفقة بتنسيق أحداث خادم مرسلة (SSE)، حيث يتم تمييز كل سطر بـ event: و data:. تشمل أنواع الأحداث المتدفقة:

message_start: بداية الرسالة، تحتوي على المعلومات الأساسية للرسالة واسم النموذج.
content_block_start: بداية كتلة المحتوى.
content_block_delta: تحديثات زيادة كتلة المحتوى، تحتوي على مقاطع نصية جديدة تم إنشاؤها.
content_block_stop: نهاية كتلة المحتوى.
message_delta: تحديثات زيادة على مستوى الرسالة، تحتوي على stop_reason ومعلومات 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":"مرحبًا"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"! اسمي هو"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" كلود. كيف يمكنني مساعدتك اليوم؟"}}

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: "مرحبًا، كلود" }],
  }),
};

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": "مرحبًا، اسمي أليس."},
        {"role": "assistant", "content": "مرحبًا أليس! سعيد بلقائك. كيف يمكنني مساعدتك اليوم؟"},
        {"role": "user", "content": "ما هو اسمي؟"}
    ]
}

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

تكون النتيجة كما يلي:

{
  "id": "msg_01Y1wfQmd89g968TVbFu57Yc",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "اسمك هو أليس، كما أخبرتني للتو!"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 40,
    "output_tokens": 14
  }
}

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

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

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

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

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

{
  "type": "thinking",
  "thinking": "تسأل المشكلة عن قيمة مثلثية قياسية...",
  "signature": "opaque-signature"
}

display: "summarized" تعيد ملخص تفكير قابل للقراءة؛ ليس سلسلة التفكير الأصلية.
display: "omitted" تعيد thinking: ""، ولكن لا تزال تحتفظ بـ opaque signature لدعم المحادثات اللاحقة.
القيم الافتراضية لـ Fable 5.1، Fable 5، Opus 5، Sonnet 5، Opus 4.8 و Opus 4.7 هي omitted؛ بينما Opus 4.6، Sonnet 4.6 وما قبلها التي تدعم التفكير تستخدم افتراضيًا summarized.
يؤثر العرض فقط على محتوى الاستجابة وتأخير التدفق، ولا يغلق الاستدلال، ولا يقلل من تكلفة تفكير الرموز.
ما إذا كان التفكير مفعلًا افتراضيًا وما هي القيم الافتراضية للعرض هما مسألتان مستقلتان. Opus 5 و Sonnet 5 مفعلان افتراضيًا التفكير التكيفي؛ بينما Opus 4.8، 4.7 و 4.6 تحتاج إلى تفعيل صريح.
budget_tokens تستخدم فقط للنماذج القديمة التي لا تزال تدعم ميزانية تفكير ثابتة. يجب على النماذج الجديدة استخدام thinking.type=adaptive و output_config.effort؛ تفكير Fable 5.1 مفعل دائمًا ولا يمكن إيقافه صراحة.
عند المحادثات متعددة الجولات واستدعاء الأدوات، يجب إعادة كتلة التفكير الكاملة التي أعادها المساعد و signature كما هي؛ لا تعدل أو تولد signature بنفسك.
بعض التوجيهات المتوافقة جزئيًا لا يمكنها معالجة redacted_thinking أو إيقاف التفكير صراحة، وفي هذه الحالة ستعيد خطأ في المعلمات، ولن تتجاهل أو تغير دلالة الطلب بصمت.

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

نموذج بصري

Claude يدعم الإدخال متعدد الوسائط، ويمكنه معالجة النصوص والصور في نفس الوقت. في واجهة برمجة التطبيقات للرسائل، يمكن استخدام القدرات البصرية عن طريق تعيين 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": "ما الذي في هذه الصورة؟"
          }
        ]
      }
    ]
  }'

تنسيقات الصور المدعومة تشمل: 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": "التقرير ربع السنوي"
            },
            {"type": "text", "text": "قم بتلخيص هذا PDF."}
        ]
    }]
}

يتم كتابة مصدر URL كـ {"type":"url","url":"https://example.com/report.pdf"}. تدعم document أيضًا text/plain ومصادر content المكونة من كتل نصية/صورية؛ تشمل الحقول الاختيارية title، context و citations. مصدر file_id في واجهة برمجة التطبيقات للملفات هو ميزة بيتا مستقلة، ولا تدخل ضمن العقد الثابتة لهذه الواجهة.

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

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

payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral", "ttl": "5m"},
    "system": "أنت خبير في هذه المواد المرجعية.",
    "messages": [{"role": "user", "content": "قم بتلخيص النقاط الرئيسية."}]
}

عند الحاجة إلى التحكم الدقيق في الموقع، يمكن أيضًا كتابة نفس cache_control في كتل المحتوى النصية، الصور، الوثائق، استخدام الأدوات، أو تعريف الأدوات. يدعم ttl قيم 5m (افتراضي) و 1h؛ يرجى استخدام usage.cache_creation_input_tokens و usage.cache_read_input_tokens لتحديد كتابة ونجاح التخزين المؤقت. مثال على نتيجة العودة:

{
  "id": "msg_01NCrxpZmV17bhQJJRQEFEb9",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "تظهر هذه الصورة واجهة تكوين طلب API لما يبدو أنه خدمة إكمال دردشة AI. تتضمن الواجهة معلمات لاختيار النموذج، الرسائل، وضع البث، وإعدادات الحد الأقصى من الرموز."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1570,
    "output_tokens": 52
  }
}

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

تدعم واجهة برمجة التطبيقات للرسائل في 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-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "احصل على الطقس الحالي في موقع معين",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "المدينة والولاية، مثل سان فرانسيسكو، كاليفورنيا"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "كيف هو الطقس في سان فرانسيسكو؟"}
    ]
}

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

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

{
  "id": "msg_01Aq9w938a90dw8q",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "دعني أتحقق من الطقس في سان فرانسيسكو من أجلك."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lgs",
      "name": "get_weather",
      "input": {
        "location": "سان فرانسيسكو، كاليفورنيا"
      }
    }
  ],
  "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": "احصل على الطقس الحالي في موقع معين",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "المدينة والولاية، على سبيل المثال سان فرانسيسكو، كاليفورنيا"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "كيف يكون الطقس في سان فرانسيسكو؟"},
        {
            "role": "assistant",
            "content": [
                {"type": "text", "text": "دعني أتحقق من الطقس في سان فرانسيسكو لك."},
                {"type": "tool_use", "id": "toolu_01A09q90qw90lq917835lgs", "name": "get_weather", "input": {"location": "سان فرانسيسكو، كاليفورنيا"}}
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lgs",
                    "content": "مشمس، 72°F"
                }
            ]
        }
    ]
}

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

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

الفرق مع واجهة برمجة التطبيقات لإكمال الدردشة

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

الميزة	واجهة برمجة التطبيقات للرسائل (`/v1/messages`)	واجهة برمجة التطبيقات لإكمال الدردشة (`/v1/chat/completions`)
التنسيق	تنسيق أصلي من Anthropic	تنسيق متوافق مع OpenAI
نص النظام	حقل `system` مستقل	يتم تمريره عبر `role: "system"` في `messages`
هيكل الاستجابة	مصفوفة `content` (تدعم أنواع متعددة)	مصفوفة `choices` (تحتوي على `message`)
التنسيق المتدفق	أحداث SSE (أنواع متعددة من الأحداث)	خطوط SSE `data`
التفكير العميق	معلمة `thinking` الأصلية	يتم تنشيطها من خلال اسم نموذج خاص (مثل اللاحقة `-thinking`)
استدعاء الأدوات	`tools` الأصلية + `input_schema`	تنسيق `functions` المتوافق مع OpenAI
إحصاء التوكنات	`input_tokens` / `output_tokens`	`prompt_tokens` / `completion_tokens`

إذا كان نظامك متصلاً بالفعل بواجهة برمجة التطبيقات بتنسيق OpenAI، يمكنك استخدام واجهة برمجة التطبيقات لإكمال الدردشة للتبديل بسلاسة. إذا كنت بحاجة إلى استخدام جميع قدرات Claude الأصلية، يُنصح باستخدام واجهة برمجة التطبيقات للرسائل.

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

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

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

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

{
  "error": {
    "code": "api_error",
    "message": "فشل في الاسترجاع"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

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

الخاتمة

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

البداية

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

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

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

الصوت الذكي

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

CAPTCHA

الهوية

وكيل

متقدم

Coding

طلب واستخدام واجهة برمجة تطبيقات رسائل كلود

عملية الطلب

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

مثال cURL

مثال Python

كلمات التحفيز النظامية

مثال Python

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

مثال Python

مثال على JavaScript

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

مثال على Python

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

نموذج بصري

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

استخدام صورة URL

مثال cURL

الوثائق و PDF

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

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

مثال Python

الفرق مع واجهة برمجة التطبيقات لإكمال الدردشة

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

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

الخاتمة

​عملية الطلب

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

​مثال cURL

​مثال Python

​كلمات التحفيز النظامية

​مثال Python

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

​مثال Python

​مثال على JavaScript

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

​مثال على Python

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

​نموذج بصري

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

​استخدام صورة URL

​مثال cURL

​الوثائق و PDF

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

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

​مثال Python

​الفرق مع واجهة برمجة التطبيقات لإكمال الدردشة

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

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

​الخاتمة

عملية الطلب

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

مثال cURL

مثال Python

كلمات التحفيز النظامية

مثال Python

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

مثال Python

مثال على JavaScript

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

مثال على Python

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

نموذج بصري

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

استخدام صورة URL

مثال cURL

الوثائق و PDF

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

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

مثال Python

الفرق مع واجهة برمجة التطبيقات لإكمال الدردشة

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

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

الخاتمة