عملية الطلب
لاستخدام واجهة برمجة تطبيقات رسائل كلود، يمكنك أولاً زيارة صفحة واجهة برمجة تطبيقات رسائل كلود والنقر على زر “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
مثال Python
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
system، يمكن التحكم بدقة في دور وسلوك كلود.
الاستجابة المتدفقة
تدعم هذه الواجهة أيضًا الاستجابة المتدفقة، حيث يمكن الحصول على تأثير العودة خطوة بخطوة عن طريق تعيين معلمةstream إلى true، مما يجعلها مثالية لتنفيذ عرض كلمة بكلمة على الويب.
مثال Python
event: و data:. تشمل أنواع الأحداث المتدفقة:
message_start: بداية الرسالة، تحتوي على المعلومات الأساسية للرسالة واسم النموذج.content_block_start: بداية كتلة المحتوى.content_block_delta: تحديث كتلة المحتوى، يحتوي على مقاطع نصية جديدة تم إنشاؤها.content_block_stop: نهاية كتلة المحتوى.message_delta: تحديث على مستوى الرسالة، يحتوي علىstop_reasonومعلوماتusageالنهائية.message_stop: نهاية الرسالة.
content_block_delta التي تتضمن نصوصًا تم إنشاؤها تدريجيًا، من خلال تجميع جميع text_delta يمكنك الحصول على الرد الكامل.
مثال على JavaScript
المحادثات متعددة الأدوار
إذا كنت ترغب في دمج وظيفة المحادثات متعددة الأدوار، تحتاج إلى ترتيب الرسائل بين أدوارuser و assistant بالتناوب في مصفوفة messages، مع تضمين تاريخ المحادثة السابقة.
مثال على Python
messages، يمكن لكلود دمج السياق لتقديم إجابات دقيقة.
نموذج التفكير العميق
يدعم كلود وظيفة التفكير الممتد (Extended Thinking)، مما يسمح للنموذج بإجراء استدلال داخلي قبل الرد، مما يعزز دقة معالجة المشكلات المعقدة. عند استخدام هذه الوظيفة، يجب تمرير معلمةthinking.
مثال على Python
content تحتوي على كتلتين من المحتوى:
type: "thinking": عملية التفكير الداخلية للنموذج، تعرض خطوات الاستدلال.type: "text": نتيجة الإجابة النهائية.
- عند استخدام
thinking، يجب أن يكونmax_tokensأكبر منbudget_tokens، لأنbudget_tokensهو ميزانية التوكنات المخصصة لعملية التفكير. - كلما كانت
budget_tokensأكبر، زادت مساحة النموذج لإجراء استدلال أعمق، مما يناسب معالجة المشكلات المعقدة.
النموذج البصري
يدعم كلود الإدخال متعدد الوسائط، ويمكنه معالجة النصوص والصور في نفس الوقت. في واجهة برمجة التطبيقات للرسائل، يمكنك استخدام القدرة البصرية عن طريق تعيينcontent إلى تنسيق مصفوفة، وتمرير كتل محتوى الصورة.
استخدام ترميز Base64 للصورة
استخدام صورة من URL
cURL مثال
image/jpeg، image/png، image/gif، image/webp。
مثال على نتيجة العودة:
استخدام الأدوات (Tool Use)
تدعم واجهة برمجة تطبيقات رسائل Claude بشكل أصلي وظيفة استدعاء الأدوات، مما يسمح للنموذج باستدعاء الأدوات/الدوال التي قمت بتعريفها مسبقًا عند الحاجة.مثال Python
tool_use:
stop_reason هو tool_use، مما يدل على أن النموذج يحتاج إلى استدعاء أداة. بعد تلقي هذه النتيجة، تحتاج إلى تنفيذ دالة الأداة وإعادة النتيجة إلى النموذج بشكل tool_result:
الفرق بين واجهة برمجة تطبيقات إكمال الدردشة
تقدم 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_tokens | prompt_tokens / completion_tokens |
معالجة الأخطاء
عند استدعاء واجهة برمجة التطبيقات، إذا واجهت خطأ، ستعيد واجهة برمجة التطبيقات رمز الخطأ والمعلومات المقابلة. على سبيل المثال:400 token_mismatched:طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.400 api_not_implemented:طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.401 invalid_token:غير مصرح به، رمز تفويض غير صالح أو مفقود.429 too_many_requests:طلبات كثيرة جدًا، لقد تجاوزت الحد الأقصى لمعدل الطلبات.500 api_error:خطأ في الخادم الداخلي، حدث خطأ ما على الخادم.

