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

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

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

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

تحتاج إلى ثلاثة أشياء لاستدعاء واجهة برمجة التطبيقات (API).

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

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

احصل على مفتاح API الخاص بك

سجّل الدخول إلى لوحة تحكم منصة Claude، افتح قسم مفاتيح API، وأنشئ مفتاحًا جديدًا. انسخه مرة واحدة وقم بتخزينه في مكان آمن، لأن لوحة التحكم لن تعرضه مرة أخرى. لا تقم أبدًا بتضمين المفتاح بشكل صريح في كود المصدر الخاص بك أو إضافته إلى Git. قم بتعيينه كمتغير بيئة بدلاً من ذلك:

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

إذا كنت مشتركًا في اتفاقية ZDR، فإن 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."}
    ]
  }'

الطلب نفسه باستخدام حزمة تطوير 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)

يقوم حقلان بالعمل الرئيسي. يحدد model Sonnet 5. يحدد max_tokens الحد الأقصى للإخراج الكلي. تابع القراءة، لأن max_tokens يتصرف بشكل مختلف في Sonnet 5 عما كان عليه في Sonnet 4.6، وهو أسهل شيء يمكن أن يخطئ فيه المرء.

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

يعيد الاستدعاء الناجح رمز 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
  }
}

تعد بعض الحقول مهمة للعمل الفعلي.

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

سبب التوقف "الرفض"

يعد Sonnet 5 أول نموذج من فئة Sonnet مزودًا بحماية أمن سيبراني في الوقت الفعلي. إذا لامس طلب موضوعًا سيبرانيًا محظورًا أو عالي المخاطر، فقد يرفض النموذج. يأتي الرفض كاستجابة HTTP 200 طبيعية مع stop_reason: "refusal"، وليس كخطأ. تعامل معه في كود تحليل الاستجابة الخاص بك بنفس الطريقة التي تتعامل بها مع أي سبب توقف غير end_turn، بدلاً من اعتباره استدعاء HTTP فاشلاً.

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

هذا هو أكبر تغيير سلوكي عن Sonnet 4.6، وهو يربك الناس. في Sonnet 4.6، عدم وجود حقل thinking كان يعني عدم وجود تفكير. في Sonnet 5، التفكير التكيفي مفعل افتراضيًا. الآن، أي طلب بدون حقل thinking يُنفّذ مع التفكير التكيفي، وتحسب رموز التفكير ضمن إجمالي مخرجاتك.

نظرًا لأن max_tokens هو حد أقصى صارم لإجمالي الإخراج (رموز التفكير بالإضافة إلى نص الاستجابة)، فإن قيمة max_tokens التي كانت مريحة في الإصدار 4.6 يمكنها الآن اقتطاع إجابتك المرئية قبل أن تكتمل. إذا قمت بترحيل عبء عمل لم يستخدم التفكير مطلقًا ووضعت حدًا ضيقًا لـ max_tokens، فقم بزيادته أو توقع الاقتطاع.

لإيقاف تشغيل التفكير بالكامل:

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

لإبقاء التفكير التكيفي مفعلًا والتحكم في مدى صعوبة عمل النموذج، استخدم معلمة الجهد (effort) بدلاً من محاولة تحديد ميزانية رمز يدوية. يدعم الجهد القيم low، medium، high، و xhigh. الجهد الأعلى يعني تفكيرًا أعمق ومزيدًا من استهلاك الرموز. توثق Anthropic هذا السلوك في صفحة التفكير التكيفي. لاحظ أن قيمة الحقل هي {"type": "adaptive"}، وليست رقم budget_tokens.

ثلاثة تغييرات في الطلب تُرجع خطأ 400

إذا كنت تقوم بنقل التعليمات البرمجية من Sonnet 4.6 أو نموذج Claude أقدم، فإن ثلاثة أشياء كانت تعمل سابقًا تُرجع الآن خطأ 400. قم بإصلاحها قبل الترحيل.

1. تمت إزالة التفكير الموسع اليدوي. thinking: {type: "enabled", budget_tokens: N} تُرجع 400. لقد كانت مهملة بالفعل في الإصدار 4.6. استخدم التفكير التكيفي بالإضافة إلى معلمة الجهد بدلاً من ذلك.
2. تم رفض معلمات أخذ العينات. تعيين temperature أو top_p أو top_k إلى قيمة غير افتراضية يُرجع 400. قم بإزالتها. إهمالها، أو تركها على قيمتها الافتراضية، أمر مقبول. وجه السلوك باستخدام تعليمات المطالبة النظامية بدلاً من ذلك. هذا القيد كان موجودًا بالفعل في Opus 4.7 وما فوق؛ وهو جديد لفئة Sonnet.
3. لا يدعم التعبئة المسبقة لرسالة المساعد. التعبئة المسبقة لبداية دور المساعد تُرجع 400. استخدم المخرجات المنظمة أو output_config.format أو تعليمات المطالبة النظامية لتشكيل الإخراج بدلاً من ذلك.

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

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

يدعم 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)

شكل حدث التدفق هو نفسه كما في Sonnet 4.6، لذا تعمل معالجات التدفق الحالية بدون تغيير.

عد الرموز المميزة باستخدام المُجزء الجديد

يستخدم Sonnet 5 مُجزئًا جديدًا. ينتج نفس النص المدخل حوالي 30% رموزًا أكثر مما كان عليه في Sonnet 4.6، أي حوالي 1.3 ضعف. هذا ليس تغييرًا في واجهة برمجة التطبيقات. أشكال الطلب والاستجابة والتدفق متطابقة، ولا تحتاج إلى تغيير أي تعليمات برمجية لذلك. لكنه يؤثر على أي شيء تقيسه أو تحدد ميزانيته بالرموز.

• أرقام usage ونتائج عد الرموز المميزة لديك أعلى لنفس النص. أعد العد مقابل Sonnet 5؛ لا تستخدم تعدادات 4.6.
• نافذة السياق التي تبلغ مليون رمز تحمل نصًا أقل في المتوسط، لأن كل رمز يغطي الآن نصًا أقل.
• قد يؤدي تعيين قيمة max_tokens قريبة من مخرجك المتوقع إلى الاقتطاع الآن. أعد النظر فيها.
• قد تكون تكلفة كل طلب لنص مكافئ أعلى على الرغم من أن سعر الرمز المميز لم يتغير.

استخدم نقطة نهاية عد الرموز المميزة قبل الإرسال، حتى تتمكن من وضع ميزانية بناءً على الأرقام الحقيقية لـ Sonnet 5:

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)

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

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

تنطبق دلالات HTTP القياسية. يشير الرمز 400 إلى طلب خاطئ (التغييرات الثلاثة المذكورة أعلاه هي المشتبه بهم المعتادون في Sonnet 5). يشير الرمز 401 إلى مفتاح API خاطئ أو مفقود. يشير الرمز 429 إلى أنك تجاوزت حد المعدل. اقرأ رأس retry-after وتراجع قبل إعادة المحاولة. تذكر أن الرفض هو 200، وليس خطأ، لذا لا توجهه عبر منطق إعادة المحاولة الخاص بك.

فيما يتعلق بالتسعير، السعر التمهيدي هو 2 دولار لكل مليون رمز إدخال و 10 دولارات لكل مليون رمز إخراج، ساري المفعول حتى 31 أغسطس 2026. بعد ذلك، ينتقل إلى السعر القياسي 3 دولارات لكل مليون رمز إدخال و 15 دولارًا لكل مليون رمز إخراج، وهو نفس سعر الرمز الواحد كما في Sonnet 4.6. بسبب تغيير المُجزء، قد تكون تكلفة طلب نص مكافئ لا تزال أعلى من Sonnet 4.6 على الرغم من أن سعر الرمز الواحد لم يتغير، لذا قم بنمذجة أعباء عملك الحقيقية باستخدام عد الرموز بدلاً من افتراض التكافؤ التام. للحصول على تفصيل أعمق للتكلفة، راجع تفاصيل تكلفة واجهة برمجة تطبيقات Claude ودليل حدود معدل واجهة برمجة تطبيقات Claude. فئة الأولوية (Priority Tier) غير متاحة في Sonnet 5.

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

بمجرد تجاوز أمر curl الأول، سترغب في حفظ طلباتك، وتخزين مفتاحك مرة واحدة، والتحقق من استجاباتك تلقائيًا. هنا يأتي دور Apidog. إنها منصة API شاملة، لذا يصبح نفس الطلب الذي ترسله يدويًا أصلًا قابلاً لإعادة الاستخدام والاختبار. قم بتنزيل Apidog للمتابعة.

إليك إعداد عملي لواجهة برمجة تطبيقات Sonnet 5.

1. إنشاء الطلب. أضف طلب HTTP جديدًا في Apidog. اضبط الطريقة على POST وعنوان URL على https://api.anthropic.com/v1/messages. أضف الرؤوس anthropic-version: 2023-06-01 و content-type: application/json. الصق نص JSON مع "model": "claude-sonnet-5".
2. تخزين مفتاح API كمتغير بيئة. أنشئ بيئة (على سبيل المثال، "Anthropic Production") وأضف متغيرًا باسم ANTHROPIC_API_KEY. أشر إليه في رأس x-api-key على النحو {{ANTHROPIC_API_KEY}}. الآن يعيش مفتاحك في مكان واحد، خارج نص طلبك، ويمكنك تبديل البيئات دون تعديل الطلبات.
3. احفظه في مجموعة. قم بتجميع طلبات Sonnet 5 الخاصة بك، استدعاء رسالة عادية، استدعاء تدفق، استدعاء أدوات، في مجموعة واحدة. يحصل فريقك بالكامل على نفس الطلبات الجيدة المعروفة بدلاً من نسخ مقتطفات curl هنا وهناك.
4. أضف اختبارًا آليًا. أرفق تأكيدات بالطلب بحيث يفشل التشغيل بصوت عالٍ عندما يحدث أي انحراف. على سبيل المثال:قم بدمج هذه التأكيدات في سيناريو اختبار وقم بتشغيله في CI كلما غيرت المطالبات أو قمت بترحيل إصدارات النموذج. هذا التأكيد الأخير هو أرخص طريقة لاكتشاف تراجع في max_tokens ناتج عن تفعيل التفكير التكيفي افتراضيًا الآن.
   • تأكد من أن حالة الاستجابة هي 200.
   • تأكد من أن model يساوي claude-sonnet-5.
   • تأكد من وجود stop_reason وأنه ليس max_tokens (طريقة سريعة لاكتشاف الاقتطاع بعد تغيير المُجزء).
   • تأكد من أن usage.output_tokens أكبر من 0.
5. محاكاة نقطة النهاية. تعيد المحاكاة الذكية لـ Apidog استجابة واقعية لشكل الرسائل، بحيث يمكن بناء واختبار كود العميل لتطبيقك، ومعالجة الأخطاء، ومحلل التدفق دون إنفاق رمز واحد. هذا مفيد لعمل الواجهة الأمامية ولاختبار الحمل لطبقة التكامل الخاصة بك.

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

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

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

إنه claude-sonnet-5، وهي السلسلة الدقيقة بدون لاحقة تاريخ. استخدمها في حقل model في طلب Messages الخاص بك. إنه بديل مباشر لـ claude-sonnet-4-6، لذلك في معظم الحالات تقوم بتغيير معرف النموذج ومراجعة ثلاثة أشياء: تفعيل التفكير التكيفي افتراضيًا الآن، ومعلمات أخذ العينات التي تمت إزالتها، وميزانية التفكير اليدوية التي تمت إزالتها. للحصول على الصورة الكاملة للنموذج، اقرأ ما هو Claude Sonnet 5.

لماذا يتم اقتطاع مخرج max_tokens الخاص بي في Sonnet 5؟

التفكير التكيفي مفعل افتراضيًا، وتحسب رموز التفكير ضمن max_tokens بالإضافة إلى نص استجابتك. إذا كان الحد الأقصى لديك معدلاً لعبء عمل لا يتضمن تفكيرًا في Sonnet 4.6، فقم بزيادته، أو قم بتعيين thinking: {"type": "disabled"} إذا كنت لا ترغب في التفكير على الإطلاق. ينتج المُجزء الجديد حوالي 30% رموزًا إضافية لنفس النص، مما يزيد من هذا التأثير.

هل أحتاج إلى تغيير الكود الخاص بي للترحيل من Sonnet 4.6؟

في ثلاثة أماكن فقط. قم بإزالة temperature و top_p و top_k غير الافتراضية. قم بإزالة أي thinking: {type: "enabled", budget_tokens: N}. قم بإزالة التعبئة المسبقة لرسالة المساعد. كل من هذه تُرجع خطأ 400 في Sonnet 5. كل شيء آخر، بما في ذلك أشكال التدفق والاستجابة، لم يتغير. إذا كنت تشغل Opus أيضًا، فإن دليل واجهة برمجة تطبيقات Opus 4.8 الخاص بنا يستخدم نفس سطح Messages.

هل الرفض خطأ يجب عليّ اكتشافه؟

لا. يُرجع رفض الأمن السيبراني HTTP 200 مع stop_reason: "refusal". تعامل معه كاستجابة طبيعية مع سبب توقف غير end_turn، وليس كطلب فاشل. لا ترسله عبر مسار إعادة المحاولة عند الخطأ الخاص بك.

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

السعر التمهيدي هو 2 دولار لكل مليون رمز إدخال و 10 دولارات لكل مليون رمز إخراج حتى 31 أغسطس 2026، ثم 3 دولارات و 15 دولارًا بعد ذلك. يتطابق سعر الرمز الواحد مع Sonnet 4.6، لكن المُجزء الجديد يعني أن النص المكافئ يمكن أن يكلف أكثر، لذا قم بالقياس باستخدام عد الرموز بدلاً من افتراض التكافؤ.