الـAPI: كلود داخل برنامجك

الهدف

تفهم وش الـAPI ومتى تحتاجه، تنشئ مفتاحًا، وتكتب أول استدعاء من بايثون، وتعرف كيف تحسب التكلفة وتخفّضها.

الشرح

إلى الآن تستخدم كلود من التطبيق. الـAPI (واجهة برمجية) تخلّي برنامجك أنت يستدعي كلود: موقعك يلخّص تعليقات الزبائن، تطبيقك يرد على الأسئلة، نظامك يصنّف الطلبات. بدون ما يفتح أحد تطبيق كلود.

متى تحتاج الـAPI؟

• ميزة ذكاء اصطناعي داخل منتجك أو موقعك.
• معالجة آلاف العناصر بشكل آلي (تصنيف، تلخيص، ترجمة).
• أتمتة في n8n أو أي أداة (الدرس ٨).

إذا الاستخدام شخصي وتفاعلي، التطبيق يكفيك.

الخطوات

1. حساب في منصة المطوّرين: platform.claude.com (Claude Console).
2. أضف رصيدًا (الدفع المسبق).
3. أنشئ مفتاح API من الإعدادات. انسخه واحفظه في مكان آمن؛ لا يظهر مرة ثانية.
4. ثبّت المكتبة:

pip install anthropic

1. احفظ المفتاح في متغير بيئة (ليس في الكود):

export ANTHROPIC_API_KEY="المفتاح"

أول استدعاء (بايثون)

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from the environment

message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=500,
    system="أنت مساعد خدمة عملاء لمحل عطور. رد بالعربية باختصار.",
    messages=[
        {"role": "user", "content": "هل عندكم توصيل للرياض؟"}
    ],
)
print(message.content[0].text)

• model: اسم النموذج (مثل claude-haiku-5-5 للمهام الخفيفة، claude-sonnet-5-5 للمتوازنة، claude-opus-5-5 للعميقة).
• system: تعليمات دائمة (مثل تعليمات المشروع).
• messages: المحادثة: دور المستخدم ودور المساعد بالتناوب.
• max_tokens: الحد الأقصى لطول الرد.

كيف تحسب التكلفة؟

الدفع بالتوكن (قطعة نص ≈ ٣–٤ أحرف إنجليزية، والعربية أكثر توكنات للكلمة). تدفع على المدخل (كل ما ترسله: التعليمات + المحادثة + الملفات) والمخرج (الرد). كل نموذج له سعر لكل مليون توكن، والأقوى أغلى. الأسعار الحالية في صفحة التسعير بالمنصة.

تخفيض التكلفة

1. نموذج خفيف للمهام البسيطة: تصنيف وتلخيص قصير = هايكو.
2. تعليمات مختصرة: الـsystem يُرسل في كل طلب.
3. التخزين المؤقت للبرومبت (Prompt Caching): للتعليمات والملفات الطويلة المتكررة؛ يخفّض التكلفة كثيرًا.
4. المعالجة بالدُفعات (Batch API): للمهام غير المستعجلة بخصم كبير.
5. حدّ للصرف: ضع حدًا شهريًا في المنصة (الدرس ١١).

اختبر بدون كود

في المنصة فيه «Workbench» تجرّب فيه الطلبات والنماذج والتعليمات قبل ما تكتب كودًا.

خطوة بخطوة

1. حساب + رصيد + مفتاح.
2. المفتاح في متغير بيئة.
3. pip install anthropic وشغّل المثال.
4. غيّر النموذج والتعليمات وشوف الفرق في الرد والتكلفة.
5. ضع حدًا للصرف.

برومبتات جاهزة

اكتب لي سكربت بايثون يستخدم مكتبة anthropic: يقرأ ملف messages.csv (عمود text)، يصنّف كل رسالة إلى [الفئات] بنموذج claude-haiku-5-5، ويحفظ النتيجة في results.xlsx. استخدم تخزين مؤقت لتعليمات النظام، وعالج الأخطاء بإعادة المحاولة، واطبع التكلفة التقديرية في النهاية. المفتاح من متغير البيئة ANTHROPIC_API_KEY.

عندي تطبيق [اشرحه]. أبي أضيف ميزة [اشرحها] باستخدام Claude API. اقترح: النموذج المناسب، تعليمات system، شكل الطلب والرد، وتقدير التكلفة لـ١٠٠٠ استخدام شهريًا.

أخطاء شائعة

• المفتاح داخل الكود أو في Git.
• أقوى نموذج لكل شي: فاتورة بلا داعٍ.
• بدون حد صرف: خطأ في حلقة برمجية = فاتورة مفاجئة.

تمرين

أنشئ مفتاحًا، شغّل المثال، ثم اطلب من كلود كود سكربت التصنيف على ٢٠ رسالة تجريبية. افتح صفحة الاستخدام في المنصة وشوف كم كلّفك.

الخلاصة

الـAPI = كلود داخل برنامجك. منصة + مفتاح + مكتبة + استدعاء. تدفع بالتوكن؛ وفّر بالنموذج الخفيف والتخزين المؤقت والدُفعات وحد الصرف.