KolWrite KolWrite المطورون

المصادقة والنطاقات

رموز الوصول الشخصية

أنشئ رموز الوصول في تطبيق KolWrite (الإعدادات → الحساب → الوصول إلى API). تبدو الرموز مثل kol_...، ولا تُعرض سوى مرة واحدة عند إنشائها، وتعمل بصلاحياتك: يمكنها رؤية ملفاتك واستهلاك رصيدك وتلتزم بحدود خطتك.

أرسل رمز الوصول بإحدى الطريقتين الآتيتين — فهما متكافئتان:

Authorization: Bearer kol_...
X-API-Key: kol_...

النطاقات

لا يمكن لرمز الوصول استدعاء سوى نقاط النهاية التي تغطيها النطاقات الممنوحة له. يتضمن كل إجراء في المرجع تعليقًا يحدد النطاق المطلوب له (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:

نسخة Markdown من هذه الصفحة