المصادقة

إنشاء مفتاح

تُصدَر مفاتيح API من مساحة عمل على console.artfical.com، من صفحة مفاتيح API. إنشاء مفتاح من هناك هو الطريقة الوحيدة للحصول عليه؛ لا توجد طريقة لسك مفتاح جديد أو تدويره عبر الـ API نفسه، وهذا مقصود: إنشاء المفتاح إجراء حساس ومنخفض التكرار، ووضعه خلف جلسة وحدة التحكم الموثّقة الخاصة بها يبقيه بعيدًا عن متناول أي شيء لا يملك سوى صلاحية وصول على مستوى الـ API.

يبدو المفتاح هكذا، دائمًا بنفس البادئة:

tai-sk-bSL2q4ja-skivx5JVNaJyyDVtKgiBAxuq8yRzsb6-e8

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

إرسال المفتاح مع الطلب

يجب أن يتضمن كل طلب إلى /v1/chat/completions و/v1/models المفتاح في ترويسة Authorization قياسية، باستخدام مخطط Bearer:

Authorization: Bearer tai-sk-bSL2q4ja-skivx5JVNaJyyDVtKgiBAxuq8yRzsb6-e8

هذا هو نفس شكل الترويسة الذي تستخدمه واجهة OpenAI نفسها، ولهذا فإن توجيه عميل قائم على SDK الخاص بـ openai نحو tAI عادةً ما يكون تغييرًا بسطر واحد: عيّن base_url إلى https://api.artfical.com/v1 وapi_key إلى مفتاح tAI الخاص بك، ولا يحتاج كود الطلب الخاص بالـ SDK نفسه إلى أي تغيير.

# Python, using the official openai package
from openai import OpenAI

client = OpenAI(
    base_url="https://api.artfical.com/v1",
    api_key="tai-sk-...",
)

response = client.chat.completions.create(
    model="tai-4.1",
    messages=[{"role": "user", "content": "Merhaba"}],
)
print(response.choices[0].message.content)

الطلب الذي تنقصه الترويسة كليًا، أو يرسلها بشكل خاطئ (بلا بادئة Bearer ، أو قيمة فارغة، أو مفتاح لا يمكن تحليله)، يُرفض بنفس طريقة رفض مفتاح غير صالح تمامًا: خطأ 401 من نوع authentication_error. راجع الأخطاء لمعرفة الشكل الدقيق للاستجابة.

مساحات العمل والنطاق

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

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

انتهاء الصلاحية

يمكن إنشاء المفتاح اختياريًا بتاريخ انتهاء صلاحية (بعد 7 أو 30 أو 90 يومًا، أو بلا انتهاء، يُختار عند إنشاء المفتاح). بمجرد تجاوز المفتاح تاريخ انتهائه، يُرفض كل طلب يُجرى به بنفس خطأ 401 authentication_error الذي يُرفض به مفتاح غير صالح، ولا يمكن تمييزه من الخارج. إذا بدأت الطلبات التي تستخدم مفتاحًا كان يعمل سابقًا تفشل فجأة بخطأ 401، فإن انتهاء صلاحية المفتاح هو أول شيء يجب التحقق منه، في صفحة مفاتيح API، قبل افتراض أن شيئًا آخر قد تعطّل.

لا يوجد تجديد تلقائي. يجب استبدال المفتاح القريب من انتهاء صلاحيته بمفتاح مُنشأ حديثًا؛ لا تمدّد وحدة التحكم عمر مفتاح قائم في مكانه.

إلغاء مفتاح

يمكن إلغاء المفتاح في أي وقت من صفحة مفاتيح API، فورًا وبلا رجعة. يتصرف المفتاح المُلغى تمامًا كمفتاح منتهي الصلاحية من وجهة نظر الـ API: كل طلب لاحق به يحصل على 401. الإلغاء هو الاستجابة الصحيحة لمفتاح مسرّب؛ لا توجد طريقة لتدوير القيمة السرية لمفتاح في مكانه، بل فقط إلغاء القديم وإنشاء مفتاح جديد ليحل محله.

ما لا يمنحه المفتاح وحده

امتلاك مفتاح API صالح كافٍ لإجراء طلبات إكمال محادثة وسرد النماذج. لكنه لا يمنح وصولاً إلى أي شيء في واجهة وحدة التحكم نفسها، أو إعدادات مساحة العمل، أو معلومات الفوترة، أو نشاط الأعضاء الآخرين؛ فتلك محمية بتسجيل الدخول القائم على جلسة وحدة التحكم نفسها، وهو منفصل تمامًا عن مفاتيح API. المفتاح المسرّب مشكلة حقيقية، لأنه يتيح لشخص ما إجراء طلبات (وتكبّد الاستخدام المرتبط بها) نيابة عن مساحة عملك، لكنه لا يكشف بذاته عن حساب وحدة التحكم الخاص بك ولا يتيح لأحد تسجيل الدخول بصفتك.