DEV Community

Cover image for كيف تستخدم Claude Sonnet 5 API خطوة بخطوة مع Apidog
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيف تستخدم Claude Sonnet 5 API خطوة بخطوة مع Apidog

تم إصدار Claude Sonnet 5 في 30 يونيو 2026، وهو أكثر نماذج Sonnet ذات القدرة الوكيلة التي أطلقتها Anthropic. يقترب أداؤه من Opus 4.8 في مهام استخدام الأدوات والبرمجة، وبسعر أقل بكثير، لذلك يصلح كخيار افتراضي للمهام التي تستدعي الأدوات داخل حلقة تكرارية. في هذا الدليل ستتعلم عمليًا كيفية استدعاء واجهة برمجة تطبيقات Claude Sonnet 5: إنشاء المفتاح، إرسال أول طلب عبر curl وPython، قراءة الاستجابة، التعامل مع التفكير التكيفي، تجنب أخطاء 400 الشائعة، تفعيل التدفق، وعدّ الرموز باستخدام المُجزئ الجديد.

جرّب Apidog اليوم

ستقوم أيضًا بإعداد الطلبات داخل Apidog بدلًا من تركها موزعة بين أوامر curl وسجل الطرفية. بهذه الطريقة تحصل على مجموعة قابلة لإعادة الاستخدام، بيئات محفوظة، واختبارات تلقائية. إذا استخدمت Messages API سابقًا، فستبدو البنية مألوفة: معرف النموذج هو claude-sonnet-5، وشكل الطلب هو نفسه تقريبًا.

ما تحتاجه قبل البدء

قبل إرسال أول طلب، جهّز العناصر التالية:

  • حساب Anthropic ومفتاح API من لوحة تحكم منصة Claude.
  • معرف النموذج: claude-sonnet-5.
  • أداة لإرسال طلبات HTTP مثل curl للاختبار السريع، أو Apidog لتنظيم الطلبات وإعادة استخدامها.

Claude Sonnet 5 API

يتوفر Sonnet 5 لجميع عملاء واجهة برمجة التطبيقات، وكذلك عبر Amazon Bedrock من خلال منصة Claude على AWS، وGoogle Cloud عبر Vertex AI، وMicrosoft Foundry في معاينة. يستخدم هذا الدليل واجهة Anthropic المباشرة. نص الطلب يبقى نفسه غالبًا؛ الذي يتغير بين المنصات هو المصادقة ومضيف نقطة النهاية.

1. أنشئ مفتاح API

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

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

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

إذا كنت تستخدم اتفاقية ZDR، فإن Sonnet 5 يدعم الاحتفاظ بالبيانات لمدة صفرية، ولا تحتاج إلى تغيير في طريقة استدعاء API.

إرسال أول طلب إلى Sonnet 5

تستخدم Sonnet 5 نقطة نهاية Messages من Anthropic.

باستخدام 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-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Write a haiku about API testing."}
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

أهم الحقول هنا:

  • model: يحدد النموذج، وهنا claude-sonnet-5.
  • max_tokens: يحدد الحد الأقصى لإجمالي المخرجات.

انتبه: في Sonnet 5، قد تتضمن المخرجات رموز التفكير التكيفي بالإضافة إلى النص النهائي، لذلك قد تحتاج إلى رفع max_tokens مقارنةً بما كنت تستخدمه مع Sonnet 4.6.

باستخدام Python SDK 

import os
from anthropic import Anthropic

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

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Write a haiku about API testing."}
    ],
)

print(message.content[0].text)
Enter fullscreen mode Exit fullscreen mode

قراءة استجابة API

استدعاء ناجح يعيد HTTP 200 مع JSON مشابه لهذا:

{
  "id": "msg_01ABC...",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5",
  "content": [
    {
      "type": "text",
      "text": "Assertions green,\nendpoints answer on the first try,\nship the merge tonight."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 18,
    "output_tokens": 27
  }
}
Enter fullscreen mode Exit fullscreen mode

تعامل مع الحقول بهذه الطريقة:

  • content: مصفوفة من الكتل. لا تفترض دائمًا أن content[0] هو النص النهائي، خصوصًا عند استخدام الأدوات أو التفكير. مرّ على العناصر وابحث عن الكتل التي يكون type فيها هو "text".
  • stop_reason: يوضح سبب انتهاء التوليد. القيمة end_turn طبيعية. القيمة max_tokens تعني أن الإخراج اقتُطع. القيمة refusal تعني أن النموذج رفض الطلب.
  • usage: يحتوي على input_tokens وoutput_tokens، وهي الأرقام المهمة للفوترة والمراقبة.

مثال عملي لاستخراج النص بأمان في Python:

texts = []

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

final_text = "\n".join(texts)
print(final_text)
Enter fullscreen mode Exit fullscreen mode

التعامل مع stop_reason: "refusal"

يحتوي Sonnet 5 على حماية أمن سيبراني في الوقت الفعلي. إذا كان الطلب يتناول موضوعًا سيبرانيًا محظورًا أو عالي المخاطر، فقد يرفض النموذج.

المهم: الرفض ليس خطأ HTTP. ستحصل غالبًا على HTTP 200 مع:

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

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

مثال:

if message.stop_reason == "refusal":
    print("تم رفض الطلب من قبل النموذج.")
elif message.stop_reason == "max_tokens":
    print("تم اقتطاع الإخراج. ارفع max_tokens.")
elif message.stop_reason == "end_turn":
    print("اكتملت الاستجابة بنجاح.")
Enter fullscreen mode Exit fullscreen mode

التفكير التكيفي مفعل افتراضيًا

هذا هو التغيير السلوكي الأهم مقارنةً بـ Sonnet 4.6.

في Sonnet 4.6، عدم إرسال الحقل thinking كان يعني عدم استخدام التفكير. في Sonnet 5، التفكير التكيفي مفعل افتراضيًا عند عدم تحديد الحقل.

هذا يؤثر مباشرة على max_tokens، لأن الحد يشمل:

  • رموز التفكير.
  • نص الاستجابة النهائي.

إذا كان لديك طلب قديم يعمل بقيمة max_tokens منخفضة، فقد يبدأ في الاقتطاع بعد الترحيل إلى Sonnet 5.

إيقاف التفكير بالكامل

إذا كنت تريد إجابة مباشرة بدون تفكير تكيفي:

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    thinking={"type": "disabled"},
    messages=[
        {"role": "user", "content": "Return only the JSON, no reasoning."}
    ],
)
Enter fullscreen mode Exit fullscreen mode

استخدام التفكير التكيفي

لإبقاء التفكير التكيفي مفعّلًا، استخدم نوع التفكير التكيفي بدل ميزانية الرموز اليدوية:

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    thinking={
        "type": "adaptive",
        "effort": "medium"
    },
    messages=[
        {"role": "user", "content": "Design a retry strategy for a public API client."}
    ],
)
Enter fullscreen mode Exit fullscreen mode

تدعم قيمة الجهد effort القيم التالية:

  • low
  • medium
  • high
  • xhigh

كلما ارتفع الجهد، زاد التفكير واستهلاك الرموز. توثق Anthropic هذا في صفحة التفكير التكيفي.

ثلاثة تغييرات قد تسبب خطأ 400

إذا كنت تنقل كودًا من Sonnet 4.6 أو من نموذج Claude أقدم، راجع هذه النقاط قبل التشغيل.

1. إزالة التفكير الموسع اليدوي

هذا النمط لم يعد مدعومًا:

{
  "thinking": {
    "type": "enabled",
    "budget_tokens": 2000
  }
}
Enter fullscreen mode Exit fullscreen mode

سيؤدي إلى خطأ 400. استخدم التفكير التكيفي بدلًا منه:

{
  "thinking": {
    "type": "adaptive",
    "effort": "medium"
  }
}
Enter fullscreen mode Exit fullscreen mode

أو عطّله:

{
  "thinking": {
    "type": "disabled"
  }
}
Enter fullscreen mode Exit fullscreen mode

2. إزالة معلمات أخذ العينات غير الافتراضية

إرسال قيم غير افتراضية لهذه الحقول يؤدي إلى خطأ 400:

  • temperature
  • top_p
  • top_k

بدلًا من ضبطها، وجّه النموذج عبر تعليمات النظام أو نص الطلب.

مثال:

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": "أجب بإيجاز وبصيغة JSON صالحة فقط.",
  "messages": [
    {
      "role": "user",
      "content": "لخص حالة الطلب."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

3. لا تستخدم التعبئة المسبقة لرسالة المساعد

التعبئة المسبقة لبداية رد المساعد لم تعد مدعومة وتُرجع 400. استخدم بدلًا منها:

  • تعليمات النظام.
  • المخرجات المنظمة.
  • output_config.format عند الحاجة.

كل ما عدا ذلك من شكل الطلب والاستجابة والتدفق يبقى مطابقًا تقريبًا لما كان في Sonnet 4.6. لمزيد من سياق الترحيل، راجع دليل واجهة برمجة تطبيقات Claude Sonnet 4.6.

استخدام التدفق للمخرجات الكبيرة

يدعم Sonnet 5 حتى 128,000 رمز للمخرجات. عند توليد نصوص طويلة أو عند استخدام التفكير التكيفي مع مخرجات كبيرة، استخدم التدفق حتى تبدأ في استقبال الرموز فور إنشائها بدل انتظار الاستجابة الكاملة.

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=8000,
    messages=[
        {
            "role": "user",
            "content": "Draft an OpenAPI 3.1 spec for a bookstore checkout API."
        }
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
Enter fullscreen mode Exit fullscreen mode

شكل أحداث التدفق مطابق لما كان في Sonnet 4.6، لذلك يمكن لمعالجات التدفق الحالية أن تعمل بدون تعديل.

عدّ الرموز باستخدام المُجزئ الجديد

يستخدم Sonnet 5 مُجزئًا جديدًا. لنفس النص، قد تحصل تقريبًا على رموز أكثر بنسبة 30% مقارنةً بـ Sonnet 4.6.

هذا لا يغير شكل API، لكنه يؤثر على:

  • ميزانية max_tokens.
  • تكلفة الطلبات.
  • حدود السياق.
  • نتائج usage.
  • أي منطق داخلي يعتمد على حساب الرموز.

استخدم نقطة نهاية عد الرموز قبل إرسال الطلبات الكبيرة:

count = client.messages.count_tokens(
    model="claude-sonnet-5",
    messages=[
        {
            "role": "user",
            "content": "Estimate the tokens for this prompt on Sonnet 5."
        }
    ],
)

print(count.input_tokens)
Enter fullscreen mode Exit fullscreen mode

نصائح عملية:

  • لا تستخدم أرقام Sonnet 4.6 لتقدير Sonnet 5.
  • ارفع max_tokens إذا لاحظت stop_reason: "max_tokens".
  • أعد حساب تكلفة أعباء العمل الحقيقية بدل افتراض أن التكلفة ستبقى نفسها.
  • راقب usage.input_tokens وusage.output_tokens في السجلات.

للتفاصيل، راجع توثيق Anthropic حول عد الرموز المميزة.

الأخطاء، حدود المعدل، والتكلفة

تعامل مع رموز HTTP كالتالي:

  • 400: طلب غير صالح. غالبًا بسبب التفكير اليدوي القديم، معلمات sampling، أو التعبئة المسبقة للمساعد.
  • 401: مفتاح API مفقود أو غير صحيح.
  • 429: تجاوزت حد المعدل. اقرأ الرأس retry-after وانتظر قبل إعادة المحاولة.
  • 200 مع stop_reason: "refusal": رفض من النموذج، وليس خطأ HTTP.

مثال بسيط لإعادة المحاولة عند 429 فقط:

import time
import requests

response = requests.post(url, headers=headers, json=payload)

if response.status_code == 429:
    retry_after = int(response.headers.get("retry-after", "5"))
    time.sleep(retry_after)
    response = requests.post(url, headers=headers, json=payload)
Enter fullscreen mode Exit fullscreen mode

بالنسبة للتسعير، السعر التمهيدي هو:

  • 2 دولار لكل مليون رمز إدخال.
  • 10 دولارات لكل مليون رمز إخراج.

وذلك حتى 31 أغسطس 2026. بعد ذلك ينتقل السعر إلى:

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

رغم أن سعر الرمز الواحد يطابق Sonnet 4.6 بعد الفترة التمهيدية، فإن المُجزئ الجديد قد يجعل النص المكافئ يستهلك رموزًا أكثر. لذلك احسب التكلفة بناءً على count_tokens وusage بدل التقدير النظري.

للمزيد، راجع:

فئة Priority Tier غير متاحة في Sonnet 5.

اختبار وتنظيم استدعاءات Sonnet 5 في Apidog

بعد نجاح أول أمر curl، من الأفضل نقل الطلب إلى Apidog حتى تتمكن من حفظه، مشاركة الإعداد مع الفريق، وإضافة اختبارات تلقائية.

1. أنشئ طلب HTTP

أنشئ طلبًا جديدًا بهذه القيم:

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

أضف الرؤوس:

anthropic-version: 2023-06-01
content-type: application/json
x-api-key: {{ANTHROPIC_API_KEY}}
Enter fullscreen mode Exit fullscreen mode

ثم أضف جسم الطلب:

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Write a haiku about API testing."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

2. خزّن مفتاح API كمتغير بيئة

أنشئ بيئة مثل:

Anthropic Production
Enter fullscreen mode Exit fullscreen mode

ثم أضف المتغير:

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

واستخدمه في رأس الطلب:

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

بهذا الشكل لا تضع المفتاح داخل الطلب نفسه، ويمكنك تبديل البيئات بسهولة.

3. احفظ الطلبات في مجموعة

أنشئ مجموعة لطلبات Sonnet 5، مثل:

  • طلب رسالة عادي.
  • طلب مع thinking: disabled.
  • طلب مع thinking: adaptive.
  • طلب تدفق.
  • طلب استخدام أدوات.
  • طلب عد الرموز.

هذا يمنح الفريق مصدرًا واحدًا للطلبات بدل نسخ أوامر curl بين الملفات والمحادثات.

4. أضف اختبارات تلقائية

أضف تأكيدات تتحقق من الاستجابة في كل تشغيل. أمثلة عملية:

  • حالة الاستجابة هي 200.
  • الحقل model يساوي claude-sonnet-5.
  • الحقل stop_reason موجود.
  • الحقل stop_reason لا يساوي max_tokens.
  • الحقل usage.output_tokens أكبر من 0.

هذه الاختبارات مفيدة جدًا بعد الترحيل، لأن stop_reason: "max_tokens" قد يكشف أن التفكير التكيفي أو المُجزئ الجديد جعلا max_tokens غير كافٍ.

5. استخدم المحاكاة أثناء تطوير العميل

يمكنك استخدام المحاكاة الذكية في Apidog لإرجاع استجابة مشابهة لشكل Messages API، مما يسمح لك باختبار:

  • محلل الاستجابة.
  • منطق الأخطاء.
  • معالجة stop_reason.
  • واجهة المستخدم.
  • طبقة التكامل.

بهذا لا تحتاج إلى استهلاك رموز فعلية أثناء تطوير العميل أو اختبار الواجهة الأمامية.

إذا كنت تنتقل من Postman، راجع اختبار واجهة برمجة التطبيقات بدون Postman في عام 2026. وإذا كنت تفضل الطرفية، يشرح الدليل الكامل لـ Apidog CLI كيفية تشغيل نفس الاختبارات المحفوظة داخل مسار CI.

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

ما هو معرف نموذج Claude Sonnet 5؟

المعرف هو:

claude-sonnet-5
Enter fullscreen mode Exit fullscreen mode

استخدمه في حقل model داخل طلب Messages. في معظم حالات الترحيل من claude-sonnet-4-6 ستغير معرف النموذج فقط، ثم تراجع التفكير التكيفي، معلمات sampling، والتعبئة المسبقة للمساعد. للمزيد، اقرأ ما هو Claude Sonnet 5.

لماذا يتم اقتطاع الإخراج عند استخدام max_tokens؟

لأن التفكير التكيفي مفعل افتراضيًا في Sonnet 5، ورموز التفكير تُحتسب ضمن max_tokens. كذلك ينتج المُجزئ الجديد رموزًا أكثر لنفس النص. الحل هو رفع max_tokens أو تعطيل التفكير:

{
  "thinking": {
    "type": "disabled"
  }
}
Enter fullscreen mode Exit fullscreen mode

هل أحتاج إلى تعديل الكود عند الترحيل من Sonnet 4.6؟

نعم، في ثلاثة مواضع أساسية:

  1. أزل temperature وtop_p وtop_k إذا كانت غير افتراضية.
  2. أزل thinking: {type: "enabled", budget_tokens: N}.
  3. أزل التعبئة المسبقة لرسالة المساعد.

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

هل الرفض خطأ يجب إعادة المحاولة بعده؟

لا. الرفض يرجع HTTP 200 مع:

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

تعامل معه كاستجابة عادية، ولا تضعه في مسار retry.

كم تبلغ تكلفة واجهة برمجة تطبيقات Sonnet 5؟

حتى 31 أغسطس 2026:

  • 2 دولار لكل مليون رمز إدخال.
  • 10 دولارات لكل مليون رمز إخراج.

بعد ذلك:

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

لكن بسبب المُجزئ الجديد، قد يستهلك النص نفسه رموزًا أكثر من Sonnet 4.6، لذلك قِس التكلفة باستخدام count_tokens وusage بدل الاعتماد على التقدير السابق.

Top comments (0)