كيف تدمج Claude API في تطبيقك

لدمج Claude API، أنشئ مفتاح API في Claude Console الخاص بـ Anthropic، وخزّنه كـسر على الخادم (عادةً باسم ANTHROPIC_API_KEY)، ثم استدعِ Messages API من مسار على خادمك باستخدام إحدى حزم SDK الرسمية. يحدد كل طلب model، ويضبط max_tokens (أطول رد تقبله)، ويرسل المحادثة كـmessages، مع وضع تعليماتك في system prompt منفصل. اضبط حدًا للإنفاق، وابث الردود الطويلة مباشرة، وتعامل مع أخطاء تجاوز المعدل (429) وأخطاء الحمل الزائد (529) بإعادة المحاولة.

يغطي هذا الدليل الإعداد، وتدفق طلب آمن، وتعليمات لأداة بناء بالذكاء الاصطناعي، والأخطاء التي يجب التخطيط لها. تفاصيل Anthropic مأخوذة من وثائقها حتى سبتمبر 2026. لمعرفة كيف تعمل الرموز (tokens) والتسعير بشكل عام، اقرأ كيف تستخدم واجهات LLM البرمجية أولًا.

ما الذي يمكنك بناؤه به

مساعدات دردشة وأدوات مساعدة داخل التطبيق (كيف تبني تطبيق دردشة بالذكاء الاصطناعي)
ملخصات وإعادة صياغة ومسودات ردود
استخراج الحقول من المستندات ورسائل البريد والنماذج
الإجابة عن الأسئلة من محتواك الخاص
وكلاء يستدعون دوال تطبيقك عبر استخدام الأدوات (tool use)

لمزيد من الأفكار، انظر كيف تضيف ميزات الذكاء الاصطناعي إلى تطبيقك.

Messages API باختصار

بحسب مرجع واجهة Anthropic البرمجية، يكون الطلب عبارة عن POST إلى https://api.anthropic.com/v1/messages مع:

الجزء	ماذا يمثل
ترويسة `x-api-key`	مفتاح API الخاص بك
ترويسة `anthropic-version`	إصدار الواجهة، مثل `2023-06-01`
`model` (مطلوب)	نموذج Claude المستخدم
`max_tokens` (مطلوب)	أكبر عدد من الرموز يمكن أن يحتويه الرد؛ وقد يتوقف النموذج قبل ذلك
`messages` (مطلوب)	المحادثة: أدوار متناوبة من `user` و`assistant`
`system` (اختياري)	تعليمات تنطبق على المحادثة كلها
`stream` (اختياري)	اضبطه على `true` لاستقبال الرد أثناء كتابته، عبر أحداث يرسلها الخادم (server-sent events)

الواجهة عديمة الحالة (stateless): لمواصلة المحادثة، أرسل الأدوار السابقة مرة أخرى مع كل طلب. لهذا تزداد تكلفة المحادثات الطويلة مع كل رسالة.

تنشر Anthropic حزم SDK رسمية للغات Python وTypeScript وC# وGo وJava وPHP وRuby. وهي تضبط الترويسات، وتحلل الردود، وتدعم البث. استخدمها بدل HTTP الخام إلا إذا كان لديك سبب لعدم ذلك.

اختيار النموذج

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

إعداد حسابك

سجّل الدخول إلى Claude Console على platform.claude.com وأضف طريقة الدفع.
أنشئ مفتاح API. احتفظ بمفتاح منفصل لكل بيئة (الاختبار والإنتاج) حتى تستطيع إلغاء أحدهما دون كسر الآخر.
اضبط حدًا للإنفاق. تشير صفحة الأخطاء لدى Anthropic إلى أنه عند بلوغ الاستخدام حد الإنفاق الذي وضعته، تُعيد الواجهة خطأ 400، لذا يجب أن يعرض تطبيقك رسالة واضحة عند حدوث ذلك.
راجع حدود المعدل لحسابك في Console؛ فهي تُقاس على مستوى المؤسسة.

تدفق الطلب

يتفاعل المستخدم داخل تطبيقك: يرسل رسالة، أو ينقر على «لخّص».
يستدعي المتصفح مسار خادمك أنت، وليس Anthropic مباشرة أبدًا.
يتحقق خادمك من أن المستخدم مسجّل الدخول ومسموح له باستخدام الميزة، ويطبق حدًا لكل مستخدم.
يبني الطلب: تعليمات نظام تحتوي على قواعدك، ومدخلات المستخدم، وأي بيانات تحتاجها المهمة من قاعدة بياناتك.
يستدعي Messages API باستخدام المفتاح من متغيرات البيئة، وmax_tokens مناسب.
يبث الرد إلى المتصفح، ويسجّل استهلاك الرموز من الاستجابة.

الخيارات والمفاضلات

القرار	الخيار البسيط	متى تذهب أبعد
البث	انتظر الرد كاملًا	ابث في الدردشة وأي رد طويل؛ وتوصي Anthropic بالبث أو الدفعات للطلبات طويلة الأمد
شكل المخرجات	نص عادي	مخرجات JSON منظمة عندما يحتاج كودك إلى قراءة حقول
بياناتك	أدرج السجل ذا الصلة	الاسترجاع من محتواك عندما يكون هناك أكثر مما يتسع (ما هو RAG)
الإجراءات	النموذج يكتب نصًا فقط	استخدام الأدوات (tool use)، حيث يطلب النموذج من كودك تنفيذ دالة عرّفتها
العمل الجماعي غير العاجل	كرر على العناصر	واجهة Message Batches، التي ترسل الطلبات وتستعلم عن النتائج لاحقًا

تعليمات لأداة البناء بالذكاء الاصطناعي

ميزة أولى:

أضف لوحة «اسأل عن هذا المستند». تستدعي مسار خادم POST /api/ask يتحقق من أن المستخدم مسجّل الدخول ومالك للمستند، ثم تستدعي Claude Messages API باستخدام حزمة Anthropic الرسمية والسر ANTHROPIC_API_KEY. اقرأ معرّف النموذج من السر CLAUDE_MODEL. تعليمات النظام: «أجب فقط من المستند المقدم. إذا لم تكن الإجابة فيه، فقل ذلك.» أرسل نص المستند والسؤال، واضبط max_tokens على 800، وابث الإجابة إلى الصفحة، ولا تكشف المفتاح للمتصفح أبدًا.

الضوابط والأخطاء:

حدّد كل مستخدم بـ20 سؤالًا في الساعة، مع تتبع ذلك في قاعدة البيانات. سجّل رموز الإدخال والإخراج من كل رد مع معرّف المستخدم ومعرّف الطلب. عند الحصول على خطأ 429 أو 529، أعد المحاولة مع تأخير متزايد حتى 3 مرات، مع احترام ترويسة retry-after إن وُجدت، ثم اعرض «المساعد مشغول، حاول مجددًا بعد قليل.» وإذا أبلغت الواجهة عن خطأ في حد الإنفاق، فاعرض «ميزات الذكاء الاصطناعي متوقفة مؤقتًا» وأرسل تنبيهًا للمشرف.

الأخطاء التي يجب التخطيط لها

من وثائق الأخطاء لدى Anthropic، الأخطاء التي سيواجهها تطبيقك فعلًا:

الرمز	النوع	ما الذي يجب فعله
400	`invalid_request_error`	أصلح الطلب؛ ويُعاد أيضًا عند بلوغ حد الإنفاق الذي وضعته
401	`authentication_error`	تحقق من أن المفتاح موجود وصحيح وغير ملغى
413	`request_too_large`	أرسل بيانات أقل؛ فالواجهة تقبل حتى 32 ميغابايت لكل طلب
429	`rate_limit_error`	تراجع وأعد المحاولة مع احترام `retry-after`
500	`api_error`	أعد المحاولة مع تأخير متزايد؛ وتواصل مع الدعم مع معرّف الطلب إذا استمر الخطأ
529	`overloaded_error`	كثافة مؤقتة في الطلبات من كل المستخدمين؛ تراجع وأعد المحاولة

تقول وثائق Anthropic إن حزم SDK الرسمية تعيد تلقائيًا محاولة الإخفاقات المؤقتة (أخطاء الاتصال وتجاوز المعدل وأخطاء 5xx) مرتين افتراضيًا مع تأخير متزايد، ويمكنك ضبط ذلك. وكل رد يحمل ترويسة request-id؛ سجّلها حتى يتمكن الدعم من تتبع المشكلات.

أخطاء شائعة

استدعاء الواجهة من المتصفح. يصبح مفتاحك عامًا. اذهب دائمًا عبر خادمك. انظر كيف تحافظ على أمان مفاتيح API.
نسيان أن max_tokens حد أقصى وليس هدفًا. اضبطه على ما تحتاجه الميزة؛ فالقيمة المنخفضة تقطع الإجابات، والمرتفعة تخاطر بردود طويلة ومكلفة.
وضع القواعد في رسالة المستخدم. التعليمات الثابتة تنتمي إلى system، والصلاحيات تنتمي إلى كودك.
إرسال المحادثة كاملة إلى الأبد. اقتطع الأدوار القديمة أو لخّصها مع نمو المحادثات.
عدم وجود حد إنفاق أو حد لكل مستخدم.
تثبيت معرّف النموذج في الكود. النماذج تُحدَّث وتُسحب.
تجاهل سبب التوقف (stop reason). إذا توقف الرد لأنه بلغ max_tokens، أخبر المستخدم أو ارفع الحد.

قائمة التحقق

تم إنشاء مفتاح API في Claude Console وحفظه كسر على الخادم
مفاتيح منفصلة للاختبار والإنتاج
حد إنفاق مضبوط، ورسالة واضحة عند بلوغه
كل الطلبات تمر عبر خادمك مع فحص الصلاحيات
تحتوي تعليمات النظام على القواعد، ومعرّف النموذج قابل للضبط
max_tokens مضبوط لكل ميزة، والردود الطويلة تُبث
حد لكل مستخدم في تطبيقك
التعامل مع 429 و529 بتأخير متزايد، وتسجيل معرّفات الطلبات
حالة خطأ ودية لا تكسر الصفحة
تم الاختبار بمدخلات فارغة، وطويلة جدًا، ومعادية

استخدام Claude API في Mythex

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

الأسئلة

كيف أحصل على مفتاح Claude API؟

سجّل الدخول إلى Claude Console على platform.claude.com، وأعدّ الفوترة، ثم أنشئ مفتاح API. خزّنه كسر من أسرار الخادم، واسمه المعتاد ANTHROPIC_API_KEY، ولا تضعه أبدًا في كود المتصفح.

ما الذي يحتاجه طلب Claude API؟

حسب مرجع Messages API من Anthropic في سبتمبر 2026، هناك ثلاثة حقول مطلوبة في جسم الطلب: model وmax_tokens وmessages. أما الطلبات المباشرة عبر HTTP فتحتاج أيضًا إلى الترويسات x-api-key وanthropic-version؛ وتضبطها حزم SDK الرسمية عنك.

ما معنى خطأ 529 من Claude API؟

تصف صفحة الأخطاء لدى Anthropic الخطأ 529 بأنه overloaded_error: الواجهة مثقلة مؤقتًا بسبب كثافة الطلبات من كل المستخدمين. أعد المحاولة مع تأخير متزايد (exponential backoff). وتعيد حزم SDK الرسمية المحاولة تلقائيًا في بعض الأخطاء المؤقتة.

هل يمكنني استخدام Claude مع كود مكتوب لحزمة OpenAI SDK؟

توثّق Anthropic طبقة توافق مع OpenAI SDK تتيح استخدام Claude عبر واجهة OpenAI SDK. أما في الكود الجديد، فتمنحك حزمها الخاصة الوصول إلى ميزات Claude المخصصة، لذا تكون عادةً نقطة البداية الأفضل.