احسب كلفة Claude API قبل الإرسال: العداد المجاني ليس الفاتورة كاملة

لحساب كلفة طلب Claude API قبل إرساله، استدعِ count_tokens بمعرّف النموذج وبنية الإدخال التي تنوي استخدامها، ثم اقرأ input_tokens. يوضح دليل Anthropic لعدّ الرموز أن الاستدعاء مجاني ويعيد تقديرًا لرموز الإدخال من دون إنشاء رد. وقد يختلف العدد قليلًا عن الاستخدام المسجل لاحقًا؛ كما يمكن أن يشمل رموزًا تضيفها الخدمة تلقائيًا ولا تُفوتر.

العدد المسبق نقطة بداية للميزانية، لا فاتورة مكتملة. حوّله إلى كلفة بضربه في سعر إدخال النموذج، ثم أضف تقديرًا منفصلًا للإخراج وحالة الذاكرة المخبأة ورسوم الأدوات المحتملة. بعد إنشاء الرسالة، اقرأ usage لحساب ما سُجل بالفعل، لأن العداد لا يعرف طول الرد أو نتيجة البحث أو ما إذا كان جزء من الإدخال سيُقرأ من الذاكرة المخبأة.

مرّر الإدخال نفسه إلى العداد

استخدم معرّف النموذج الذي سيستقبل الطلب، ومرّر سجل messages كاملًا، وتعليمات system في موضعها المستقل، وتعريفات أدوات العميل إذا كانت ضمن الطلب. يستطيع العداد التعامل مع الصور وملفات PDF المقدمة بصيغة base64؛ لذلك فإن عدّ النص المستخرج محليًا من ملف ليس بديلًا عن عدّ الملف إذا كنت سترسله إلى Claude. أما max_tokens فهو حد للإخراج في طلب إنشاء الرسالة، وليس عددًا يعيده عدّ الإدخال.

مثال Python قابل للتعديل بعد تثبيت anthropic وضبط ANTHROPIC_API_KEY: import anthropic; client = anthropic.Anthropic(); payload = {"model": "claude-sonnet-5", "system": "أجب بإيجاز", "messages": [{"role": "user", "content": "لخّص هذا النص"}]}; input_tokens = client.messages.count_tokens(**payload).input_tokens. استبدل الرسالة القصيرة وحقل system بالحمولة الحقيقية، ثم استخدم payload نفسه عند إنشاء الرسالة مع إضافة max_tokens. إذا كانت لديك أدوات عميل، أضف تعريفاتها إلى الحمولة التي تُعدّها أيضًا.

وفي TypeScript، بعد تثبيت @anthropic-ai/sdk وضبط المفتاح: import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const messages = [{role: "user" as const, content: "لخّص هذا النص"}]; const payload = {model: "claude-sonnet-5", system: "أجب بإيجاز", messages}; const inputTokens = (await client.messages.countTokens(payload)).input_tokens;. احتفظ بمتغيرات الحمولة نفسها بين العدّ والإنشاء حتى لا تحسب صياغة وترسل أخرى. وتذكّر أن أي نتيجة لأداة عميل ستعيدها في رسالة لاحقة تصبح جزءًا من إدخال ذلك الطلب اللاحق.

عند الانتقال بين أجيال Claude، أعد العدّ بمعرّف النموذج الجديد. تستخدم نماذج Claude 4.7 وما بعدها محللًا رمزيًا أحدث، وقد ينتج عن النص نفسه عدد رموز مختلف؛ لذلك لا يصلح رقم محفوظ من نموذج سابق لتقدير الطلب الجديد. ينطبق ذلك حتى إذا لم يتغير النص، وتزداد أهمية إعادة العدّ عندما تضم الحمولة ملفات أو تعريفات أدوات.

افصل الإدخال والإخراج والبحث في معادلة الكلفة

يعرض جدول أسعار Claude API لنسخة Claude Sonnet 5 سعر دولارين لكل مليون رمز إدخال وعشرة دولارات لكل مليون رمز إخراج، ورسم بحث ويب قدره عشرة دولارات لكل ألف عملية بحث، إضافة إلى كلفة الرموز. ولا يفرض web fetch رسم استخدام مستقلًا فوق كلفة الرموز. هذه أسعار Claude API المباشرة؛ افحص تعرفة المنصة التي تفوترك وأي خيارات تسعير إضافية قبل اعتمادها في التطبيق.

الصيغة الأساسية بالدولار هي: كلفة الإدخال = رموز الإدخال ÷ 1,000,000 × سعر الإدخال، وكلفة الإخراج المقدّرة = رموز الإخراج المخطط لها ÷ 1,000,000 × سعر الإخراج. اجمع الحدين، ثم أضف رسم البحث المتوقع إذا كان الطلب يستخدمه. حد max_tokens يصلح لبناء سقف محافظ للإخراج، لكنه لا يعني أن النموذج سيستهلكه كاملًا؛ أما متوسط الاستهلاك في طلباتك السابقة فيصلح لتوقع تشغيلي أقل تحفظًا.

في مثال افتراضي على السعر المذكور، تبلغ كلفة 10,000 رمز إدخال و1,000 رمز إخراج متوقع 0.03 دولار قبل الذاكرة المخبأة والأدوات: 0.02 دولار للإدخال و0.01 دولار للإخراج. في Python يمكن تمثيل ذلك بالعبارة estimate_usd = input_tokens * input_rate / 1_000_000 + planned_output_tokens * output_rate / 1_000_000. وفي TypeScript تقابلها const estimateUsd = inputTokens * inputRate / 1_000_000 + plannedOutputTokens * outputRate / 1_000_000;. اجعل أسعار النموذج متغيرات إعدادات، لأن تغيير النموذج أو التعرفة يجب أن يغيّر الحساب دون تعديل منطق العدّ.

إذا أتحت web search، فأضف إلى التقدير عدد عمليات البحث التي تسمح بها مضروبًا في رسم العملية، فوق رموز المحتوى الذي سيعود منها. لا يستنتج count_tokens عدد مرات البحث المستقبلية من تعريف الأداة. وبعد التنفيذ، يعطي server_tool_use.web_search_requests عدد عمليات البحث المسجلة؛ وقد يحتوي الرد على مدخلات إضافية من نتائج البحث، لذلك لا تساوِ بين عدّ الرسالة الأولية وإجمالي رموز دورة العمل.

وزّع رموز الذاكرة المخبأة على أسعارها

لا يقرر العدّ المسبق ما إذا كان جزء من الطلب سيُكتب في الذاكرة المخبأة أو سيحقق قراءة منها. يشرح دليل الذاكرة المخبأة من Anthropic أن usage يفصل الإدخال العادي في input_tokens، والكتابة في cache_creation_input_tokens، والقراءة في cache_read_input_tokens؛ ومجموع الحقول يمثل إجمالي رموز الإدخال المعالجة. كما تختلف تعرفة كتابة ذاكرة مدتها خمس دقائق عن كتابة مدتها ساعة، بينما تُسعّر القراءة بفئة مستقلة.

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

بعد التنفيذ، اضرب كل فئة من usage في سعرها: الإدخال العادي في سعر الإدخال الأساسي، والقراءة في سعر قراءة الذاكرة، والكتابة في سعر الكتابة الموافق لمدة التخزين، ثم أضف output_tokens بسعر الإخراج. إذا ظهر تفصيل cache_creation الذي يضم ephemeral_5m_input_tokens وephemeral_1h_input_tokens، فاستخدمه لتوزيع تكلفة الكتابة؛ لا تحاسب cache_creation_input_tokens مرة أخرى بعد جمع هذين الجزأين. بهذه الطريقة يظهر سبب اختلاف التقدير المسبق عن الكلفة المسجلة.

حين يرفض العداد جزءًا من الطلب

لا يقبل endpoint العدّ معظم أدوات الخادم، ومنها web search وweb fetch وتنفيذ الشيفرة والبحث عن الأدوات، ولا موصل MCP. كما يرفض كتلة صورة أو مستند تستخدم مصدر url أو file، رغم أن Messages API قد يقبلها؛ ولعدّ صورة أو PDF مسبقًا، قدّم المحتوى بصيغة base64 إذا كان ذلك مناسبًا لمسار تطبيقك. أدوات العميل مدعومة، لكن عدّ تعريفها لا يتنبأ بعدد استدعاءاتها أو بحجم النتائج التي ستعود.

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

اقرأ أيضًا:

• Claude Fable 5.1 يبقي السعر ويخفض كلفة الذاكرة المخبأة 75%
• النموذج مفتوح الأوزان ليس مفتوح المصدر: أربعة عناصر تحسم الفرق
• إضافة Google Cloud تجمع المهارات وMCP، وتطلب الموافقة قبل التغيير