لا تكمن صعوبة ربط Claude API في «هل تعرف إرسال طلب HTTP»، بل في تفاصيل صغيرة يسهل الخطأ فيها: أي ترويسة يحمل المفتاح، وهل anthropic-version إلزامية، ولماذا لا يمكن حذف max_tokens، ولماذا content مصفوفة وليس نصًا. بمجرد ضبط هذه النقاط، يمكن تشغيل أصغر استدعاء خلال عشر دقائق.
تتبع هذه المقالة الترتيب التالي: الحساب والمفتاح، وترويسات الطلب، وcurl، وPython، والبث والمعاملات، وتشخيص الأخطاء، وأمان المفتاح، ثم شرح استخدام بوابة متوافقة كمدخل بديل. تُراجع معرّفات الطرازات وسياقها وفوترة استخدامها وفق وثائق Anthropic الرسمية وأسعار الطرازات داخل الموقع.
ملاحظة: Anthropic وClaude علامتان تجاريتان مملوكتان لمالكيهما، وOpenAI علامة تجارية مملوكة لمالكها. هذه المقالة مخصصة للشرح التقني فقط. تتغير الطرازات والأسعار والحصص، لذا يُرجى مراجعة الوثائق الرسمية قبل الربط.
أولًا: الاستعداد قبل الربط: الحساب ومساحة العمل والمفتاح
يدير Claude API الحساب ومساحة العمل ومفتاح API والفوترة عبر Anthropic Console. تأكد من ثلاثة أمور قبل البدء:
| عنصر الاستعداد | ما يجب تأكيده | ملاحظة |
|---|---|---|
| الحساب | بريد إلكتروني قابل للتحقق، وإمكانية الدخول إلى Console | يُفضّل للفرق استخدام بريد الشركة |
| مساحة العمل | إلى أي مساحة عمل ينتمي المفتاح | تؤثر مساحة العمل في الأعضاء والمفاتيح ونسبة الاستخدام |
| الفوترة | طريقة الدفع وبيانات الفاتورة والرصيد المتاح | يُعتمد ما يظهر فعليًا في Console |
إذا لم يحدد الفريق بعد من يدير الفاتورة، فلا تسارع بإنشاء مفتاح إنتاج. فبمجرد توزيع المفتاح، يُنسب الاستخدام والصلاحيات إلى مساحة العمل المقابلة، ويصبح فصل التكاليف لاحقًا أكثر كلفة.
ثانيًا: إنشاء مفتاح API في ست خطوات
- افتح Anthropic Console على console.anthropic.com، وسجّل حسابًا أو ادخل إليه، وأكمل التحقق من البريد الإلكتروني.
- أنشئ مساحة عمل أو اختر واحدة. يُستحسن فصل الإنتاج والاختبار والتجارب الشخصية، وتجنب استخدام مفتاح واحد في كل مكان.
- انتقل إلى صفحة API Keys، وأنشئ مفتاحًا جديدًا، واكتب اسمًا يوضح الغرض، مثل
prod-backend-2026-10. - انسخ المفتاح واخزنه فورًا في خدمة إدارة الأسرار أو في متغير بيئة. معظم لوحات التحكم تعرض القيمة الكاملة مرة واحدة فقط عند الإنشاء.
- راجع في صفحة الفوترة داخل Console طريقة الدفع وبيانات الفاتورة وإعدادات الحصة. أما دعم الشحن المسبق والفواتير وسقف الحصة فيُعتمد فيه على الخيارات الفعلية في لوحة التحكم.
- اضبط متغير البيئة محليًا، وأرسل أصغر طلب للتحقق من صلاحية المفتاح.
export ANTHROPIC_API_KEY="sk-ant-مفتاحك"
لا تكتب المفتاح داخل الشيفرة أو مستودع Git أو صفحات الواجهة الأمامية أو سجلات المحادثة. حتى في مرحلة الاختبار، يُستحسن إنشاء مفتاح منفصل ليسهل إلغاؤه في أي وقت.
ثالثًا: ترويسات الطلب وأصغر استدعاء عبر curl
نقطة نهاية Messages API هي POST https://api.anthropic.com/v1/messages، وأهم ثلاث ترويسات هي:
| الترويسة | القيمة | الوظيفة |
|---|---|---|
x-api-key |
مفتاح API الخاص بك | مصادقة مفتاح Anthropic API |
anthropic-version |
2023-06-01 |
تحديد إصدار API، وقد يؤدي غيابها إلى خطأ |
content-type |
application/json |
الإعلان عن أن جسم الطلب بصيغة JSON |
تنبيه: يُمرّر مفتاح API عبر x-api-key، وليس عبر Authorization: Bearer. خلط طريقتي المصادقة هاتين من أكثر أسباب الخطأ 401 شيوعًا.
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"system": "أنت مساعد تقني، وأجب بإيجاز.",
"messages": [
{"role": "user", "content": "اشرح ما هي بوابة API في ثلاث جمل."}
]
}'
معرّف الطراز في المثال هو واحد من الطرازات المتاحة حاليًا فقط. أما الطرازات المتاحة فعليًا وسياقها وأسعارها فتُعتمد على Models API الرسمية وأسعار الطرازات داخل الموقع. حقل content في الاستجابة مصفوفة كتل محتوى، ويوجد النص عادةً في content[0].text، لكن الطريقة الأكثر أمانًا هي المرور على الكتل والتحقق من type == "text".
رابعًا: استدعاء Messages API عبر Python
ثبّت SDK الرسمي:
pip install anthropic
أصغر استدعاء يكون كالتالي:
import os
import anthropic
client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
resp = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system="أنت مساعد تقني، وأجب بإيجاز.",
messages=[
{"role": "user", "content": "اشرح ما هي بوابة API في ثلاث جمل."}
],
)
for block in resp.content:
if block.type == "text":
print(block.text)
print(resp.stop_reason)
print(resp.usage.input_tokens, resp.usage.output_tokens)
نقاط مهمة:
systemمعامل على المستوى الأعلى، ولا يُكتب كرسالة{"role": "system"}. أدوار الرسائل في Messages API هي أساسًاuserوassistant.max_tokensإلزامي، ويحدد الحد الأقصى لطول الإخراج في هذا الرد. القيمة الصغيرة جدًا تقطع الإخراج ويظهرstop_reasonبالقيمةmax_tokens، والقيمة الكبيرة جدًا تتطلب مراعاة التكلفة والمهلة.resp.contentمصفوفة كتل، وقد تضم كتل نص أو كتل تفكير أو كتل استدعاء أدوات. لا تفترض في شيفرة العمل أنها نص فقط.- سجّل
usageوstop_reason، فهما أساس التسوية والتشخيص.
خامسًا: system وmax_tokens والإخراج المتدفق
يُستخدم system لتعريف الدور وتنسيق الإخراج والقيود. تُوضع المحتويات الثابتة في المقدمة، وتُترك مدخلات المستخدم المتغيرة في messages، وهذا يساعد على إصابة التخزين المؤقت.
max_tokens ليس «أكبر دائمًا أفضل». فهو يقيّد الحد الأعلى للإخراج في الطلب الواحد ولا يغيّر تكلفة الإدخال. التقارير الطويلة والشيفرة الطويلة تحتاج مساحة كافية، أما التصنيف والاستخراج فيمكن ضبطهما على قيم أصغر. في بيئة الإنتاج يُنصح بإعداد القيمة حسب نوع الواجهة، لا بقيمة واحدة عامة.
الإخراج المتدفق مناسب للإجابات الطويلة والواجهات التفاعلية. الصيغة في Python SDK:
with client.messages.stream(
model="claude-opus-5-5",
max_tokens=4096,
system="أنت مساعد تقني.",
messages=[{"role": "user", "content": "اكتب وصفًا لمنتج في مئتي كلمة."}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
تعيد الطلبات المتدفقة أيضًا usage وstop_reason، فلا تغفل عنهما عند التسجيل. عند استخدام HTTP مباشرة، أضف "stream": true إلى جسم الطلب؛ وتكون الاستجابة سلسلة أحداث SSE تُقرأ وفق أحداث مثل content_block_delta.
سادسًا: تسمية الطرازات واختيار الإصدار
تُقسّم طرازات Claude إلى عائلات مثل Opus وSonnet وHaiku، وتختلف مواقعها وسياقها وأسعارها. توجد لمعرّفات الطرازات صورتان شائعتان: الاسم المستعار المستقر واللقطة المؤرخة. يجب على بيئة الإنتاج تحديد أي صورة تستخدم، ولا يجوز نسخ الاسم المعروض في لوحة التحكم مباشرة إلى الشيفرة.
ترتيب الاختيار المقترح:
- استخدم مجموعة تقييم من أعمالك لتصفية العائلات التي تحقق متطلبات الجودة.
- ثم قارن زمن الاستجابة والسياق والتكلفة.
- أخيرًا تأكد من توفر الطراز في المنطقة المستهدفة وطريقة الربط المتبعة.
تُضاف الطرازات وتُزال، وقد تدخل المعرّفات القديمة حالة legacy. اجمع أسماء الطرازات في إعداد أو جدول تحويل، بحيث تتغير في مكان واحد عند الترحيل. الطرازات المتاحة فعليًا تُعتمد على Models API الرسمية ولوحة التحكم وأسعار الطرازات.
سابعًا: كيف تشخّص أخطاء 401 و429 و400
| رمز الحالة | الأسباب الشائعة | ترتيب المعالجة |
|---|---|---|
| 401 | غياب المفتاح، خطأ في الترويسة، إلغاء المفتاح، عدم تطابق مساحة العمل | تحقق من x-api-key والمسافات والأسطر الجديدة وحالة المفتاح وbase URL |
| 429 | تجاوز معدل الطلبات أو معدل الرموز، ارتفاع مفاجئ في التزامن، مشكلة في الحصة | اقرأ retry-after، واستخدم تراجعًا أسيًا مع تشويش، وافصل المفاتيح، وخفّض التزامن |
| 400 | JSON غير صالح، غياب max_tokens، معرّف طراز خاطئ، معامل خارج الحد |
احتفظ بجسم الخطأ وrequest id، وراجع جسم الطلب بندًا بندًا |
| 404 | المسار أو اسم الطراز غير موجود | تأكد من /v1/messages ومن معرّف الطراز |
| 5xx | عطل مؤقت في المنبع | أعد المحاولة عددًا محدودًا، ثم انتقل إلى مدخل بديل عند استمرار الفشل |
احتفظ بترويسة request-id عند التشخيص. لا تشك في الرصيد أولًا عند ظهور 401، بل راجع ترويسة المصادقة والمفتاح نفسه. و429 لا يعني بالضرورة «نفاد المال»، فقد يكون حدًا للمعدل. أما 400 فهو غالبًا مشكلة في جسم الطلب، ورسالة الخطأ تحدد الحقل المعني عادةً.
ثامنًا: أمان المفتاح والمدخل البديل عبر بوابة متوافقة
يلزم لأمان المفتاح أربعة أمور على الأقل: تخزينه في متغيرات البيئة أو خدمة إدارة الأسرار فقط؛ وفصل المفاتيح حسب المشروع؛ وإعداد تنبيهات الاستخدام؛ وتدوير المفاتيح بانتظام وإلغاء مفاتيح الأعضاء المغادرين. لا يجوز أن تظهر مفاتيح دائمة في الواجهة الأمامية أو تطبيقات الجوال أو المستودعات العامة.
إذا واجهت الفرق المحلية مشكلات في الشبكة أو الدفع أو الفواتير، يمكنها استخدام بوابة توفر نقاط نهاية متوافقة مع Anthropic بدلًا من العنوان الرسمي. يحتاج SDK الرسمي عادةً إلى تغيير base_url والمفتاح فقط:
import os
from anthropic import Anthropic
client = Anthropic(
api_key=os.environ["ZSQH_API_KEY"],
base_url="https://ai.zhongshangqihang.com",
)
resp = client.messages.create(
model="حسب قائمة الطرازات في الموقع",
max_tokens=256,
messages=[{"role": "user", "content": "أجب بكلمة OK فقط"}],
)
print(resp.content)
إذا كانت البوابة توفر واجهة متوافقة مع OpenAI فقط، فيجب تعديل بنية الطلب أو إضافة طبقة تحويل، ولا يكفي تغيير base URL. عند اختيار البوابة تأكد من ثلاثة أمور: دعم بروتوكول Anthropic الأصلي، وكيفية تحويل أسماء الطرازات، وشفافية سياسات الحد والتسجيل.
تاسعًا: الأسئلة الشائعة
هل Claude API واشتراك موقع Claude الإلكتروني شيء واحد؟
لا. الموقع الإلكتروني اشتراك منتج موجه للمستخدمين، بينما تُحاسب واجهة API حسب الاستخدام. يختلف نظاما الحساب والحصة ومدخل الإدارة. تُدار مفاتيح API والفواتير والاستخدام في Anthropic Console.
هل يمكن رؤية القيمة الكاملة لمفتاح API بعد إنشائه؟
في معظم الحالات تُعرض مرة واحدة فقط عند الإنشاء، وبعدها لا يظهر سوى البادئة أو الاسم. لذلك يجب تخزينه فورًا في خدمة إدارة الأسرار؛ وإذا فُقد، فألغِ المفتاح القديم وأنشئ آخر.
لماذا يجب تمرير max_tokens؟
يشترط Messages API الإعلان صراحةً عن الحد الأعلى للإخراج في الطلب الواحد، للتحكم في طول التوليد والموارد. حذفه يعيد 400. اضبط قيمة معقولة حسب المهمة، ولا ترفعها إلى الحد الأقصى دون داعٍ.
هل يعني 429 نفاد الحصة أم ارتفاع التزامن؟
قد يكون أيًا منهما. راجع جسم الاستجابة وretry-after أولًا: الظهور المركز في فترة قصيرة يشير غالبًا إلى معدل أو تزامن مرتفع؛ والظهور المستمر مع رصيد غير طبيعي يستدعي مراجعة الخطة والاستخدام. تشمل المعالجة التراجع وإعادة المحاولة وخفض التزامن وفصل المفاتيح.
هل تحتاج الفرق المحلية إلى بوابة بالضرورة؟
ليس بالضرورة. الفرق القادرة على الاتصال المباشر المستقر وإتمام الدفع وتقييم الامتثال تجد الاتصال الرسمي أبسط. أما الحاجة إلى تسوية بالعملة المحلية أو الفواتير أو مدخل موحد لعدة طرازات أو تحسين الشبكة فتستدعي تقييم البوابة، مع التأكد من سياسات البيانات ومعالجة الأعطال.
الخطوة التالية
ابدأ بـالتسجيل في بوابة ZSQH AI، وشغّل أصغر طلب إلى /v1/messages بمفتاح اختبار، ثم اربط أعمالك. تُعتمد الطرازات والسياق والفوترة على أسعار الطرازات.
قراءات ذات صلة:
