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

ملخص

Claude Opus 4.7 (claude-opus-4-7) هو نموذج Anthropic الأكثر قدرة والمتوفر بشكل عام. يدعم نافذة سياق بحجم 1M رمز (token)، و128K كحد أقصى للمخرجات، والتفكير التكيفي، ومستوى جهد xhigh جديد، وميزانيات للمهام، ورؤية عالية الدقة (3.75 ميجابكسل)، واستخدام الأدوات. يغطي هذا الدليل إعداد واجهة برمجة التطبيقات (API)، والمصادقة، وأمثلة التعليمات البرمجية العملية بلغات Python وTypeScript وcURL لكل قدرة رئيسية.

مقدمة

أصدرت Anthropic نموذج Claude Opus 4.7 في 16 أبريل 2026. إنه النموذج الأقوى في عائلة Claude والخيار المفضل للتفكير المعقد، والوكلاء المستقلين، وسير العمل الذي يعتمد بشكل كبير على الرؤية.

إذا كنت قد استخدمت واجهة برمجة تطبيقات Claude من قبل، فإن معظم الواجهة مألوفة. لكن Opus 4.7 يقدم العديد من الإمكانيات الجديدة والتغييرات الجذرية التي تتطلب تحديثات في التعليمات البرمجية. لقد اختفت ميزانيات التفكير الموسعة. لقد اختفت معلمات أخذ العينات (temperature، top_p، top_k). يدعم وضع التفكير الآن التفكير التكيفي فقط، وهو غير مفعل افتراضيًا.

يرشدك هذا الدليل خلال كل خطوة: الحصول على مفتاح واجهة برمجة التطبيقات (API key)، إجراء طلبك الأول، استخدام التفكير التكيفي، إرسال صور عالية الدقة، إعداد استخدام الأدوات، تهيئة ميزانيات المهام، وبث الاستجابات. كل مثال تم اختباره وجاهز للنسخ. ستتعلم أيضًا كيفية تصحيح الأخطاء واختبار استدعاءات واجهة برمجة التطبيقات الخاصة بك باستخدام Apidog، مما يجعل فحص محادثات استخدام الأدوات متعددة الأدوار أسهل بكثير من تحليل JSON الخام.

البدء

احصل على مفتاح واجهة برمجة التطبيقات الخاص بك

1. سجل الدخول في console.anthropic.com
2. انتقل إلى مفاتيح واجهة برمجة التطبيقات (API Keys) في لوحة التحكم
3. انقر على إنشاء مفتاح (Create Key) وانسخ المفتاح
4. قم بتخزينه كمتغير بيئة:

export ANTHROPIC_API_KEY="sk-ant-your-key-here"

تثبيت حزمة تطوير البرمجيات (SDK)

بايثون (Python):

pip install anthropic

تايب سكريبت/نود.جي إس (TypeScript/Node.js):

npm install @anthropic-ai/sdk

نقطة نهاية واجهة برمجة التطبيقات (API Endpoint)

تذهب جميع الطلبات إلى:

POST https://api.anthropic.com/v1/messages

الرؤوس المطلوبة (Required headers):

x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

طلب نصي أساسي

أبسط استدعاء لواجهة برمجة التطبيقات. أرسل رسالة، احصل على رد.

بايثون (Python):

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explain how HTTP/2 server push works in three sentences."}
    ]
)

print(message.content[0].text)

تايب سكريبت (TypeScript):

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

const client = new Anthropic();

const message = await client.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "Explain how HTTP/2 server push works in three sentences." }
  ],
});

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

cURL:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-4-7",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Explain how HTTP/2 server push works in three sentences."}
    ]
  }'

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

التفكير التكيفي هو وضع التفكير الوحيد المدعوم في Opus 4.7. يتيح هذا الوضع لـ Claude تخصيص رموز التفكير ديناميكيًا بناءً على تعقيد المهمة. إنه غير مفعل افتراضيًا — يجب عليك تمكينه صراحةً.

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16384,
    thinking={
        "type": "adaptive",
        "display": "summarized"  # optional: see thinking output
    },
    messages=[
        {"role": "user", "content": "Analyze this algorithm's time complexity and suggest optimizations:\n\ndef find_pairs(arr, target):\n    result = []\n    for i in range(len(arr)):\n        for j in range(i+1, len(arr)):\n            if arr[i] + arr[j] == target:\n                result.append((arr[i], arr[j]))\n    return result"}
    ]
)

for block in message.content:
    if block.type == "thinking":
        print("Thinking:", block.thinking)
    elif block.type == "text":
        print("Response:", block.text)

نقاط رئيسية:

• "type": "adaptive" يُفعّل التفكير. لا تقم بتعيين budget_tokens — فهذا يُرجع خطأ 400 الآن.
• "display": "summarized" يجعل محتوى التفكير مرئيًا في الاستجابة. الافتراضي هو "omitted".
• اجمع مع معلمة effort للتحكم في عمق التفكير.

استخدام معلمة الجهد (Effort Parameter)

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16384,
    thinking={"type": "adaptive"},
    output_config={"effort": "xhigh"},  # xhigh | high | medium | low
    messages=[
        {"role": "user", "content": "Review this pull request for security vulnerabilities..."}
    ]
)

مستويات الجهد لـ Opus 4.7:

الرؤية عالية الدقة

يقبل Opus 4.7 صورًا تصل إلى 2,576 بكسل على الحافة الطويلة (3.75 ميجابكسل). تتوافق الإحداثيات بنسبة 1:1 مع البكسلات الفعلية.

بايثون — تحليل صورة من عنوان URL:

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://example.com/architecture-diagram.png"
                    }
                },
                {
                    "type": "text",
                    "text": "Describe this architecture diagram. List every service and the connections between them."
                }
            ]
        }
    ]
)

print(message.content[0].text)

بايثون — تحليل صورة محلية باستخدام Base64:

import base64

with open("screenshot.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data
                    }
                },
                {
                    "type": "text",
                    "text": "What UI bugs do you see in this screenshot?"
                }
            ]
        }
    ]
)

تستهلك الصور عالية الدقة المزيد من الرموز (tokens). إذا لم تكن بحاجة إلى دقة كاملة، فقم بتغيير حجم الصور قبل إرسالها لتقليل التكاليف.

استخدام الأدوات (استدعاء الوظائف)

يتيح استخدام الأدوات لـ Claude استدعاء الوظائف التي تحددها. يميل Opus 4.7 إلى استخدام عدد أقل من استدعاءات الأدوات افتراضيًا، مفضلاً التفكير المنطقي. ارفع مستوى الجهد لزيادة استخدام الأدوات.

بايثون (Python):

import json

tools = [
    {
        "name": "get_weather",
        "description": "Get current weather for a city. Returns temperature, conditions, and humidity.",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "City name, e.g. 'San Francisco'"
                },
                "units": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "Temperature unit"
                }
            },
            "required": ["city"]
        }
    }
]

messages = [
    {"role": "user", "content": "What's the weather like in Tokyo right now?"}
]

# First call — Claude requests a tool
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=tools,
    messages=messages,
)

# Process tool calls
if response.stop_reason == "tool_use":
    messages.append({"role": "assistant", "content": response.content})

    tool_results = []
    for block in response.content:
        if block.type == "tool_use":
            # Execute your function here
            result = {"temperature": 22, "conditions": "Partly cloudy", "humidity": 65}

            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": json.dumps(result)
            })

    messages.append({"role": "user", "content": tool_results})

    # Second call — Claude uses the tool result
    final_response = client.messages.create(
        model="claude-opus-4-7",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )
    print(final_response.content[0].text)

نمط الحلقة الوكيلية (Agentic Loop)

للوكلائ المستقلين الذين يقومون بتشغيل استدعاءات أدوات متعددة بالتسلسل:

def run_agent(system_prompt: str, tools: list, user_message: str) -> str:
    messages = [{"role": "user", "content": user_message}]

    while True:
        response = client.messages.create(
            model="claude-opus-4-7",
            max_tokens=16384,
            system=system_prompt,
            tools=tools,
            thinking={"type": "adaptive"},
            output_config={"effort": "xhigh"},
            messages=messages,
        )

        messages.append({"role": "assistant", "content": response.content})

        if response.stop_reason != "tool_use":
            return "".join(
                block.text for block in response.content
                if hasattr(block, "text")
            )

        tool_results = []
        for block in response.content:
            if block.type == "tool_use":
                result = execute_tool(block.name, block.input)
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result,
                })

        messages.append({"role": "user", "content": tool_results})

ميزانيات المهام (تجريبي)

تمنح ميزانيات المهام Claude مخصصًا من الرموز (tokens) لدورة وكيلية كاملة. يرى النموذج عدًا تنازليًا مستمرًا وينجز العمل مع استهلاك الميزانية.

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=128000,
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 128000},
    },
    messages=[
        {"role": "user", "content": "Review the codebase and propose a refactor plan."}
    ],
    betas=["task-budgets-2026-03-13"],
)

القيود الرئيسية:

• الحد الأدنى للميزانية: 20,000 رمز (token)
• إرشادي، وليس سقفًا صارمًا — قد يتجاوز Claude الميزانية
• يختلف عن max_tokens (سقف صارم لا يمكن للنموذج رؤيته)
• يتطلب رأس (header) تجريبي task-budgets-2026-03-13

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

قم ببث الاستجابات للحصول على مخرجات في الوقت الفعلي في واجهات الدردشة.

بايثون (Python):

with client.messages.stream(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Write a Python function to parse CSV files with error handling."}
    ]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

تايب سكريبت (TypeScript):

const stream = await client.messages.stream({
  model: "claude-opus-4-7",
  max_tokens: 4096,
  messages: [
    { role: "user", content: "Write a Python function to parse CSV files with error handling." }
  ],
});

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

إذا قمت بتمكين التفكير التكيفي باستخدام display: "summarized"، يتم بث كتل التفكير أولاً، يليها الاستجابة النصية. بدون display: "summarized"، يرى المستخدمون وقفة أثناء التفكير يليها إخراج النص.

التخزين المؤقت للموجهات (Prompt Caching)

قلل التكاليف للسياق المتكرر (موجهات النظام، المستندات الطويلة) عن طريق تخزينها مؤقتًا.

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "You are a senior code reviewer. Review code for security vulnerabilities, performance issues, and best practices violations...",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {"role": "user", "content": "Review this function:\n\ndef process_user_input(data):\n    return eval(data)"}
    ]
)

تسعيرة التخزين المؤقت لـ Opus 4.7:

قراءة واحدة من ذاكرة التخزين المؤقت تغطي تكلفة كتابة ذاكرة التخزين المؤقت لمدة 5 دقائق. قراءتان تغطيان تكلفة كتابة الساعة الواحدة.

المحادثات متعددة الأدوار

حافظ على السياق عبر الأدوار عن طريق الإلحاق بمصفوفة الرسائل.

messages = []

# Turn 1
messages.append({"role": "user", "content": "I need to build a REST API for a todo app."})

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=messages,
)

messages.append({"role": "assistant", "content": response.content})

# Turn 2
messages.append({"role": "user", "content": "Add authentication with JWT tokens."})

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=messages,
)

اختبار استدعاءات واجهة برمجة التطبيقات الخاصة بك باستخدام Apidog

يتضمن بناء تكامل واجهة برمجة تطبيقات Claude حمولات معقدة: رسائل متعددة الأدوار، تعريفات الأدوات، نتائج الأدوات، صور Base64، واستجابات متدفقة. أداة مثل Apidog تبسط تصحيح الأخطاء والاختبار.

إعداد بيئتك:

1. أنشئ مشروعًا جديدًا في Apidog وأضف نقطة نهاية واجهة برمجة تطبيقات Claude Messages.
2. قم بتخزين ANTHROPIC_API_KEY الخاص بك في متغيرات البيئة.
3. قم بتعيين الرؤوس المطلوبة (x-api-key، anthropic-version، content-type).

اختبار تدفقات استخدام الأدوات:

يتيح لك Apidog ربط الطلبات، بحيث يمكنك محاكاة دورة كاملة لاستخدام الأدوات: إرسال الرسالة الأولية، فحص استدعاء أداة Claude، بناء نتيجة الأداة، وإعادتها. يوضح مفتش الطلبات/الاستجابات المرئي ما هو موجود بالضبط في كل حمولة.

مقارنة النماذج:

قم بتشغيل نفس الموجهات مقابل claude-opus-4-6 و claude-opus-4-7 لمقارنة أعداد الرموز، وجودة الاستجابة، ووقت الاستجابة. يجعل Apidog's test runner مقارنات A/B قابلة للتكرار.

التحقق من صحة المخططات (Schemas):

حدد مخططات JSON لتنسيق الاستجابة المتوقع ودع Apidog يتحقق تلقائيًا من تطابق استجابات Claude. هذا يلتقط التراجعات عند تغيير الموجهات أو تبديل النماذج.

الأخطاء الشائعة والإصلاحات

مرجع التسعير

ملاحظة: قد يستخدم برنامج ترميز Opus 4.7 الجديد ما يصل إلى 35% رموزًا أكثر لنفس النص مقارنةً بـ Opus 4.6. استخدم نقطة نهاية /v1/messages/count_tokens لتقدير التكاليف قبل النشر في الإنتاج.

الخلاصة

Claude Opus 4.7 هو النموذج الأكثر قدرة في عائلة Claude. تتوافق واجهة برمجة التطبيقات إلى حد كبير مع Opus 4.6، ولكن إزالة ميزانيات التفكير الموسعة ومعلمات أخذ العينات تتطلب تغييرات في التعليمات البرمجية. تمنحك الإمكانيات الجديدة — التفكير التكيفي، والجهد xhigh، وميزانيات المهام، والرؤية عالية الدقة — مزيدًا من التحكم في كيفية تفكير النموذج ومقدار تكلفته.

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