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

ملخص

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

جرّب Apidog اليوم

مقدمة

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

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

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

البدء

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

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

الرؤوس المطلوبة:

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. يجب تفعيله يدويًا.

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16384,
    thinking={
        "type": "adaptive",
        "display": "summarized"  # اختياري: لعرض التفكير في الاستجابة
    },
    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.
• "display": "summarized" يجعل التفكير مرئيًا في الاستجابة.
• يمكن دمج معلمة effort للتحكم في العمق.

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

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..."}
    ]
)

مستويات الجهد:

المستوى	الأفضل لـ
xhigh	الترميز، المهام الوكيلية، التفكير المعقد
high	الأعمال الحساسة للذكاء
medium	توازن بين السرعة والجودة
low	المهام البسيطة، الاستجابات السريعة

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

Opus 4.7 يدعم صور حتى 3.75 ميجابكسل (أقصى طول للحافة 2576 بكسل).

تحليل صورة من عنوان 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?"
                }
            ]
        }
    ]
)

نصيحة: الصور عالية الدقة تستهلك رموزًا أكثر. لتقليل التكلفة، قلل حجم الصور قبل الإرسال إذا لم تكن بحاجة للدقة الكاملة.

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

تمكين Claude من استدعاء وظائفك الخاصة.

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?"}
]

# الطلب الأول — Claude يطلب أداة
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=tools,
    messages=messages,
)

# معالجة استدعاء الأداة
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":
            # نفذ الوظيفة هنا
            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})

    # الطلب الثاني — Claude يستخدم نتيجة الأداة
    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})

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

خصص ميزانية رموز كاملة لدورة وكيلية.

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 رمز
• الميزانية إرشادية وليست سقفًا صارمًا
• تختلف عن max_tokens
• يتطلب رأس (header) تجريبي

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

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

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" ستبث كتل التفكير أولاً، ثم النص. بدونها، يظهر النص بعد وقفة.

التخزين المؤقت للموجهات (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)"}
    ]
)

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

العملية	التكلفة
كتابة ذاكرة تخزين مؤقت 5 دقائق	$6.25 / MTok (1.25x)
كتابة ساعة	$10 / MTok (2x)
قراءة/إصابة ذاكرة التخزين	$0.50 / MTok (0.1x)

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

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

حافظ على السياق عبر إضافة الرسائل في مصفوفة.

messages = []

# المحادثة الأولى
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})

# المحادثة الثانية
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 API يتطلب إدارة حمولات معقدة (رسائل متعددة، أدوات، صور Base64، استجابات متدفقة). أداة مثل Apidog تسهل عملية الاختبار والتصحيح.

إعداد البيئة:

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

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

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

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

• نفّذ نفس الموجهات على claude-opus-4-6 وclaude-opus-4-7 لمقارنة الرموز، جودة ووقت الاستجابة. استخدم Apidog test runner لمقارنات A/B.

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

• حدد مخططات JSON للاستجابة المتوقعة ودع Apidog يتحقق تلقائيًا من المطابقة.

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

الخطأ	السبب	الإصلاح
400: thinking.budget_tokens غير مدعوم	استخدام صيغة التفكير الموسع	استخدم thinking: {"type": "adaptive"}
400: temperature غير مدعوم	تعيين معلمات أخذ عينات	أزل temperature، top_p، top_k
400: max_tokens تجاوز الحد	برنامج ترميز جديد	زد max_tokens (حتى 128,000)
429: تجاوز معدل الطلبات	طلبات كثيرة	استخدم تراجع أسي، تحقق من حدود مستواك
كتل تفكير فارغة	العرض الافتراضي للتفكير "omitted"	أضف display: "summarized"

مرجع التسعير

الاستخدام	التكلفة
رموز الإدخال	$5 / MTok
رموز الإخراج	$25 / MTok
الإدخال المجمع	$2.50 / MTok
الإخراج المجمع	$12.50 / MTok
قراءة التخزين المؤقت	$0.50 / MTok
كتابة التخزين المؤقت 5د	$6.25 / MTok
كتابة التخزين المؤقت 1س	$10 / MTok

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

الخلاصة

Claude Opus 4.7 هو الأقوى في عائلة Claude. واجهة الـ API مشابهة لـ Opus 4.6 لكن بدون ميزانيات التفكير الموسعة أو معلمات أخذ العينات. استغل الإمكانيات الجديدة (التفكير التكيفي، جهد xhigh، ميزانيات المهام، الرؤية عالية الدقة) للتحكم في التكلفة والأداء.

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