التسجيل و API Key: احصل على مفتاح TypeSafe في 5 دقائق
في الدرس السابق عرفت بالفعل ما هو Jev. في هذا الدرس ستحصل على المفتاح: أكمل تسجيل TypeSafe، وادخل إلى وحدة التحكم لإنشاء مفتاح Jev API Key، وخزّنه في متغير بيئة، ثم تحقق باستخدام Playground الرسمي أنه يعمل فعلًا — كل ذلك في 5 دقائق، دون كتابة سطر كود واحد.
ماذا ستستطيع أن تفعل بعد التعلم
- إكمال تسجيل TypeSafe وتسجيل الدخول إلى وحدة تحكم TypeSafe console
- إنشاء مفتاح Jev API Key في صفحة Keys داخل وحدة التحكم
- تخزين المفتاح في متغير البيئة
TYPESAFE_API_KEYليقرأه الـ SDK تلقائيًا - إرسال طلب حقيقي واحد عبر Playground للتأكد من أن المفتاح يعمل
- معرفة أين تتحقق من حدود المعدل وماذا يحدث عند تجاوزها
مشكلتك الحالية
- تريد تجربة Jev، لكنك لا تعرف من أين تحصل على المفتاح: الموقع الرسمي والوثائق ووحدة التحكم مليئة بالمداخل، ودورت طويلًا دون أن تجد مكان الإنشاء
- نسخت المفتاح إلى الكود ونجح الطلب مرة واحدة، ثم أدركت عند الرفع إلى git أنك اقشعرّ بدنك من الخوف
- سمعت بوجود حدود للمعدل، لكنك لا تعرف كم حصتك ولا ماذا يحدث عند تجاوزها
متى تستخدم هذه الطريقة
عندما تحتاج إلى:
- مفتاح Jev API Key قادر على استدعاء
api.typesafe.ai - طريقة للتحقق من أن المفتاح يعمل دون كتابة كود
ولا تريد:
- كتابة المفتاح كنص صريح في الكود أو المستودع
- قراءة وثائق API كاملة قبل إنجاز أول طلب
🎒 التحضيرات قبل البدء
- قراءة الدرس السابق ما هو Jev، ومعرفة أن شكل استدعاء Jev هو «state + سؤال»
- متصفح حديث (التسجيل وإنشاء المفتاح والتحقق عبر Playground، كل ذلك يتم داخل المتصفح)
- شبكة قادرة على الوصول إلى
console.typesafe.ai(وحدة التحكم) وapi.typesafe.ai(API)
الفكرة الأساسية
المفتاح واحد فقط، والمدخل واحد فقط. جميع استدعاءات Jev — الـ SDK و curl و Playground — تمر عبر نفس الـ API، والمصادقة تستخدم نفس مفتاح API. لذا فإن العملية قصيرة: التسجيل ← إنشاء المفتاح في وحدة التحكم ← تخزينه في متغير بيئة ← التحقق.
لماذا التخزين في متغير بيئة. التوصية الرسمية واضحة: بعد إنشاء المفتاح خزّنه في متغير بيئة (مثل TYPESAFE_API_KEY). لهذا فائدتان:
- سيقرأ الـ SDK الرسمي هذا المتغير تلقائيًا، فلا تحتاج لكتابة أي مفتاح في الكود
- ما دام المفتاح لا يقع في ملفات الكود، فلن يُرفع مع عمليات git
TypeSafe console بها ثلاث صفحات، كل واحدة مسؤولة عن شيء واحد.
| الصفحة | العنوان | الغرض |
|---|---|---|
| Keys | console.typesafe.ai/keys | إنشاء API Key |
| Playground | console.typesafe.ai/playground | إرسال طلبات حقيقية دون كود، والتحقق من المفتاح |
| Rate limits | console.typesafe.ai/rate-limits | التحقق من حدود المعدل للمؤسسة الحالية |
إدارة توقعات. Jev يقع حاليًا في مرحلة الوصول المبكر — النص الأصلي على الموقع الرسمي هو «Try our first System One Model, Jev, in early access». قد تتغير واجهة وحدة التحكم مع الإصدارات، وهذا الدرس يثبّت فقط العناوين والعمليات المذكورة في الوثائق الرسمية، وتُعتمد تفاصيل الواجهة على الصفحة الفعلية.
⚠️ ملاحظة لمستخدمي الصين
لا توجد في المصادر الرسمية معلومات حول الوصول من شبكة الصين أو الدفع باليوان، لذا لا يقدم هذا الدرس نصائح لا يمكن التحقق منها؛ إذا واجهت مشاكل في الوصول أو الدفع، فاعتمد على إرشادات صفحات TypeSafe الرسمية.
اتبع خطواتي
الخطوة 1: أكمل تسجيل TypeSafe وسجّل الدخول إلى وحدة التحكم
لماذا: يُصدر مفتاح API فقط من داخل وحدة تحكم TypeSafe، لذا يجب أن يكون لديك حساب أولًا.
افتح في المتصفح console.typesafe.ai، وسجّل وسجّل الدخول حسب إرشادات الصفحة.
ما يجب أن تراه: دخول واجهة وحدة التحكم. يُسمى هذا المدخل في تنقل الموقع الرسمي «API console».
الخطوة 2: أنشئ مفتاح Jev API Key الخاص بك في صفحة Keys
لماذا: النص الأصلي في البداية السريعة الرسمية هو «Get an API key from the TypeSafe console»، والمقصود هو صفحة Keys هذه.
افتح console.typesafe.ai/keys، وأنشئ مفتاحًا جديدًا باتباع تعليمات الصفحة.
يجب أن ترى: سلسلة نصية للمفتاح. انسخها أولًا إلى مكان مؤقت محليًا، فستحتاجها في الخطوة التالية.
- لقد نسخت المفتاح، ولم ألصقه في أي ملف كود
الخطوة 3: خزّن المفتاح في متغير بيئة TYPESAFE_API_KEY
لماذا: التوصية الرسمية هي تخزين المفتاح في متغير بيئة؛ وسيقرأ Python SDK قيمة TYPESAFE_API_KEY تلقائيًا، فلا يظهر المفتاح في الكود.
الطريقة الواردة في البدء السريع الرسمي (Bash على macOS / Linux / Windows WSL):
export TYPESAFE_API_KEY="your-api-key"استبدل your-api-key بسلسلة المفتاح التي نسختها للتو.
يجب أن ترى: لا يوجد أي مخرجات بعد تنفيذ الأمر — export يبقى صامتًا عند النجاح.
💡 هذا الأمر يسري فقط على الطرفية الحالية
المتغير الذي يعيّنه export يختفي بعد إغلاق الطرفية، وعليك إعادة تنفيذه في كل طرفية جديدة. للحل الدائم، يمكنك إضافته إلى ملف إعدادات shell لديك (مثل ~/.bashrc) — هذا استخدام عام لـ shell، ولا تتطرق إليه وثائق TypeSafe الرسمية.
- لقد نفذت export في الطرفية الحالية، واسم المتغير هو
TYPESAFE_API_KEY
الخطوة 4: تحقق من المفتاح باستخدام Playground
لماذا: تأكد من صلاحية المفتاح قبل كتابة الكود — يرسل Playground طلبات حقيقية مباشرة من المتصفح دون تثبيت أي شيء.
- افتح console.typesafe.ai/playground وسجّل الدخول
- الصق تذكرة العمل الرسمية التالية في منطقة state:
Our API integration started returning 500 errors on every request about 20 minutes ago, and we can't process any customer orders until this is fixed.- أضف سؤال Noul من المثال الرسمي:
{
"urgency": {
"type": "noul",
"instructions": "Does this message express urgency?"
}
}يجب أن ترى: رقم احتمال بين 0 و 1. حصولك على الرقم يعني أن التسجيل والمفتاح والشبكة تعمل جميعها — هذا المفتاح صالح للاستخدام.
- حصلت في Playground على رقم بين 0–1
الخطوة 5: ألقِ نظرة على حدود المعدل الخاصة بك
لماذا: تُحسب حدود المعدل لدى Jev على مستوى المؤسسة، والطلبات التي تتجاوز الحد تُرجع 429؛ اعرف مكان التحقق من الحصة الآن حتى تكون على بيّنة عند تشغيل مهام دفعية لاحقًا.
افتح console.typesafe.ai/rate-limits.
يجب أن ترى: حدود المؤسسة الحالية، مقاسة على بعدين: عدد الرموز في الثانية (tokens/s) وعدد الطلبات في الثانية (requests/s).
نقطة تحقق ✅
- أستطيع تسجيل الدخول إلى console الخاص بـ TypeSafe، وأعرف أن المفتاح يُنشأ في صفحة
/keys - خزّنت مفتاحي في متغير البيئة
TYPESAFE_API_KEYولم أكتبه في الكود - حصلت في Playground باستخدام هذا المفتاح على احتمال بين 0–1
- أعرف أن حدود المعدل تُفحص في صفحة
/rate-limits، وأن تجاوز الحد يُرجع429 - أعرف أن SDK الرسمي يقرأ
TYPESAFE_API_KEYتلقائيًا
تنبيهات للمزالق
❌ كتابة المفتاح بشكل ثابت في الكود أو رفعه إلى git
بمجرد دخول المفتاح إلى المستودع، لا ينفع حذف الالتزام لاحقًا — أي شخص يستطيع استخدام المفتاح المسرب لحرق حصتك. الطريقة الصحيحة: خزّنه في متغير البيئة TYPESAFE_API_KEY (التوصية الرسمية)، واكتب في الكود TypeSafeClient(model="jev-latest") فقط، وسيقرأه SDK بنفسه.
❌ الطلب يُرجع 401
401 = المفتاح مفقود أو غير صالح. افحص ثلاثة أمور بالترتيب: هل نُفذ export في الطرفية الحالية؛ هل اسم المتغير هو TYPESAFE_API_KEY (بأحرف كبيرة كاملة، دون أخطاء إملائية)؛ وهل المفتاح المنسوخ يحتوي على محتوى زائد. يقوم SDK الرسمي بإزالة الفراغات في بداية المفتاح ونهايته (بما في ذلك الأسطر الجديدة)، لكن وجود مسافات أو محارف تحكم أو محارف غير ASCII داخل المفتاح يؤدي إلى الرفض مباشرة.
❌ الظن بأن المفتاح معطّل لمجرد أن الطلب يُرجع 429
429 = تم بلوغ حد المعدل، وليست مشكلة في المفتاح. الحد يُحسب على مستوى المؤسسة (tokens/s + requests/s)، فاذهب إلى صفحة /rate-limits للاطلاع على الحصة. يعيد SDK الرسمي المحاولة تلقائيًا افتراضيًا (مع إطالة مدة الانتظار تدريجيًا، والتقيد بترويسة retry-after)؛ فقط الاتصال المباشر بـ HTTP API يتطلب معالجة خاصة منك. للحصول على حصة أعلى، انتقل إلى خطة custom / enterprise، فهناك نموذج طلب رسمي.
❌ الضياع داخل وحدة التحكم
يكفي أن تتذكر ثلاث صفحات: /keys لإنشاء المفتاح، و/playground لتجربته، و/rate-limits للاطلاع على الحدود — الإدخال المباشر للعنوان في شريط العناوين هو الأسرع.
نصائح متقدمة (اختياري)
اضبط هذا المفتاح لـ coding agent أيضًا. تذكر وثائق agent skill الرسمية صراحة: أنشئ مفتاح API، وامنح coding agent الخاص بك صلاحية استخدامه، لكي يستكشف بنفسه أفضل طرق استخدام TypeSafe من خلال نداءات اختبار رخيصة. كما وفر المسؤول prompt جاهزًا — «شغّل بعض التجارب بالمفتاح الذي صدّرته إلى TYPESAFE_API_KEY، وقدّم تعديلات بناءً على النتائج الأكثر وعدًا». وبمساعدة skill الـ TypeSafe من درس التطوير بالتكامل مع Claude Code، يستطيع agent أن يكتب لك مباشرة الكود الذي يستدعي Jev.
علاقة المفتاح بالأسعار. تُحتسب رسوم نداءات Jev بهذا المفتاح بحسب الرموز — المدخلات مدفوعة والمخرجات مجانية. الجدول الكامل للأسعار وإصدارات النماذج وحدود السياق موجود في صفحة النماذج والأسعار.
خلاصة الدرس
✅ اكتمل التسجيل في TypeSafe: أصبح لديك حساب console لدى TypeSafe، والمفتاح يُنشأ في صفحة /keys.
✅ المفتاح في مكانه: مخزّن في متغير البيئة TYPESAFE_API_KEY، ويقرأه SDK الرسمي تلقائيًا، فلا مفتاح في الكود إطلاقًا.
✅ تم التحقق من المفتاح: حصلت على احتمال حقيقي في Playground؛ وأعرف مكان فحص حدود المعدل في /rate-limits.
مراجعة حقول الإعداد الأساسية:
| الحقل | القيمة الموصى بها | الشرح |
|---|---|---|
TYPESAFE_API_KEY | مفتاحك (متغير بيئة) | طريقة التخزين الموصى بها رسميًا؛ يقرأه Python SDK تلقائيًا |
| صفحة إنشاء المفتاح | console.typesafe.ai/keys | صفحة Keys في وحدة التحكم |
| Playground | console.typesafe.ai/playground | التحقق من المفتاح دون كود، وتجربة أنواع الأسئلة |
| صفحة حدود المعدل | console.typesafe.ai/rate-limits | محسوبة لكل مؤسسة: tokens/s + requests/s، وعند تجاوز الحد يُعاد 429 |
استطلاع الدرس التالي
حصلت على المفتاح، وفي الدرس التالي سنستخدمه: تثبيت Python SDK وإرسال أول طلب: جاهز خلال 10 دقيقة .
ستتعلم:
- إتمام تثبيت typesafe-sdk باستخدام venv + pip (Python 3.10+)
- تشغيل مثال الأسئلة الثلاثة للتذاكر الرسمي والحصول على التصنيف والدرجة وإجابة نعم/لا دفعة واحدة
- فهم
probabilitiesوconfidenceفي الاستجابة المرجعة - ما الذي يجب التحقق منه أولاً عند فشل التثبيت أو التشغيل