DEV Community

Cover image for كيفية استخدام Claude Fable 5.1 API خطوة بخطوة مع أبيدوج
Yusuf Khalidd
Yusuf Khalidd

Posted on Originally published at apidog.com

كيفية استخدام Claude Fable 5.1 API خطوة بخطوة مع أبيدوج

دليل عملي لاستخدام Claude Fable 5.1 API

أُطلق Claude Fable 5.1 في 1 سبتمبر 2026، ومعرّف نموذج API الدقيق هو claude-fable-5-1 من دون لاحقة تاريخ. السعر مماثل لـ Fable 5: 10 دولارات لكل مليون رمز إدخال و50 دولارًا لكل مليون رمز إخراج، مع خفض تكلفة قراءة ذاكرة التخزين المؤقت إلى 0.25 دولار لكل مليون رمز. ويقدم النموذج ثلاثة تغييرات جوهرية لم تكن متاحة في Fable 5.

جرّب Apidog اليوم

Claude Fable 5.1

يغطي هذا الدليل المسار الكامل: الحصول على مفتاح API، إرسال أول طلب، ضبط الجهد، البث، استخدام الأدوات دون فرض tool_choice، معالجة الرفض، عرض تحديثات التقدم، والتحقق من عمل التخزين المؤقت من خلال كائن usage. جميع الطلبات HTTP عادية مع JSON، لذلك يمكنك إنشاؤها وتصحيحها في Apidog قبل دمجها في التطبيق.

إذا كنت ترحّل خدمة مبنية على Fable 5 أو Opus 5، فراجع دليل الترحيل الكامل. وللتعرف إلى النموذج، ابدأ بدليل ما هو Claude Fable 5.1.

قبل أول استدعاء: ثلاثة أسباب شائعة للخطأ 400

1. التفكير تكيفي دائمًا

يشغّل Fable 5.1 التفكير التكيفي في كل طلب. يمكنك حذف حقل thinking أو إرسال:

{"type": "adaptive"}
Enter fullscreen mode Exit fullscreen mode

أما الإعدادان التاليان فيعيدان الخطأ 400:

{"type": "disabled"}
{"type": "enabled", "budget_tokens": N}
Enter fullscreen mode Exit fullscreen mode

إذا كنت قادمًا من Opus 5، حيث كان disabled مقبولًا عند جهد high أو أقل، فأزل الحقل وتحكم في الإنفاق عبر output_config.effort. راجع قسم ما الجديد في Claude Fable 5.1 للتفاصيل.

2. لم يعد فرض استخدام الأدوات مدعومًا

الإعدادان التاليان يعيدان الخطأ:

tool_choice: {"type": "any"}
tool_choice: {"type": "tool", "name": "..."}
Enter fullscreen mode Exit fullscreen mode

استخدم auto بدلًا منهما، كما سنوضح لاحقًا.

3. الاحتفاظ بالبيانات لمدة 30 يومًا مطلوب

Fable 5.1 نموذج مغطى (Covered Model). إذا كانت المؤسسة أو مساحة العمل لا تحتفظ بالبيانات لمدة 30 يومًا، فسيعيد الطلب:

400 invalid_request_error
Enter fullscreen mode Exit fullscreen mode

من دون تفاصيل واضحة. إذا بدا الطلب صحيحًا وفشل أول استدعاء، فتحقق من سياسة الاحتفاظ بالبيانات أولًا.

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

سجّل الدخول إلى Claude Console، وافتح API Keys من إعدادات المؤسسة، ثم أنشئ مفتاحًا. انسخه مرة واحدة فقط، إذ لا يمكنك قراءته لاحقًا.

صدّر المفتاح بدلًا من وضعه في الكود:

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

في Apidog، خزّن المفتاح في متغير بيئة باسم ANTHROPIC_API_KEY، ثم استخدمه في الرأس كالتالي:

{{ANTHROPIC_API_KEY}}
Enter fullscreen mode Exit fullscreen mode

بهذه الطريقة لا يظهر المفتاح في نص الطلبات المحفوظة.

الخطوة 2: إرسال أول طلب

أنشئ طلب POST إلى:

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

استخدم الرؤوس التالية:

  • x-api-key
  • anthropic-version: 2023-06-01
  • content-type: application/json 
curl https://api.anthropic.com/v1/messages \
  -H "x-[REDACTED CREDENTIAL] \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-fable-5-1",
    "max_tokens": 16000,
    "messages": [
      {"role": "user", "content": "Explain the difference between idempotent and safe HTTP methods, with one example each."}
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

الطلب نفسه باستخدام Python وSDK الرسمي:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Explain the difference between idempotent and safe HTTP methods, with one example each."}],
)

if response.stop_reason == "refusal":
    print("declined:", response.stop_details.category if response.stop_details else None)
else:
    for block in response.content:
        if block.type == "text":
            print(block.text)
Enter fullscreen mode Exit fullscreen mode

عادتان مهمتان

تحقق من stop_reason قبل قراءة content. فالرفض الناتج عن المصنف الأمني يعيد HTTP 200 مع مصفوفة محتوى فارغة.

كذلك، امنح max_tokens مساحة كافية؛ فهو يحدد سقف رموز التفكير والاستجابة معًا. وبما أن التفكير يعمل دائمًا، فقد يؤدي الحد الضيق المستخدم مع نموذج لا يعتمد على التفكير إلى اقتطاع الاستجابة.

قد تتضمن الاستجابة كتلة thinking فارغة ضمن العرض الافتراضي omitted. هذا سلوك متوقع، ويجب إعادة الكتلة دون تغيير في الجولة التالية.

الخطوة 3: التحكم في التكلفة والعمق باستخدام effort

المعامل الأساسي للتحكم في Fable 5.1 هو effort. ضعه داخل output_config، وليس في المستوى الأعلى. القيم المتاحة هي:

  • low
  • medium
  • high
  • xhigh
  • max

القيمة الافتراضية هي high.

{
  "model": "claude-fable-5-1",
  "max_tokens": 16000,
  "output_config": {"effort": "medium"},
  "messages": [{"role": "user", "content": "Summarize this changelog in five bullets."}]
}
Enter fullscreen mode Exit fullscreen mode

توصي Anthropic بالبدء عند high، ثم مقارنة المستويات الأخرى بتقييماتك وإعادة التجربة حتى عند الترحيل من Fable 5، لأن أسماء المستويات لا تعني كمية التفكير نفسها عبر النماذج.

وتشير إرشاداتها إلى أن:

  • medium قد يطابق Fable 5 تقريبًا بتكلفة أقل.
  • low قد ينافس Opus وSonnet من حيث التكلفة لكل مهمة.
  • عند low، يستدعي النموذج أدوات البحث والاسترجاع بدرجة أقل ويعتمد على الذاكرة بدرجة أكبر.
  • عند xhigh وmax، قد ينشئ مخرجات طويلة أثناء التفكير ثم يعيد صياغتها؛ لذلك اضبط max_tokens بقيمة كبيرة عند استخدامهما.

للمرجع، راجع معامل الجهد ودليل معامل الجهد لـ Opus 5.

تغيير الجهد أثناء المحادثة

هذه الميزة تجريبية. في Fable 5، كان تغيير الجهد بين الطلبات على المستوى الأعلى يؤدي إلى حذف البادئة المخزنة مؤقتًا. أما في Fable 5.1، فيمكن لرسالة نظام فارغة تحتوي على output_config تغيير الجهد بدءًا من دور المستخدم التالي دون إبطال التخزين المؤقت.

تحتاج إلى رأس البيتا mid-conversation-output-config-2026-07-01 واستخدام client.beta.messages:

response = client.beta.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    output_config={"effort": "high"},
    betas=["mid-conversation-output-config-2026-07-01"],
    messages=[
        {"role": "user", "content": "Plan a migration from SQLite to PostgreSQL in three short steps."},
        {"role": "assistant", "content": "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts."},
        {"role": "system", "content": [], "output_config": {"effort": "low"}},
        {"role": "user", "content": "Summarize the plan in one sentence."},
    ],
)
Enter fullscreen mode Exit fullscreen mode

خفض الجهد بهذه الطريقة موثوق، بينما يعمل رفعه بصورة أفضل عند القفزات الكبيرة، مثل الانتقال من low إلى xhigh.

الخطوة 4: بث الاستجابة

قد تستغرق المهام الصعبة دقائق عند استخدام جهد مرتفع، لذلك استخدم البث لأي استجابة طويلة. وعند الاقتراب من الحد الأقصى البالغ 128,000 رمز، يتطلب SDK البث لتجنب مهلات HTTP.

with client.messages.stream(
    model="claude-fable-5-1",
    max_tokens=64000,
    messages=[{"role": "user", "content": "Write a test plan for a rate-limited public API."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final = stream.get_final_message()

print(final.stop_reason, final.usage.output_tokens)
Enter fullscreen mode Exit fullscreen mode

يعرض Apidog الاستجابة المتدفقة فور وصولها، ما يتيح لك قياس المدة التي يستغرقها التفكير عند high قبل ظهور أول رمز نصي.

الخطوة 5: استخدام الأدوات دون فرضها

عرّف الأدوات بالطريقة نفسها المستخدمة مع Fable 5، لكن اترك قرار الاستدعاء للنموذج. في Fable 5.1، يؤدي فرض أداة محددة إلى خطأ 400، لأن الاستدعاء الإجباري قد يتخطى التفكير ويدفع النموذج إلى كتابة تفكيره داخل الوسيطات.

استخدم هذه الاستراتيجية المكونة من ثلاثة أجزاء:

  1. اترك tool_choice عند auto.
  2. اذكر اسم الأداة صراحة في التعليمات.
  3. استخدم strict: true وadditionalProperties: false لضمان صحة الوسيطات. 
record_summary_tool = {
    "name": "record_summary",
    "description": "Record the structured summary of the document.",
    "strict": True,
    "input_schema": {
        "type": "object",
        "properties": {"summary": {"type": "string"}},
        "required": ["summary"],
        "additionalProperties": False,
    },
}

response = client.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    tools=[record_summary_tool],
    tool_choice={"type": "auto"},
    messages=[{"role": "user", "content": "Summarize: The meeting moved to Thursday. Call the record_summary tool with your result."}],
)
Enter fullscreen mode Exit fullscreen mode

للحصول على JSON فقط، استخدم output_config.format والمخرجات المنظمة بدلًا من الأداة.

إذا كان التطبيق يتطلب استدعاء أداة محددة في جولة حالية من محادثة متعددة الجولات، فألحق رسالة system بعد آخر دور للمستخدم، وحدد فيها الأداة المطلوبة، ثم احتفظ بها في السجل. ولا يزال الإعداد التالي يعمل في الدورة التي يجب ألا تستدعي أدوات:

{"type": "none"}
Enter fullscreen mode Exit fullscreen mode

حلقة تنفيذ الأدوات

عندما يكون stop_reason مساويًا لـ tool_use:

  1. نفّذ كل كتلة tool_use.
  2. أعد جميع كتل tool_result داخل رسالة مستخدم واحدة.
  3. أعد دور المساعد كماارم للأدوات](https://platform.claude.com/docs/en/agents-and-tools/tool-use/strict-tool-use) ودليل التفكير المحفوظ.

في الحلقات الطويلة، قد يصدر Fable 5.1 استدعاء أداة واحدًا في كل جولة بدلًا من جمع عدة استدعاءات مستقلة كما كان يفعل Fable 5. بعد كل رسالة نتيجة أداة، أرسل تلميحًا من جملة واحدة:

أولًا، اذكر بشكل خاص ما تحتاجه بعد ذلك؛ ثم اطلب كل عنصر لا يعتمد على نتيجة آخر في هذه الاستجابة الواحدة.

أرسل التلميح كرسالة نظام ذات نطاق جولة، باستخدام:

clear_at: "next_user_message"
Enter fullscreen mode Exit fullscreen mode

مع رأس البيتا:

mid-conversation-system-clear-at-2026-08-21
Enter fullscreen mode Exit fullscreen mode

واحتفظ بكل نسخة سابقة من هذه الرسالة في السجل.

الخطوة 6: معالجة الرفض باستخدام آليات التراجع

يشغّل Fable 5.1 مصنفات أمان. يُعاد الطلب المرفوض كـ HTTP 200 مع:

stop_reason: "refusal"
Enter fullscreen mode Exit fullscreen mode

ويحتوي stop_details على فئة الرفض، التي قد تكون:

  • cyber
  • bio
  • frontier_llm
  • reasoning_extraction
  • general_harms

لا تتم محاسبة الرفض قبل أي إخراج.

فعّل التراجع افتراضيًا. أبسط إعداد هو fallbacks: "default" مع رأس البيتا server-side-fallback-2026-07-01:

response = client.beta.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    fallbacks="default",
    betas=["server-side-fallback-2026-07-01"],
    messages=[{"role": "user", "content": "Audit this authentication middleware for logic bugs."}],
)

fallback_ran = any(
    entry.type == "fallback_message" for entry in (response.usage.iterations or [])
)
if fallback_ran and response.stop_reason != "refusal":
    print("served by", response.model)
Enter fullscreen mode Exit fullscreen mode

تعرض الاستجابة النموذج المستخدم في الحقل الأعلى model، بينما تشير كتلة المحتوى fallback إلى حدوث التسليم البديل. احتفظ بهذه الكتلة عند إعادة إرسال الدور.

القيود الحالية:

  • لا يُسمح بـ fallbacks في Batches API.
  • الميزة غير متاحة على Bedrock أو Google Cloud أو Foundry.
  • في هذه البيئات، سجّل BetaRefusalFallbackMiddleware من SDK على العميل.
  • الأهداف المسموح بها لـ Fable 5.1 هي claude-opus-4-8 وclaude-opus-5.

للمزيد، راجع دليل معالجة الرفض، بما في ذلك الفوترة والتوجيه الثابت وإعادة المحاولة اليدوية باستخدام رصيد التراجع.

الخطوة 7: عرض تحديثات التقدم

بين استدعاءات الأدوات، قد يكتب Fable 5.1 ملاحظات قصيرة عمّا وجده وما سيفعله لاحقًا. تصل كل ملاحظة ككتلة thinking مستقلة قبل استدعاء الأداة مباشرة.

ضمن العرض الافتراضي omitted تكون هذه الكتل فارغة. لاستقبالها كنص مع إبقاء التفكير الداخلي مخفيًا، استخدم display: "updates" ورأس البيتا thinking-display-updates-2026-08-18:

{
  "model": "claude-fable-5-1",
  "max_tokens": 16000,
  "thinking": {"type": "adaptive", "display": "updates"},
  "tools": [...],
  "messages": [{"role": "user", "content": "Review the PRs open against our billing service."}]
}
Enter fullscreen mode Exit fullscreen mode

أي كتلة thinking غير فارغة يمكن عرضها كسطر حالة. يكتب Fable 5.1 تحديثات أقل من Fable 5، لذلك إذا كانت الواجهة تعتمد على السرد، فأزل أيضًا أي سطر في المطالبة يطلب من النموذج الاحتفاظ بالنتائج للاستجابة النهائية.

الخطوة 8: التحقق من سعر قراءة التخزين المؤقت

يظهر خفض السعر إلى 0.25 دولار لكل مليون رمز عند استخدام التخزين المؤقت للمطالبات. ضع cache_control على البادئة الثابتة، ثم افحص كائن usage:

response = client.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    system=[{"type": "text", "text": LONG_STABLE_SYSTEM_PROMPT, "cache_control": {"type": "ephemeral"}}],
    messages=[{"role": "user", "content": "Which endpoints in the spec lack an error schema?"}],
)
u = response.usage
print(u.input_tokens, u.cache_creation_input_tokens, u.cache_read_input_tokens)
Enter fullscreen mode Exit fullscreen mode

في الطلب الأول، يجب أن تكون قيمة cache_creation_input_tokens غير صفرية. وتتم محاسبتها بسعر 12.50 دولارًا لكل مليون رمز مع مدة تخزين مؤقت تبلغ خمس دقائق.

عند إرسال الطلب نفسه مرة ثانية خلال خمس دقائق، يجب أن تصبح cache_read_input_tokens غير صفرية، وتتم محاسبتها بسعر 0.25 دولار لكل مليون رمز.

إذا ظلت القيمة صفرًا، فابحث عن تغيّر في البادئة، مثل:

  • طابع زمني داخل مطالبة النظام.
  • JSON غير مرتب.
  • مصفوفة أدوات تتغير بين الطلبات.

الحد الأدنى للمطالبة القابلة للتخزين المؤقت هو 512 رمزًا. راجع التخزين المؤقت للمطالبات وتفاصيل التسعير.

لماذا أصبح ثبات البادئة أهم؟

فشل التخزين المؤقت يكلف 40 ضعف التخزين الناجح، لذلك أصبح إبقاء التخزين المؤقت دافئًا أكثر أهمية من Fable 5.

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

اختبار التدفق كاملًا باستخدام Apidog

احفظ الخطوات السابقة كطلبات داخل مجموعة Apidog واحدة:

  • الاستدعاء الأول.
  • متغيرات effort.
  • البث.
  • حلقة الأدوات.
  • آلية التراجع.
  • اختبار التخزين المؤقت.

استخدم متغيرات بيئة لكل من المفتاح وmodel، بحيث يصبح التبديل بين claude-fable-5 وclaude-fable-5-1 تعديلًا واحدًا.

أضف التأكيدات التالية:

  • stop_reason ليس refusal في مطالبات الاختبار السليمة.
  • usage.cache_read_input_tokens أكبر من صفر في طلب التخزين المؤقت الثاني.
  • لا يوجد إدخال في input_transformations بالسبب: 
  prefix_binding_mismatch
Enter fullscreen mode Exit fullscreen mode

شغّل المجموعة قبل وبعد أي تغيير في التجهيزات. يمكنك تنزيل Apidog لإعداد الطلبات، كما يمكن استخدام المجموعة نفسها كفحص CI عبر Apidog CLI.

الأخطاء والمآزق الشائعة

  • 400: tool_choice: type "tool" and "any" are not supported for this model

    استخدم auto، واذكر الأداة في المطالبة، وفعّل strict: true.

  • 400 عند استخدام thinking: {"type": "disabled"}

    احذف الحقل وخفّض effort بدلًا من تعطيل التفكير.

  • 400 invalid_request_error رغم صحة النص

    تحقق من احتفاظ المؤسسة أو مساحة العمل بالبيانات لمدة 30 يومًا.

  • 400: Invalid signature in thinking block

    تم تعديل دور سابق أو مطالبة النظام أو مصفوفة الأدوات، فأصبحت كتلة التفكير مرتبطة بمحادثة مختلفة. راجع دليل التفكير المحفوظ.

  • نص تفكير فارغ

    هذا متوقع مع display: "omitted". استخدم summarized أو updates لعرضه.

  • قراءات تخزين مؤقت تساوي صفرًا

    البادئة متغيرة. راجع الطوابع الزمنية وترتيب الكائنات ومصفوفة الأدوات.

  • فشل التحقق من Priority Tier

    لا يدعم Fable 5.1 فئة Priority Tier، بينما يدعمها Fable 5.

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

ما معرّف نموذج Claude Fable 5.1 في API؟

المعرّف هو:

claude-fable-5-1
Enter fullscreen mode Exit fullscreen mode

على Amazon Bedrock استخدم:

anthropic.claude-fable-5-1
Enter fullscreen mode Exit fullscreen mode

أما Google Cloud وMicrosoft Foundry وClaude Platform على AWS فتستخدم claude-fable-5-1.

هل أحتاج إلى رأس Beta؟

لاستخدام النموذج الأساسي والتفكير التكيفي والجهد والأدوات والتخزين المؤقت، يكفي:

anthropic-version: 2023-06-01
Enter fullscreen mode Exit fullscreen mode

تحتاج إلى رؤوس Beta فقط من أجل:

  • ضبط الجهد لكل رسالة.
  • رسائل النظام محددة النطاق للدورة.
  • تحديثات التقدم.
  • التراجع من جانب الخادم.
  • عناصر التحكم في ربط التفكير.

هل يمكنني فرض استدعاء أداة؟

لا. يعيد tool_choice من النوعين any وtool خطأ 400. استخدم auto، واذكر الأداة في المطالبة، وفعّل strict: true. وإذا كان هدفك استخراج JSON فقط، فاستخدم المخرجات المنظمة.

ما الحد الأقصى للإخراج؟

الحد الأقصى في Messages API هو 128,000 رمز. استخدم البث للاستجابات الكبيرة. ولم يُدرج إصدار Batch API التجريبي، الذي يدعم 300,000 رمز، لـ Fable 5.1.

كيف أرى قراءات التخزين المؤقت الأقل تكلفة؟

افحص:

usage.cache_read_input_tokens
Enter fullscreen mode Exit fullscreen mode

في طلب متكرر. تُحاسب هذه الرموز بسعر 0.25 دولار لكل مليون رمز في Fable 5.1، مقارنةً بدولار واحد في Fable 5 و0.50 دولار في Opus 5.

هل لا يزال دليل Fable 5 API صالحًا؟

بوجه عام، نعم. يغطي دليل Fable 5 API نقطة النهاية نفسها، لكن أمثلة فرض استخدام الأدوات فيه ستعيد خطأ 400 مع Fable 5.1. كما يسبق Fable 5.1 بتغيير الجهد لكل رسالة وتحديثات التقدم.

Top comments (0)