DEV Community

Cover image for كيفية استخدام Claude Opus 5 API؟
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

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

تم شحن Claude Opus 5 في 24 يوليو 2026، وتوصي Anthropic المطورين بالبدء به عند عدم التأكد من النموذج المناسب. معرّف نموذج API هو claude-opus-5 بدون لاحقة تاريخ. يشرح هذا الدليل إعداد المفتاح، إرسال أول طلب، الدفق، الأدوات، التفكير التكيفي، effort، والتحقق من التخزين المؤقت عبر كائن usage. جميع الأمثلة هي طلبات HTTP وJSON يمكنك بناؤها وفحصها في Apidog قبل دمجها في تطبيقك.

جرّب Apidog اليوم

إذا كنت تهاجر من Opus 4.8، راجع أيضًا دليل الترحيل الكامل من Opus 4.8 إلى Opus 5.

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

1. التفكير مفعّل افتراضيًا

في Opus 4.8، كان الطلب الذي لا يحتوي على thinking يعمل بدون تفكير. في Opus 5، يعمل الطلب نفسه بالتفكير التكيفي.

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

الإجراء العملي: ارفع max_tokens عند ترحيل طلبات Opus 4.8، ثم افحص stop_reason في الاختبارات.

2. تعطيل التفكير يقيّد مستوى الجهد

هذا الدمج يعيد خطأ 400:

{
  "thinking": { "type": "disabled" },
  "output_config": { "effort": "xhigh" }
}
Enter fullscreen mode Exit fullscreen mode

عند تعطيل التفكير، يجب ألا يتجاوز effort القيمة high.

اختر أحد المسارين:

  • أبقِ التفكير مفعّلًا وخفّض effort للتحكم في التكلفة.
  • عطّل التفكير واستخدم effort: "high" كحد أقصى.

توصي Anthropic بالخيار الأول؛ فتعطيل التفكير قد يؤدي أحيانًا إلى ظهور استدعاءات أدوات كنص عادي أو تسريب وسوم <thinking> إلى المخرجات المرئية.

راجع دليل ترحيل النماذج للحصول على التفاصيل الرسمية.

الخطوة 1: إنشاء مفتاح API

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

لا تضع المفتاح في الكود. استخدم متغير بيئة:

export ANTHROPIC_API_KEY="sk-ant-..."
Enter fullscreen mode Exit fullscreen mode

في Apidog، أنشئ بيئات مثل local وstaging وproduction، ثم عرّف متغيرًا باسم ANTHROPIC_API_KEY واستخدمه في الترويسة:

x-api-key: {{ANTHROPIC_API_KEY}}
Enter fullscreen mode Exit fullscreen mode

بهذا تبقى الطلبات المحفوظة قابلة للمشاركة دون تضمين السر في تصدير المجموعة.

إعداد متغير البيئة في Apidog

تحتاج أيضًا إلى رصيد فواتير قبل نجاح الطلبات. يبلغ سعر Opus 5:

  • 5 دولارات لكل مليون رمز إدخال.
  • 25 دولارًا لكل مليون رمز إخراج.

راجع تفصيل أسعار Opus 5 لمعدلات التخزين المؤقت والدُفعات والوضع السريع.

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

استخدم نقطة النهاية التالية:

POST https://api.anthropic.com/v1/messages
Enter fullscreen mode Exit fullscreen mode

تحتاج إلى ثلاث ترويسات:

  • x-api-key
  • anthropic-version
  • content-type

مثال باستخدام curl:

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."
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

استخدمنا max_tokens: 4096 بدلًا من 1024 لأن التفكير يستهلك من الميزانية نفسها.

مثال Python باستخدام 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)
Enter fullscreen mode Exit fullscreen mode

لا تفترض أن message.content[0].text هي الإجابة. content مصفوفة من كتل مكتوبة، وقد تأتي كتلة thinking قبل كتلة text.

استخدم التصفية حسب النوع دائمًا:

text_blocks = [
    block.text
    for block in message.content
    if block.type == "text"
]

answer = "\n".join(text_blocks)
Enter fullscreen mode Exit fullscreen mode

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

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

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

اتبع هذه القواعد في التطبيق:

  1. حلّل الكتل حسب النوع.

    استخدم block.type == "text" للإجابة المرئية، وblock.type == "thinking" عند الحاجة إلى التسجيل أو المراقبة.

  2. أعد كتل التفكير كما هي في المحادثات متعددة الجولات.

    عند متابعة محادثة أو تنفيذ أدوات، مرّر محتوى المساعد كاملًا بدل إعادة بنائه كنص.

  3. راقب الاقتطاع.

    التفكير والإجابة يتشاركان max_tokens. إذا ظهر:

   {
     "stop_reason": "max_tokens"
   }
Enter fullscreen mode Exit fullscreen mode

فارفع max_tokens.

لتعطيل التفكير:

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

لا ترفع effort إلى xhigh أو max في هذا الوضع.

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

يقبل output_config.effort القيم التالية:

low
medium
high
xhigh
max
Enter fullscreen mode Exit fullscreen mode

القيمة الافتراضية هي high.

مثال لطلب عالي الجهد:

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."
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

قبل اختيار مستوى الجهد، ضع هذه النقاط في الاعتبار:

  • لا تنقل إعدادات Opus 4.8 كما هي.

    تمت إعادة معايرة المستويات، وlow وmedium أقوى في Opus 5 مقارنة بنماذج Opus السابقة.

  • ابدأ بـ xhigh للبرمجة والعمل الوكيلي.

    امنح الطلب ميزانية مناسبة، مثل 65536 للمنعطفات الوكيلة الطويلة.

  • خفض الجهد لا يعني بالضرورة مخرجات أقصر.

    يخفض الجهد الاستدلال الداخلي، وليس طول النص الظاهر. اطلب صراحةً إجابة مختصرة إذا كان ذلك مطلوبًا.

لمنهجية اختبار المستويات، راجع الدليل المتعمق لمعلمة الجهد.

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

أضف:

{
  "stream": true
}
Enter fullscreen mode Exit fullscreen mode

ستعيد نقطة النهاية أحداث SSE بدل جسم JSON واحد.

مثال Python:

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)
Enter fullscreen mode Exit fullscreen mode

التسلسل الخام لأحداث SSE هو:

message_start
content_block_start
content_block_delta
content_block_stop
message_delta
message_stop
Enter fullscreen mode Exit fullscreen mode

مع التفكير المفعّل، قد تصل كتلة thinking بدالات thinking_delta قبل كتلة النص ذات text_delta.

لا تضع كل الدالات في مخزن عرض واحد. افصل مسار التفكير عن النص المرئي حتى لا تعرض الاستدلال الداخلي للمستخدم النهائي.

يمكنك استخدام Apidog لمشاهدة أحداث SSE فور وصولها والتحقق من حدود الكتل قبل كتابة معالج الدفق في تطبيقك.

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

أضف تعريفات الأدوات ضمن tools. عندما يحتاج النموذج أداة، تحصل على:

{
  "stop_reason": "tool_use"
}
Enter fullscreen mode Exit fullscreen mode

وتظهر كتلة محتوى من النوع 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(
        block for block in message.content
        if block.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
                    }
                ]
            },
        ],
    )
Enter fullscreen mode Exit fullscreen mode

السطر المهم هو:

{"role": "assistant", "content": message.content}
Enter fullscreen mode Exit fullscreen mode

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

تفاصيل إضافية لوكلاء الأدوات:

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

الخطوة 7: تحقق من التخزين المؤقت عبر usage

تحتوي كل استجابة على كائن usage:

{
  "input_tokens": 84,
  "cache_creation_input_tokens": 6421,
  "cache_read_input_tokens": 0,
  "output_tokens": 913
}
Enter fullscreen mode Exit fullscreen mode

لتخزين محتوى ثابت مؤقتًا، أضف 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."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

تحقق من السلوك عبر طلبين متطابقين في البادئة:

الطلب cache_creation_input_tokens cache_read_input_tokens
الأول أكبر من 0 0
الثاني ينخفض أو يصبح 0 أكبر من 0

إذا لم تظهر قراءة من الذاكرة المؤقتة، فتحقق من أن البادئة متطابقة بايتًا وأنها تجاوزت الحد الأدنى.

في Opus 5 يبدأ التخزين المؤقت عند 512 رمزًا بدل 1024 في Opus 4.8. وتبلغ تكلفة قراءة الذاكرة المؤقتة 0.50 دولار لكل مليون رمز، مقابل 5 دولارات لمليون رمز إدخال أساسي.

أضف اختبارًا صريحًا في CI أو اختبارات التكامل:

assert response.usage.cache_read_input_tokens > 0
Enter fullscreen mode Exit fullscreen mode

على الطلبات المتكررة التي تتوقع فيها إصابة ذاكرة التخزين المؤقت. راجع دليل خفض فاتورة Claude API لمزيد من الأدوات.

اختبر التدفق كاملًا في Apidog

كل ما سبق عبارة عن طلب HTTP يتكون من:

  • ترويسات مصادقة.
  • جسم JSON.
  • تدفق SSE اختياري.
  • استجابة يجب التحقق منها.

Apidog يرسل ويفحص ويختبر طلبات API، لكنه لا يشغّل الاستدلال أو يوجّه النموذج؛ الطلب يظل متجهًا إلى Anthropic.

اختبار طلب Claude API في Apidog

إعداد عملي للفريق:

  1. أنشئ طلبًا واحدًا موثوقًا.

    أضف POST https://api.anthropic.com/v1/messages والترويسات الثلاثة، واستخدم متغير بيئة للمفتاح.

  2. احفظه في مجموعة.

    تجنّب إعادة بناء كل مطور للطلب من مقتطف مختلف.

  3. أنشئ نسخة لكل مستوى جهد.

    اختبر low وmedium وhigh وxhigh على الموجه نفسه، ثم قارن الجودة ووقت الاستجابة واستهلاك الرموز.

  4. اختبر SSE.

    فعّل "stream": true وتأكد أن التطبيق يفصل thinking_delta عن text_delta.

  5. افحص استدعاءات الأدوات.

    عندما تحصل على tool_use، راجع كائن input الناتج للتحقق من أن input_schema صارم بما يكفي.

  6. أضف تحققًا للاستجابة.

    تأكد من أن stop_reason ليس max_tokens، وتحقق من cache_read_input_tokens في الطلبات المتكررة.

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

أخطاء ومشكلات شائعة

  • خطأ 400 عند استخدام thinking: disabled مع xhigh أو max.

    خفّض الجهد إلى high أو أعد تفعيل التفكير.

  • خطأ 400 عند تعيين معلمات أخذ العينات بقيم غير افتراضية.

    ما زالت temperature وtop_p وtop_k تعيد 400 عند استخدام قيم غير افتراضية. وجّه السلوك عبر موجه النظام بدلًا من ذلك.

  • إجابات مقتطعة.

    إذا كان stop_reason: "max_tokens"، فارفع max_tokens.

  • Priority Tier غير مدعوم في Opus 5.

    يظل متاحًا في Opus 4.8، لذا تحقق من أثر ذلك قبل تحويل حركة المرور في بيئة تعتمد عليه.

  • رسائل النظام في منتصف المحادثة.

    يقبل Opus 5 إدخال role: "system" ضمن messages، بينما كان Opus 4.8 يعيد 400.

  • تعليمات التحقق الزائدة.

    يتحقق Opus 5 من عمله تلقائيًا. إزالة تعليمات مثل “تحقق مرة أخرى من إجابتك” قد تقلل رموز التفكير غير الضرورية.

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

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

كما يتأخر Opus 5 عن Mythos 5 في استغلال الأمن السيبراني وأبحاث البيولوجيا الذاتية، وفق ما ذكرته Anthropic.

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

راجع مقارنة Opus 5 مقابل Fable 5 ومنشور إطلاق Anthropic.

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

ما معرّف نموذج Claude Opus 5؟ 

claude-opus-5
Enter fullscreen mode Exit fullscreen mode

بدون لاحقة تاريخ. على Amazon Bedrock يكون:

anthropic.claude-opus-5
Enter fullscreen mode Exit fullscreen mode

بينما تستخدم Google Cloud ومنصة Claude على AWS معرّف الطرف الأول.

لماذا بدأت طلبات Opus 4.8 القديمة بالاقتطاع في Opus 5؟

لأن التفكير مفعّل افتراضيًا، وmax_tokens يغطي التفكير والإجابة معًا. ارفع max_tokens وتحقق من:

{
  "stop_reason": "max_tokens"
}
Enter fullscreen mode Exit fullscreen mode

لماذا أحصل على 400 عند تعطيل التفكير؟

غالبًا لأنك استخدمت:

{
  "thinking": { "type": "disabled" },
  "output_config": { "effort": "xhigh" }
}
Enter fullscreen mode Exit fullscreen mode

استخدم high كحد أقصى عند تعطيل التفكير، أو فعّل التفكير وخفّض الجهد.

هل أحتاج إلى ترويسة تجريبية لسياق 1M؟

لا. في Opus 5، نافذة 1M رمز هي القيمة الافتراضية والحد الأقصى، دون ترويسة تجريبية أو تكلفة إضافية للسياق الطويل.

تحتاج إلى الترويسة التجريبية:

output-300k-2026-03-24
Enter fullscreen mode Exit fullscreen mode

للوصول إلى 300 ألف رمز إخراج عبر Batch API. أما Messages API فيحد الإخراج بـ128 ألف رمز.

هل يمكنني إعادة استخدام إعدادات جهد Opus 4.8؟

لا يُنصح بذلك. تمت إعادة معايرة المستويات؛ نفّذ مسحًا جديدًا على مجموعة تقييماتك.

هل يشغّل Apidog النموذج؟

لا. يقوم Apidog بإرسال وفحص واختبار طلب HTTP، بينما يحدث الاستدلال على جانب Anthropic. يساعدك في إدارة المفاتيح، ومراقبة SSE، وفحص استدعاءات الأدوات، والتحقق من الاستجابات.

Top comments (0)