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

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

لاستخدام Claude Chat Completion API، انتقل أولًا إلى لوحة تحكم Ace Data Cloud للحصول على API Token الخاص بك، واحتفظ به للاستخدام لاحقًا. إذا لم تكن قد سجلت الدخول أو أنشأت حسابًا بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك إلى التسجيل وتسجيل الدخول، وبعد الإكمال ستعود تلقائيًا إلى الصفحة الحالية. يمكن لـ API Token واحد استدعاء جميع خدمات المنصة، ولا حاجة للتقديم بشكل منفصل لكل خدمة. ستحصل عند أول تقديم على رصيد مجاني لتجربة الخدمة مجانًا؛ وعندما لا يكون الرصيد كافيًا، يمكنك شحن الرصيد العام من لوحة التحكم.
📘 الوثائق الكاملة: Claude Chat Completion API →

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

بعد ذلك، يمكنك تعبئة المحتوى المقابل في الواجهة، كما هو موضح في الشكل:

عند استخدام هذه الواجهة لأول مرة، نحتاج إلى تعبئة ثلاثة عناصر على الأقل. أحدها هو authorization، ويمكنك اختياره مباشرة من القائمة المنسدلة. المعلمة الأخرى هي model، ويوصى باستخدام الإصدار الرائد الأحدث claude-fable-5-1؛ ولا يزال بالإمكان استدعاء الإصدار السابق claude-fable-5. المعلمة الأخيرة هي messages، وهي مصفوفة من عبارات الأسئلة، ويحتوي كل عنصر على role وcontent؛ يدعم role القيم user وassistant وsystem، بينما يمثل content المحتوى المحدد. يدعم Claude Fable 5.1 سياقًا يصل إلى مليون Token ومخرجات تصل إلى 128K Token كحد أقصى. في الوقت نفسه، يمكنك ملاحظة وجود إنشاء لكود الاستدعاء المقابل على الجانب الأيمن، ويمكنك نسخ الكود وتشغيله مباشرة، أو النقر مباشرة على زر «Try» للاختبار. المعلمات الاختيارية الشائعة:
  • max_tokens: يحدد الحد الأقصى لعدد token في الرد الواحد.
  • temperature: عشوائية التوليد، بين 0 و2، وكلما زادت القيمة زاد التشتت.
  • n: عدد الردود المرشحة التي يتم إنشاؤها في المرة الواحدة.
  • response_format: إعداد تنسيق الإرجاع.

بعد الاستدعاء، نجد أن النتيجة المعادة كما يلي:
تحتوي النتيجة المعادة على عدة حقول، يتم تقديمها كما يلي:
  • id، معرّف مهمة المحادثة التي تم إنشاؤها، ويُستخدم لتمييز مهمة المحادثة هذه بشكل فريد.
  • model ، نموذج Claude الرسمي المحدد.
  • choices، معلومات الرد التي يقدمها Claude على عبارة السؤال.
  • usage : معلومات إحصائية عن token لهذه الجولة من الأسئلة والأجوبة.
في تنسيق Chat Completions، يمثل usage.prompt_tokens إجمالي المدخلات؛ ويسجل prompt_tokens_details.cached_tokens وprompt_tokens_details.cache_write_tokens تفاصيل قراءة وكتابة ذاكرة التخزين المؤقت على التوالي. يمثل completion_tokens_details.reasoning_tokens مجموعة فرعية من completion_tokens، ولا تقم بإضافته مرة أخرى عند حساب الإجمالي أو التكلفة. قد تعيد الاستجابات غير المتدفقة أيضًا كائن usage.cost، حيث يمثل amount استهلاك الرصيد الفعلي، ويمثل currency وحدة القياس، ويمثل list_amount المبلغ قبل الخصم (إن وجد). اسم الحقل المتوافق مع Chat هو reasoning_tokens؛ بينما تستخدم Messages API الأصلية output_tokens_details.thinking_tokens. يختلف wire schema للبروتوكولين، ويجب ألا يخلط العميل بين أسماء الحقول. من بينها، choices تحتوي على معلومات رد Claude، أما choices الموجودة بداخلها فهي المعلومات المحددة لرد Claude، كما يمكن ملاحظته في الشكل.

يمكنك رؤية أن حقل content داخل choices يحتوي على المحتوى المحدد لرد Claude.

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

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

بعد تغيير stream إلى true، ستعيد API بيانات JSON المقابلة سطرًا بسطر، وعلى مستوى الكود نحتاج إلى إجراء التعديلات المناسبة للحصول على النتائج سطرًا بسطر. كود استدعاء نموذجي بلغة Python:
يكون تأثير الإخراج كما يلي:
يمكن ملاحظة أن الاستجابة تحتوي على العديد من data، وأن choices داخل data هي أحدث محتوى للإجابة، وهو متوافق مع المحتوى المذكور أعلاه. تمثل choices محتوى الإجابة المضاف حديثًا، ويمكنك ربطه بنظامك وفقًا للنتيجة. وفي الوقت نفسه، يتم تحديد انتهاء الاستجابة المتدفقة وفقًا لمحتوى data، فإذا كان المحتوى هو [DONE]، فهذا يعني أن إجابة الاستجابة المتدفقة قد انتهت بالكامل. تحتوي نتيجة data المُعادة على عدة حقول، كما يلي:
  • id، معرّف مهمة المحادثة المُولَّدة هذه، ويُستخدم لتمييز مهمة المحادثة هذه بشكل فريد.
  • model ، نموذج Claude الرسمي المحدد.
  • choices، معلومات الإجابة التي يقدمها Claude على كلمات السؤال.
يدعم JavaScript أيضًا ذلك، مثلًا كود الاستدعاء المتدفق لـ Node.js كما يلي:
كود مثال Java:
يمكن إعادة كتابة اللغات الأخرى بشكل منفصل، والمبدأ واحد.

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

إذا كنت ترغب في ربط وظيفة المحادثة متعددة الجولات، فأنت بحاجة إلى رفع عدة كلمات سؤال إلى حقل messages، ويظهر المثال المحدد لعدة كلمات سؤال كما في الصورة التالية:

كود استدعاء مثال Python:
من خلال رفع عدة كلمات سؤال، يمكن بسهولة تحقيق محادثة متعددة الجولات، ويمكن الحصول على الإجابة التالية:
يمكن ملاحظة أن المعلومات التي تحتويها choices متوافقة مع محتوى الاستخدام الأساسي، وهي تتضمن المحتوى المحدد لرد Claude على محادثات متعددة، وبهذه الطريقة يمكن الإجابة عن الأسئلة المقابلة استنادًا إلى محتويات محادثات متعددة.

التفكير العميق

قد تقوم نماذج Claude من الجيل الجديد بالاستدلال وفقًا لسياسة النموذج الافتراضية، دون الحاجة إلى تشغيله عبر لاحقة نموذج -thinking. تستخدم الاستجابات المتوافقة مع Chat حقل usage المتوافق مع OpenAI وهو completion_tokens_details.reasoning_tokens. إن reasoning_tokens مشمولة بالفعل ضمن completion_tokens، لذا لا تقم بجمعها بشكل متكرر. يشترك الاستدلال والنص المرئي في الحد الأقصى لرموز الإخراج، لذلك عند انخفاض max_tokens قد يظهر النص فارغًا أو يتم اقتطاعه؛ عند مواجهة هذه الحالة، يرجى زيادة ميزانية الإخراج، أو اختيار مستوى استدلال أقل عندما يدعم النموذج المستخدم ذلك. إذا كنت بحاجة إلى thinking الأصلي، وoutput_config.effort، وكتل محتوى thinking، وإرجاع التوقيع، فيرجى استخدام /v1/messages. حقل usage المقابل لـ Messages هو output_tokens_details.thinking_tokens، ولا تخلطه مع completion_tokens_details.reasoning_tokens المتوافق مع Chat.

نماذج الرؤية

claude-sonnet-4-20250514 هو نموذج لغوي كبير متعدد الوسائط طورته Claude، ويضيف قدرة فهم الرؤية على أساس claude-4. يمكن لهذا النموذج معالجة مدخلات النصوص والصور في الوقت نفسه، مما يحقق الفهم والتوليد عبر الوسائط. تتوافق معالجة النصوص باستخدام نموذج claude-sonnet-4-20250514 مع محتوى الاستخدام الأساسي المذكور أعلاه، وفيما يلي مقدمة موجزة عن كيفية استخدام قدرة معالجة الصور الخاصة بالنموذج. تتمثل قدرة معالجة الصور لنموذج claude-sonnet-4-20250514 بشكل أساسي في إضافة حقل type على أساس محتوى content الأصلي، ومن خلال هذا الحقل يمكن معرفة ما إذا كان المرفوع نصًا أم صورة، وبالتالي استخدام قدرة معالجة الصور لنموذج claude-sonnet-4-20250514. وفيما يلي شرح رئيسي لاستدعاء هذه الوظيفة باستخدام طريقتي Curl وPython.
  • طريقة سكربت Curl
  • طريقة سكربت Python
بعد ذلك يمكن الحصول على النتيجة التالية، وتكون معلومات الحقول في النتيجة متسقة مع ما ورد أعلاه، كما يلي تحديدًا:
يمكن ملاحظة أن محتوى الإجابة يعتمد على الصورة، ولذلك يمكن بسهولة استخدام قدرات معالجة النصوص والصور لنموذج claude-3-7-sonnet-20250219 من خلال الطريقتين المذكورتين أعلاه.

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

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

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

الخلاصة

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