المصادقة والنطاقات
رموز الوصول الشخصية
الوصول إلى API ذاتي الخدمة: بعد أن يشتري حسابك رصيدًا، فعّله من الإعدادات → الحساب → الوصول إلى API. تُخصم الطلبات من رصيدك.
أنشئ رموز الوصول في تطبيق KolWrite (الإعدادات → الحساب → الوصول إلى API). تبدو الرموز مثل kol_...، ولا تُعرض سوى مرة واحدة عند إنشائها، وتعمل بصلاحياتك: يمكنها رؤية ملفاتك واستهلاك رصيدك وتلتزم بحدود خطتك.
أرسل رمز الوصول بإحدى الطريقتين الآتيتين — فهما متكافئتان:
Authorization: Bearer kol_...
X-API-Key: kol_...
- انتهاء الصلاحية: لا تنتهي صلاحية الرموز افتراضيًا؛ ويمكنك عند الإنشاء تحديد 7 أو 30 أو 90 يومًا، أو تاريخ مخصص.
- الإلغاء: ألغِ أي رمز وصول في التطبيق (أو استخدم
DELETE /api/v1/api-keys/{id}من جلسة مسجّل دخولها). يسري الإلغاء فورًا. - لا يمكن لرموز الوصول مطلقًا إدارة الرموز أو حذف حسابك أو الوصول إلى نقاط النهاية الإدارية — بصرف النظر عن النطاقات.
النطاقات
لا يمكن لرمز الوصول استدعاء سوى نقاط النهاية التي تغطيها النطاقات الممنوحة له. يتضمن كل إجراء في المرجع تعليقًا يحدد النطاق المطلوب له (x-required-scope في مواصفات OpenAPI).
| النطاق | الصلاحيات الممنوحة |
|---|---|
files:read | عرض الملفات والمجلدات والوسائط والمرفوعات وتنزيلها؛ وقراءة استخدام مساحة التخزين |
files:write | رفع الملفات وتسجيل الوسائط وإنشاء المجلدات ومساحات العمل أو تحديثها |
jobs:read | قراءة حالة المهمة وموضعها في قائمة الانتظار ونتائجها ونواتجها |
jobs:write | إنشاء المهام وإلغاؤها (التحويل إلى نص ودمج التسميات التوضيحية)؛ وإعادة ترتيب قائمة الانتظار |
transcripts:read | قراءة النصوص المفرّغة وإصداراتها وعناوين URL لتنزيل الصادرات |
transcripts:write | حفظ إصدارات جديدة من النصوص المفرّغة واستعادة الإصدارات السابقة |
ai:use | استخدام الذكاء الاصطناعي المُدار من KolWrite (الدردشة والتضمينات والتحويل السريع إلى نص)؛ ويستهلك الرصيد |
copilot:write | تشغيل الذكاء الاصطناعي المُقاس وحفظ المحادثات في Copilot العام أو Copilot لنص مفرغ مصرح به |
shares:read | عرض روابط المشاركة العامة وفحصها |
shares:write | إنشاء روابط المشاركة العامة وتحديثها وتدويرها وإلغاؤها |
devices:read | عرض جلسات الأجهزة المسجّل دخولها |
devices:write | تسجيل خروج جلسات الأجهزة |
account:read | قراءة إشارات الميزات وتفضيلات تجربة التطبيق |
account:write | تحديث تفضيلات تجربة التطبيق |
billing:read | قراءة رصيد الاعتمادات ودفتر العمليات والمنح |
الإعدادات المسبقة في التطبيق: للقراءة فقط (جميع نطاقات *:read)، والأتمتة (files:* وjobs:* وtranscripts:read وbilling:read)، والوصول الكامل.
أخطاء النطاقات
نطاق مفقود لنقطة نهاية مشمولة:
{"detail": {"code": "insufficient_scope",
"message": "This endpoint requires the 'jobs:write' scope",
"required_scope": "jobs:write"}}
نقطة نهاية خارج النطاق المتاح لرموز الوصول العامة:
{"detail": {"code": "pat_route_not_allowed",
"message": "This endpoint is not available to personal access tokens"}}
تعيد كلتا الحالتين HTTP 403. أما رموز الوصول غير الصالحة أو الملغاة فتعيد HTTP 401 مع invalid_api_key.
الرصيد والفوترة
تحجز المهام الرصيد عند إنشائها وتسوّيه عند اكتمالها؛ وتُحتسب استدعاءات الذكاء الاصطناعي وفق استخدام الرموز. تحقق من الإنفاق باستخدام billing:read:
GET /api/v1/billing/balanceGET /api/v1/billing/ledger
الحدود والإنفاق
- الرصيد هو الحد النهائي: الطلبات المدفوعة (مهام التفريغ ووكيل AI) تُخصم من الرصيد، وعند نفاده تُرجع HTTP 402
insufficient_credits. - يرتفع مستوى الاستخدام تلقائيًا بحسب الرصيد الذي اشتريته وعمر الحساب (Start وBuild وScale وEstablished). يحدد كل مستوى سقفًا شهريًا وعدد الطلبات في الدقيقة والطلبات المتزامنة لكل مفتاح.
- في التطبيق يمكنك تحديد ميزانية شهرية للحساب، ولكل مفتاح حدًا شهريًا وعناوين IP مسموحًا بها وتاريخ انتهاء. بعد تجاوز الميزانية أو الحد تُرجع الطلبات المدفوعة HTTP 402
api_monthly_budget_reachedأوapi_key_cap_reached؛ وكثرة الطلبات تُرجع HTTP 429 معRetry-After. - الإنفاق غير المعتاد يرسل لك رسالة أولًا؛ ولا يُوقف المفتاح مؤقتًا إلا عند قفزات حادة جدًا، ويمكنك استئنافه من التطبيق. عند تدوير مفتاح يمكن أن يبقى القديم عاملًا حتى 7 أيام.