Blog

كيفية استخدام Claude Opus 5 API؟

دليل خطوة بخطوة لواجهة برمجة تطبيقات Claude Opus 5: احصل على مفتاح، أرسل استدعاءك الأول باستخدام معرّف نموذج claude-opus-5، قم ببث الاستجابات، أضف استخدام الأدوات، اضبط الجهد، واقرأ الاستخدام المتعلق بإصابات ذاكرة التخزين المؤقت.

Ashley Innocent

Ashley Innocent

25 يوليو 2026

كيفية استخدام Claude Opus 5 API؟

Apidog للمؤسسات

النشر على الخوادم المحلية

SSO و RBAC

متوافق مع SOC 2

استكشف Apidog للمؤسسات

تم شحن Claude Opus 5 في 24 يوليو 2026، وتوجه Anthropic المطورين إليه أولاً: تقول الوثائق أنه إذا كنت غير متأكد من النموذج الذي يجب استخدامه، فابدأ بـ Claude Opus 5. معرف نموذج API هو السلسلة الدقيقة claude-opus-5، بدون لاحقة تاريخ.

يرشدك هذا الدليل خلال المسار بأكمله: الحصول على مفتاح، وإرسال طلب أول، والتدفق، واستخدام الأدوات، والتفكير التكيفي، ومعلمة effort، وقراءة كائن usage لتأكيد عمل ذاكرة التخزين المؤقت للموجه الخاص بك. كل طلب هنا هو HTTP عادي مع إدخال وإخراج JSON، لذا يمكنك بناؤه وتصحيح أخطائه في Apidog قبل ربطه برمز التطبيق.

زر

سيواجهك تغييران من Opus 4.8 في أول مكالمة، لذا يأتيا قبل أي شيء آخر. إذا كنت تقوم بترحيل خدمة قائمة بدلاً من البدء من جديد، فاقرأ دليل الترحيل الكامل من Opus 4.8 إلى Opus 5 جنبًا إلى جنب مع هذا.

قبل مكالمتك الأولى: تغييران رئيسيان

1. التفكير مفعل افتراضيًا. في Opus 4.8، كان الطلب بدون حقل thinking يعمل بدون تفكير على الإطلاق. في Opus 5، يعمل نفس الطلب مع التفكير التكيفي. لا يزال max_tokens حدًا أقصى صارمًا لرموز التفكير بالإضافة إلى رموز الاستجابة معًا، لذا فإن نص الطلب الذي نسخته من تكامل 4.8 يعمل الآن قد يتم اقتطاعه في منتصف الإجابة. إذا تم ضبط max_tokens الخاص بك بإحكام حول طول الإخراج المتوقع، فقم بزيادته.

2. تعطيل التفكير يحد من مستوى جهدك. إرسال thinking: {"type": "disabled"} جنبًا إلى جنب مع جهد xhigh أو max يعيد 400. تفرض Anthropic ذلك لكل طلب، لذا يفشل فورًا بدلاً من التدهور بهدوء. الحل هو اختيار أحد الخيارين: إبقاء التفكير مفعلًا وتقليل الجهد للتحكم في التكلفة، أو إبقاء التفكير معطلاً وتحديد الجهد بـ high.

نصيحة Anthropic نفسها هي الخيار الأول. مع تعطيل التفكير، يقوم Opus 5 أحيانًا بكتابة استدعاءات الأدوات كنص عادي (لا يتم تنفيذها أبدًا، ويُلوث النص المسرب الدورات اللاحقة في حلقة الوكيل) وأحيانًا يسرب وسوم <thinking> إلى الإخراج المرئي. إبقاء التفكير مفعلًا وتقليل الجهد يتجنب كلا الأمرين.

تم توثيق كلا التغييرين في دليل ترحيل النماذج الخاص بـ Anthropic.

الخطوة 1: الحصول على مفتاح API

سجّل الدخول إلى منصة Claude للمطورين، وافتح قسم مفاتيح API في إعدادات مؤسستك، وأنشئ مفتاحًا. انسخه مرة واحدة؛ لا يمكنك قراءته لاحقًا.

قم بتخزينه في متغير بيئة بدلاً من لصقه في التعليمات البرمجية:

export ANTHROPIC_API_KEY="sk-ant-..."

إذا كنت تختبر في عميل واجهة رسومية، ضع المفتاح في متغير بيئة هناك أيضًا. في Apidog، يعني ذلك إنشاء بيئة (محلي، مرحلة، إنتاج) باستخدام متغير ANTHROPIC_API_KEY، ثم الإشارة إلى {{ANTHROPIC_API_KEY}} في الترويسة. تبقى طلباتك المحفوظة قابلة للمشاركة مع الفريق ولا يصل السر أبدًا إلى تصدير المجموعة.

تحتاج أيضًا إلى إضافة رصيد فواتير قبل أن تنجح الطلبات. أسعار Opus 5 هي 5 دولارات لكل مليون رمز إدخال و 25 دولارًا لكل مليون رمز إخراج، وهي نفس أسعار Opus 4.8، ويغطي توزيع الأسعار الكامل معدلات التخزين المؤقت والدُفعات والوضع السريع.

الخطوة 2: إرسال طلبك الأول

نقطة النهاية هي POST https://api.anthropic.com/v1/messages. تهم ثلاثة ترويسات: مفتاحك، إصدار API، ونوع المحتوى.

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-opus-5",
    "max_tokens": 4096,
    "messages": [
      {"role": "user", "content": "Explain the difference between a 429 and a 529 from an API perspective."}
    ]
  }'

لاحظ قيمة max_tokens. 4096 هي خطوة مقصودة للأعلى من 1024 التي تراها في معظم مقتطفات البدء، لأن رموز التفكير تأتي الآن من نفس الميزانية.

المعادل البايثون عبر SDK الرسمي:

import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Explain the difference between a 429 and a 529 from an API perspective."}
    ],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

تلك الحلقة على message.content ليست زخرفة. content الاستجابة عبارة عن مصفوفة من الكتل المكتوبة، ومع تفعيل التفكير، سترى الآن كتلة thinking قبل كتلة text. التعليمات البرمجية التي افترضت أن content[0].text كانت هي الإجابة تتعطل في Opus 5. هذا هو فشل الترقية الأكثر شيوعًا، ومن السهل إغفاله لأن الطلب لا يزال يعيد 200.

بعض المواصفات التي تستحق أن تكون أمامك أثناء البناء: يحتوي Opus 5 على نافذة سياق بحجم 1M رمز كلاهما الافتراضي والحد الأقصى (لا توجد ترويسة تجريبية، ولا تكلفة إضافية لسياق طويل)، وحد أقصى للإخراج يبلغ 128 ألفًا على Messages API، وقطع معرفي بتاريخ مايو 2026. يحتوي نظرة عامة على النماذج على الجدول الكامل، ويغطي شرح Opus 5 لدينا بقية ورقة المواصفات.

الخطوة 3: العمل مع التفكير التكيفي

التفكير التكيفي يعني أن النموذج يقرر مقدار الاستدلال الداخلي الذي يستحقه الطلب. لا تحدد ميزانية للرموز. توجهه بالجهد، وهو ما سيتم تغطيته في الخطوة التالية.

ما تحتاج إلى التعامل معه في الكود:

لإيقاف التفكير تمامًا:

{
  "model": "claude-opus-5",
  "max_tokens": 4096,
  "thinking": {"type": "disabled"},
  "output_config": {"effort": "high"},
  "messages": [{"role": "user", "content": "Return only the HTTP status code."}]
}

تم تحديد الجهد بـ high في هذا الطلب عن قصد. ارفعه إلى xhigh وستحصل على الخطأ 400 الموصوف أعلاه.

الخطوة 4: التحكم في التكلفة باستخدام output_config.effort

يوجد حقل effort ضمن output_config ويقبل القيم low، medium، high، xhigh، أو max. القيمة الافتراضية له هي high. هذه هي المعلمة التي وصفتها التغطية الرئيسية بأنها مفتاح تبديل بين التكلفة والقدرة؛ في API هي سلسلة واحدة في نص طلبك.

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-opus-5",
    "max_tokens": 65536,
    "output_config": {"effort": "xhigh"},
    "messages": [
      {"role": "user", "content": "Refactor this handler to stream responses and keep backpressure."}
    ]
  }'

ثلاثة أشياء يجب معرفتها قبل ضبطه.

الخطوة 5: دفق الاستجابة

أضف "stream": true وستعيد نقطة النهاية أحداثًا مرسلة من الخادم بدلاً من جسم JSON واحد.

with client.messages.stream(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Draft a retry policy for a flaky upstream."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

    final = stream.get_final_message()
    print("\n\nusage:", final.usage)

تسلسل SSE الخام هو message_start، ثم content_block_start / content_block_delta / content_block_stop لكل كتلة، ثم message_delta الذي يحمل stop_reason وعدد الرموز النهائية للإخراج، ثم message_stop.

مع تفعيل التفكير، تحصل على كتلتين من المحتوى تتدفقان بالترتيب: كتلة تفكير تصل دلتاها كـ thinking_delta، ثم كتلة النص مع text_delta. واجهة المستخدم التي تعرض كل دلتا في نفس المخزن المؤقت ستطبع استدلال النموذج لمستخدميك. قم بتوجيههما بشكل منفصل منذ البداية.

التدفق هو أيضًا المكان الذي يكتسب فيه عميل واجهة المستخدم الرسومية مكانته، لأن قراءة SSE الخام في محطة طرفية أمر مزعج. يقوم Apidog بعرض تدفق الأحداث فور وصوله، حتى تتمكن من مراقبة حدود الكتل وتأكيد افتراضات التحليل الخاصة بك قبل كتابة سطر واحد من التعليمات البرمجية للمعالج.

الخطوة 6: إضافة استخدام الأدوات

تذهب تعريفات الأدوات في مصفوفة tools. يجيب النموذج بـ stop_reason: "tool_use" وكتلة محتوى tool_use؛ تقوم بتنفيذ الأداة وإرسال النتيجة مرة أخرى ككتلة tool_result في رسالة مستخدم جديدة.

tools = [
    {
        "name": "get_order_status",
        "description": "Look up the current status of a customer order by ID.",
        "input_schema": {
            "type": "object",
            "properties": {
                "order_id": {"type": "string", "description": "The order ID, e.g. A-10293"}
            },
            "required": ["order_id"],
        },
    }
]

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    tools=tools,
    messages=[{"role": "user", "content": "What's the status of order A-10293?"}],
)

if message.stop_reason == "tool_use":
    call = next(b for b in message.content if b.type == "tool_use")
    result = get_order_status(**call.input)

    follow_up = client.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        tools=tools,
        messages=[
            {"role": "user", "content": "What's the status of order A-10293?"},
            {"role": "assistant", "content": message.content},
            {"role": "user", "content": [
                {"type": "tool_result", "tool_use_id": call.id, "content": result}
            ]},
        ],
    )

تمرير message.content مباشرة كدور المساعد هو ما يحافظ على كتلة التفكير. لا تقم بإعادة بناء هذا الدور يدويًا.

تفصيلان من Opus 5 يهمان الوكلاء. الحمل الزائد لموجه نظام استخدام الأدوات أقل مما كان عليه في Opus 4.8: 286 رمزًا مع تعيين tool_choice على auto أو none، مقابل 290 في 4.8 و 675 في Opus 4.7. هذا الرقم صغير لكل طلب، ولكنه حقيقي عبر مليون دور للوكيل. وهناك ترويسة تجريبية، mid-conversation-tool-changes-2026-07-01، تتيح لك إضافة أو إزالة الأدوات بين الأدوار دون إبطال ذاكرة التخزين المؤقت للموجه.

يفوض Opus 5 أيضًا إلى الوكلاء الفرعيين بسهولة أكبر مما كان عليه في 4.8. في أعباء العمل الحساسة للتكلفة، حدد ذلك صراحةً في موجه النظام الخاص بك بدلاً من اكتشافه في الفاتورة.

الخطوة 7: قراءة كائن الاستخدام (usage object) لضربات ذاكرة التخزين المؤقت

تحمل كل استجابة كائن usage. إنها الطريقة الصادقة الوحيدة لتأكيد أن ذاكرة التخزين المؤقت للموجه الخاص بك تعمل.

"usage": {
  "input_tokens": 84,
  "cache_creation_input_tokens": 6421,
  "cache_read_input_tokens": 0,
  "output_tokens": 913
}

لتخزين كتلة مؤقتًا، قم بتمييزها بـ cache_control:

{
  "model": "claude-opus-5",
  "max_tokens": 4096,
  "system": [
    {
      "type": "text",
      "text": "<your long, stable instructions and reference material>",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [{"role": "user", "content": "Question one."}]
}

المكالمة الأولى: cache_creation_input_tokens غير صفرية و cache_read_input_tokens هي 0. المكالمة الثانية بنفس البادئة: تنقلب هذه القيم. إذا لم تنقلب أبدًا، فإن بادئتك ليست متطابقة بايتًا أو أنها أقل من الحد الأدنى.

هذا الحد الأدنى هو الخبر السار في Opus 5. يبدأ التخزين المؤقت للموجه الآن عند 512 رمزًا، نزولاً من 1024 في Opus 4.8. الموجهات التي كانت قصيرة جدًا بحيث لا يمكن تخزينها مؤقتًا من قبل، يتم تخزينها الآن دون أي تغيير في التعليمات البرمجية على الإطلاق، وتُحاسب قراءات ذاكرة التخزين المؤقت بسعر 0.50 دولار لكل مليون رمز مقابل معدل إدخال أساسي قدره 5 دولارات. تأكد من cache_read_input_tokens في مجموعة اختباراتك بحيث يظهر تعديل الموجه الذي يفشل ذاكرة التخزين المؤقت بصمت كاختبار فاشل بدلاً من فاتورة. لمزيد من الأدوات، راجع دليلنا حول خفض فاتورة Claude API.

اختبر وتصحيح الأخطاء في التدفق بأكمله في Apidog

كل ما سبق هو طلب HTTP مع ترويسات مصادقة، وجسم JSON، وتدفق SSE، واستجابة تحتاج إلى التأكد منها. Apidog هي منصة تطوير API شاملة، وهذا هو بالضبط نوع نقطة النهاية التي تتعامل معها: فهي ترسل الطلب، وتخزن المفتاح، وتعرض التدفق، وتختبر الاستجابة. لا تقوم بتشغيل الاستدلال أو توجيه النماذج؛ المكالمة لا تزال تذهب إلى Anthropic.

إعداد يؤتي ثماره من اليوم الأول:

  1. إنشاء الطلب. POST https://api.anthropic.com/v1/messages مع الترويسات الثلاثة، والمفتاح المستخرج من متغير بيئة بدلاً من لصقه مباشرة.
  2. احفظه في مجموعة. يعيد فريقك استخدام شكل طلب واحد معروف وموثوق به بدلاً من أن يقوم كل شخص بإعادة بنائه من مقتطف مدونة.
  3. افصله لكل مستوى جهد. كرر الطلب مع تعيين output_config.effort على low، medium، high، و xhigh، وأرسل نفس الموجه لكل منها، وقارن جودة الإخراج، ووقت الاستجابة، وعدد الرموز جنبًا إلى جنب. هذا هو مسح الجهد الذي تطلب Anthropic منك تشغيله، ويتم ذلك دون كتابة أدوات اختبار.
  4. راقب تدفق SSE. قم بتشغيل "stream": true واقرأ الأحداث فور وصولها لتأكيد أنك تتعامل مع كتل التفكير وكتل النص بشكل منفصل.
  5. افحص حمولات استدعاء الأدوات. عندما يعود stop_reason كـ tool_use، يكون كائن input الدقيق الذي أنتجه النموذج موجودًا هناك، وهذه هي الطريقة التي تكتشف بها أن input_schema الخاص بك كان فضفاضًا جدًا.
  6. تأكد من الاستجابة. أضف فحوصات للتأكد من أن stop_reason ليس max_tokens (علامة الاقتطاع الخاصة بك) وأن cache_read_input_tokens أعلى من الصفر في المكالمات المتكررة (علامة التخزين المؤقت الخاصة بك).

قم بتنزيل Apidog إذا كنت ترغب في المتابعة. نفس نمط المجموعة يعمل مع أي نموذج Claude، لذا يمكنك توجيهه إلى Sonnet 5 أو طلبات Opus 4.8 الموجودة لديك ومقارنة السلوك.

الأخطاء والمشاكل التي ستواجهها بالفعل

الحد الأقصى الصادق

Opus 5 ليس قمة مكدس Claude، ويجدر القول بصراحة. لا يزال Fable 5 يحمل تصنيف Anthropic لـ "الأكثر قدرة والأوسع انتشارًا"، بسعر 10 دولارات لكل مليون إدخال و 50 دولارًا لكل مليون إخراج. يتخلف Opus 5 أيضًا عن Mythos 5 في استغلال الأمن السيبراني وأبحاث البيولوجيا الذاتية، وهو ما ذكرته Anthropic بنفسها.

إن ادعاءات معايير الإطلاق (تقريبًا ضعف Opus 4.8 على Frontier-Bench v0.1، حوالي 3 أضعاف أفضل نموذج تالي على ARC-AGI 3، في حدود 0.5% من Fable 5 على CursorBench 3.2) هي كلها أرقام Anthropic الخاصة ولم يتم إعادة إنتاجها بشكل مستقل اعتبارًا من 25 يوليو 2026. اقرأها على أنها نتائج تشغلها الشركة، ثم قم بإجراء تقييماتك الخاصة. يتناول مقارنة Opus 5 مقابل Fable 5 أين يستحق الفارق في السعر وأين لا يستحق، و منشور إطلاق Anthropic هو المصدر الأساسي للادعاءات نفسها.

الأسئلة الشائعة

ممارسة تصميم API في Apidog

اكتشف طريقة أسهل لبناء واستخدام واجهات برمجة التطبيقات

التسجيل مجانًاتحميل