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

عملية الطلب

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

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

مسار طلب واجهة برمجة تطبيقات رسائل كلود هو /v1/messages، وهو متوافق مع واجهة برمجة تطبيقات Anthropic الرسمية. نحتاج على الأقل إلى تقديم ثلاثة معلمات إلزامية:
  • model: اختيار نموذج كلود المستخدم، مثل claude-opus-4-20250514، claude-sonnet-4-20250514، إلخ.
  • 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: التحكم في كيفية استخدام النموذج للأدوات المقدمة.

مثال 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": "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-sonnet-4-20250514",
    "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-sonnet-4-20250514",
  "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 (استدعاء أداة).
  • stop_sequence: إذا توقفت بسبب تسلسل التوقف المخصص، يظهر نص تسلسل التوقف المطابق.
  • usage: إحصائيات استخدام الرموز، تشمل input_tokens (عدد رموز الإدخال) و output_tokens (عدد رموز الإخراج).

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

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

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

يدعم كلود وظيفة التفكير الممتد (Extended Thinking)، مما يسمح للنموذج بإجراء استدلال داخلي قبل الرد، مما يعزز دقة معالجة المشكلات المعقدة. عند استخدام هذه الوظيفة، يجب تمرير معلمة thinking.

مثال على 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": 16000,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
    },
    "messages": [
        {"role": "user", "content": "ما هو جيب الزاوية 30 درجة؟ أظهر استدلالك."}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
النتيجة ستكون كما يلي:
{
  "id": "msg_018J4YaRoGHtbsTVb4Vvz7oH",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "thinking",
      "thinking": "يسأل المستخدم عن جيب الزاوية 30 درجة. هذه مسألة مثلثات أساسية.\n\nفي مثلث 30-60-90، تكون الأضلاع في نسبة 1:√3:2.\n\nبالنسبة لزاوية 30°:\n- الضلع المقابل هو 1\n- الوتر هو 2\n- لذا فإن sin(30°) = المقابل/الوتر = 1/2 = 0.5"
    },
    {
      "type": "text",
      "text": "جيب الزاوية 30 درجة هو **1/2** أو **0.5**.\n\nهذه واحدة من القيم المثلثية الأساسية. في مثلث 30-60-90، تكون الأضلاع في نسبة 1:√3:2، حيث يكون طول الضلع المقابل للزاوية 30° هو 1 وطول الوتر هو 2، مما يعطينا sin(30°) = 1/2."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 28,
    "output_tokens": 239
  }
}
يمكنك أن ترى أن مصفوفة content تحتوي على كتلتين من المحتوى:
  • type: "thinking": عملية التفكير الداخلية للنموذج، تعرض خطوات الاستدلال.
  • type: "text": نتيجة الإجابة النهائية.
ملاحظات:
  • عند استخدام thinking، يجب أن يكون max_tokens أكبر من budget_tokens، لأن budget_tokens هو ميزانية التوكنات المخصصة لعملية التفكير.
  • كلما كانت budget_tokens أكبر، زادت مساحة النموذج لإجراء استدلال أعمق، مما يناسب معالجة المشكلات المعقدة.

النموذج البصري

يدعم كلود الإدخال متعدد الوسائط، ويمكنه معالجة النصوص والصور في نفس الوقت. في واجهة برمجة التطبيقات للرسائل، يمكنك استخدام القدرة البصرية عن طريق تعيين 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 مثال على نتيجة العودة:
{
  "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، والفرق الرئيسي بينهما كما يلي:
الميزةواجهة رسائل API (/v1/messages)واجهة إكمال الدردشة API (/v1/chat/completions)
التنسيقتنسيق أصلي من Anthropicتنسيق متوافق مع OpenAI
نص النظامحقل system مستقليتم تمريره عبر messages في role: "system"
هيكل الاستجابةمصفوفة content (تدعم أنواع متعددة)مصفوفة choices (تحتوي على message)
التنسيق المتدفقأحداث SSE (أنواع متعددة من الأحداث)خطوط SSE data
التفكير العميقمعلمة thinking الأصليةيتم تنشيطها من خلال اسم نموذج خاص (مثل اللاحقة -thinking)
استدعاء الأدواتtools + input_schema الأصليةتنسيق functions المتوافق مع OpenAI
إحصاء الرموزinput_tokens / output_tokensprompt_tokens / completion_tokens
إذا كان نظامك متصلًا بالفعل بتنسيق واجهة برمجة تطبيقات OpenAI، يمكنك استخدام واجهة إكمال الدردشة API للتبديل بسلاسة. إذا كنت بحاجة إلى استخدام جميع قدرات Claude الأصلية، يُنصح باستخدام واجهة رسائل API.

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

عند استدعاء واجهة برمجة التطبيقات، إذا واجهت خطأ، ستعيد واجهة برمجة التطبيقات رمز الخطأ والمعلومات المقابلة. على سبيل المثال:
  • 400 token_mismatched:طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
  • 400 api_not_implemented:طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
  • 401 invalid_token:غير مصرح به، رمز تفويض غير صالح أو مفقود.
  • 429 too_many_requests:طلبات كثيرة جدًا، لقد تجاوزت الحد الأقصى لمعدل الطلبات.
  • 500 api_error:خطأ في الخادم الداخلي، حدث خطأ ما على الخادم.

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

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "فشل في جلب البيانات"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

الاستنتاج

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