كيفية استخدام API كلاود أوبوس 4.8؟

تم إطلاق واجهة برمجة تطبيقات Claude Opus 4.8 مع إطلاق النموذج في 28 مايو 2026. معرف النموذج هو claude-opus-4-8، ويعمل عبر نفس Messages API التي تستخدمها مع نماذج Claude الأخرى. في هذا الدليل ستنفذ الإعداد عمليًا: إنشاء مفتاح API، إرسال أول طلب، ضبط effort، تفعيل التفكير التكيفي، استخدام البث، تعريف الأدوات، واختبار التكامل في Apidog.

جرّب Apidog اليوم

إذا كنت تستخدم Claude API بالفعل، فغالبًا ستغيّر قيمة model فقط. المفهوم الجديد الأهم هو التحكم في الجهد effort، لأنه يحل محل نمط “ميزانية التفكير” اليدوي القديم. إذا كنت جديدًا على Claude API، يمكنك تشغيل طلب Opus 4.8 خلال دقائق. لمعلومات عامة عن النموذج نفسه، راجع ما هو Claude Opus 4.8.

ما تحصل عليه مع واجهة برمجة تطبيقات Opus 4.8

القيم التي تهمك أثناء التكامل:

• claude-opus-4-8: سياق إدخال 1 مليون توكن، وإخراج 128 ألف توكن.
• نفس Messages API: مناسب كاستبدال مباشر للمشاريع التي تستخدم Opus 4.7.
• معلمة effort: خمسة مستويات من low إلى max لكل طلب.
• التفكير التكيفي: النموذج يقرر متى وكم يفكر.
• التسعير القياسي: 5 دولارات لكل مليون توكن إدخال، و25 دولارًا لكل مليون توكن إخراج.

لحساب التكلفة الكاملة وأسعار الوضع السريع، راجع دليل تسعير Opus 4.8. وإذا لم تكن لديك خطة مدفوعة بعد، يغطي دليل الوصول المجاني الخيارات المتاحة.

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

1. افتح console.anthropic.com.
2. سجّل الدخول أو أنشئ حسابًا.
3. انتقل إلى Settings ثم API Keys.
4. اضغط Create Key، اختر اسمًا للمفتاح، ثم انسخه.

احفظ المفتاح في متغير بيئة بدلًا من وضعه داخل الكود:

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

تستطيع الحسابات الجديدة استخدام أرصدة تجريبية للاختبار قبل إضافة معلومات الفوترة. يعمل المفتاح مع claude-opus-4-8 مباشرةً إذا كان الوصول متاحًا لحسابك.

الخطوة 2: تثبيت حزمة SDK

توفر Anthropic حزم SDK رسمية لعدة لغات، منها Python وTypeScript وGo وJava وC# وRuby وPHP.

Python

pip install anthropic

Node.js / TypeScript

npm install @anthropic-ai/sdk

يمكنك أيضًا استدعاء REST API مباشرةً باستخدام curl دون SDK. إذا احتجت إلى أنواع دقيقة أو تفاصيل تنفيذية، راجع مصدر Python SDK.

الخطوة 3: إرسال أول طلب إلى Opus 4.8

Python

import anthropic

client = anthropic.Anthropic()  # يقرأ ANTHROPIC_API_KEY من البيئة

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Explain the OAuth 2.0 PKCE flow in 3 short paragraphs."
        }
    ],
)

print(message.content[0].text)

Node.js

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const message = await client.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 4096,
  messages: [
    {
      role: "user",
      content: "Explain the OAuth 2.0 PKCE flow in 3 short paragraphs.",
    },
  ],
});

console.log(message.content[0].text);

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-4-8",
    "max_tokens": 4096,
    "messages": [
      {
        "role": "user",
        "content": "Explain the OAuth 2.0 PKCE flow in 3 short paragraphs."
      }
    ]
  }'

هذا هو الحد الأدنى لتشغيل النموذج. بعد ذلك أضف الميزات حسب احتياج التطبيق.

التحكم في الجهد: معلمة effort

تتحكم effort في مقدار العمل الذي ينفقه Opus 4.8 عبر الاستجابة: النص، استدعاءات الأدوات، والتفكير. توضع داخل output_config وتقبل القيم التالية:

• low
• medium
• high
• xhigh
• max

القيمة الافتراضية هي high، لذلك إذا لم تمررها فسيعمل الطلب بمستوى high.

Python

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=8192,
    messages=[
        {
            "role": "user",
            "content": "Refactor this 600-line module for testability."
        }
    ],
    output_config={"effort": "xhigh"},
)

Node.js

const message = await client.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 8192,
  messages: [
    {
      role: "user",
      content: "Refactor this 600-line module for testability.",
    },
  ],
  output_config: { effort: "xhigh" },
});

وفقًا إلى وثائق الجهد من Anthropic، اختر المستوى بهذه الطريقة:

المستوى	استخدمه لـ
low	التصنيف، البحث السريع، المهام عالية الحجم، والوكلاء الفرعيين
medium	العمل الوكيلي المتوازن عندما تكون التكلفة مهمة
high	الافتراضي؛ التفكير المعقد عندما تكون الجودة أهم من السرعة
xhigh	البرمجة والمهام الوكيلية طويلة المدى؛ نقطة بداية موصى بها
max	المشكلات المتقدمة جدًا بعد قياس مساحة العمل المطلوبة

قاعدتان عمليتان:

1. ابدأ من xhigh في مهام البرمجة والحلقات الوكيلية.
2. عند استخدام xhigh أو max، عيّن max_tokens إلى قيمة كبيرة. 64K نقطة بداية مناسبة حتى يكون لدى النموذج مساحة للتفكير واستخدام الأدوات.

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

يدعم Opus 4.8 التفكير التكيفي. مرر:

{
  "thinking": {
    "type": "adaptive"
  }
}

عندها يقرر النموذج متى يحتاج إلى التفكير وكم يخصص له. بدون هذا الإعداد، تعمل الطلبات بدون تفكير.

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "xhigh"},
    messages=[
        {
            "role": "user",
            "content": "Find the race condition in this scheduler."
        }
    ],
)

for block in message.content:
    if block.type == "thinking":
        print("[thinking]", block.thinking[:200])
    elif block.type == "text":
        print(block.text)

تنبيه مهم عند الترحيل: التفكير الموسع اليدوي باستخدام budget_tokens غير مدعوم في Opus 4.8، وسيعيد خطأ 400. إذا كنت تستخدمه مع Opus 4.5 أو أقدم، احذف budget_tokens واستخدم التفكير التكيفي مع effort.

بث الاستجابات

البث مناسب لواجهات المستخدم لأنه يعرض النص فور وصوله بدل انتظار اكتمال الاستجابة.

Python

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Write a 5-step guide to writing a REST client in Go."
        }
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Node.js

const stream = client.messages.stream({
  model: "claude-opus-4-8",
  max_tokens: 4096,
  messages: [
    {
      role: "user",
      content: "Write a 5-step guide to writing a REST client in Go.",
    },
  ],
});

for await (const event of stream) {
  if (
    event.type === "content_block_delta" &&
    event.delta.type === "text_delta"
  ) {
    process.stdout.write(event.delta.text);
  }
}

إذا كنت تستخدم REST مباشرةً، أضف "stream": true إلى جسم الطلب واقرأ Server-Sent Events.

استخدام الأدوات واستدعاء الدوال

يستطيع Opus 4.8 استدعاء الأدوات عبر تعريف input_schema. يحدد مستوى effort مقدار التخطيط وعدد الاستدعاءات التي قد يجريها النموذج.

مثال لتعريف أداة بسيطة للطقس:

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a city.",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "City name"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"]
                },
            },
            "required": ["city"],
        },
    }
]

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=tools,
    messages=[
        {
            "role": "user",
            "content": "What's the weather in Singapore right now?"
        }
    ],
)

for block in message.content:
    if block.type == "tool_use":
        print(f"Call: {block.name}")
        print(f"Args: {block.input}")

بعد ذلك:

1. شغّل الأداة محليًا في تطبيقك.
2. أضف نتيجة التنفيذ ككتلة tool_result.
3. أرسل طلبًا جديدًا إلى النموذج لإكمال الإجابة.

ملاحظة عملية: الجهد المنخفض يميل إلى تقليل عدد الاستدعاءات، بينما الجهد الأعلى قد يجعل النموذج يخطط ويفسر خطواته قبل التنفيذ. إذا كنت تبني أنظمة متعددة الوكلاء، راجع الوكلاء المدارون بواسطة كلود مقابل Agent SDK.

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

يتضمن Opus 4.8 تغييرًا في Messages API: يمكنك وضع رسالة نظام داخل مصفوفة messages في منتصف المحادثة، وليس فقط في البداية. هذا مفيد عندما تحتاج إلى حقن تعليمات أو أذونات جديدة أثناء تنفيذ مهمة طويلة.

هذا النمط هو أساس Claude Code’s Dynamic Workflows. إذا كنت تنسق وكلاء فرعيين عبر API، اقرأ التفاصيل العميقة لـ Dynamic Workflows.

اختبار تكامل Opus 4.8 باستخدام Apidog

تشغيل طلب SDK ناجح ليس كافيًا للإنتاج. تحتاج أيضًا إلى اختبار:

• أجزاء البث.
• شكل output_config.
• كتل التفكير التكيفي.
• استدعاءات الأدوات.
• أخطاء المصادقة والحدود.
• التغييرات بين مستويات effort.

يمكنك استخدام Apidog لاختبار Messages API في مساحة عمل واحدة:

• حفظ نقطة النهاية كطلب: استخدم https://api.anthropic.com/v1/messages وأضف رؤوس x-api-key وanthropic-version.
• إعادة التشغيل بين إصدارات النماذج: بدّل claude-opus-4-7 إلى claude-opus-4-8 وقارن المخرجات.
• اختبار البث: فعّل "stream": true وشاهد أجزاء SSE عند وصولها.
• التحقق من شكل الاستجابة: أضف assertions لاكتشاف تغيّر البنية عند تبديل effort أو thinking.
• محاكاة نقطة النهاية: أنشئ ردًا وهميًا لاختبار الكود اللاحق دون استهلاك أرصدة.
• بناء سيناريوهات وكلاء: اربط عدة طلبات مع تحقق من tool_use وtool_result.

للبدء، قم بتنزيل Apidog، أنشئ طلبًا إلى Messages API، ثم استورد مقتطف curl أعلاه. يمكن استخدام نفس أسلوب الاختبار مع واجهة برمجة تطبيقات Gemini 3.5 وواجهة برمجة تطبيقات Qwen 3.7 إذا كنت تدير أكثر من مزود.

معالجة الأخطاء وحدود المعدل

أهم رموز الأخطاء التي يجب التعامل معها:

• 400 invalid_request_error: جسم الطلب غير صحيح، مثل استخدام budget_tokens مع Opus 4.8 أو قيمة effort غير صالحة.
• 401 authentication_error: مفتاح API مفقود أو غير صحيح.
• 403 permission_error: المفتاح لا يملك صلاحية الوصول إلى النموذج.
• 429 rate_limit_error: تجاوز حدود المعدل؛ استخدم retry مع backoff.
• 500 api_error: خطأ من جهة الخادم؛ أعد المحاولة مع تراجع أسي.
• 529 overloaded_error: الخدمة محملة مؤقتًا؛ أعد المحاولة مع تراجع أسي.

مثال بسيط للتراجع الأسي في Python:

import time
import anthropic

client = anthropic.Anthropic()

def call_with_retry(prompt, max_retries=4):
    for attempt in range(max_retries):
        try:
            return client.messages.create(
                model="claude-opus-4-8",
                max_tokens=4096,
                messages=[
                    {
                        "role": "user",
                        "content": prompt
                    }
                ],
            )
        except anthropic.RateLimitError:
            if attempt == max_retries - 1:
                raise

            time.sleep(2 ** attempt)

تتغير حدود المعدل حسب مستوى استخدامك. للمهام الدفعية عالية الإنتاجية التي لا تتطلب زمن استجابة فوري، تتيح Batch API أيضًا ما يصل إلى 300 ألف توكن إخراج مع رأس beta.

الترحيل من Opus 4.7 إلى 4.8

في أغلب المشاريع، التغيير الأساسي هو اسم النموذج:

# قبل
model="claude-opus-4-7"

# بعد
model="claude-opus-4-8"

بعد التبديل، اختبر هذه النقاط:

1. مستويات effort: أعد تشغيل تقييماتك على المستوى الذي تستخدمه.
2. إعدادات التفكير: إذا كان لديك budget_tokens، احذفه واستخدم thinking: {"type": "adaptive"}.
3. مخططات الأدوات: أعد اختبار tool_use وtool_result.
4. التكلفة: أسعار التوكن مطابقة لـ 4.7، لذلك لا توجد مفاجأة في الفوترة من ناحية السعر لكل توكن.

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

ما هو معرف نموذج Claude Opus 4.8 في API؟

claude-opus-4-8 على Claude API وVertex AI، وanthropic.claude-opus-4-8 على AWS Bedrock.

هل يوجد مستوى مجاني لواجهة برمجة تطبيقات Opus 4.8؟

لا يوجد مستوى مجاني دائم للـ API، لكن الحسابات الجديدة تحصل على أرصدة تجريبية. راجع دليل الوصول المجاني لمسارات أخرى منخفضة التكلفة.

كيف أحدد مستوى الجهد؟

مرر output_config: {"effort": "xhigh"} أو استخدم low أو medium أو high أو max. القيمة الافتراضية هي high.

لماذا يعيد طلبي خطأ 400 بسبب budget_tokens؟

لأن Opus 4.8 لا يدعم التفكير الموسع اليدوي. احذف budget_tokens واستخدم thinking: {"type": "adaptive"} مع effort.

هل يعمل Opus 4.8 مع SDK المتوافق مع OpenAI؟

توفر Anthropic طبقة توافق مع OpenAI SDK. وجّه base_url إلى نقطة نهاية Anthropic، استخدم مفتاح Anthropic، واحتفظ باسم النموذج claude-opus-4-8.

ما قيمة max_tokens المناسبة للعمل الوكيلي؟

ابدأ بـ 64K عند استخدام xhigh أو max حتى يكون لدى النموذج مساحة للتفكير وربط استدعاءات الأدوات. بعد مراقبة الاستخدام الفعلي، خفّض القيمة حسب الحاجة.

كيف أختبر استجابات البث في Apidog؟

افتح الطلب، أضف "stream": true إلى الجسم، وسيعرض Apidog أجزاء Server-Sent Events عند وصولها، مما يساعدك على اكتشاف الاستجابات الناقصة أو المنقطعة.