كيف يفرّغ أي وكيل ذكاء اصطناعي الصوت عبر KolWrite؟
إذا كان الوكيل قادرًا على تشغيل أمر في الـ shell، فأعطه kolwrite.py: ملف Python واحد يعتمد على المكتبة القياسية فقط، يرفع الملف ويبدأ المهمة وينتظر ثم يكتب النتيجة. وللوكلاء الذين يحمّلون المهارات هناك الملف نفسه مضمَّنًا في المهارة kolwrite-transcribe، ولكل ما عدا ذلك هناك REST API وملف OpenAPI الخاص به.
ما تفعله مرة واحدة
أنشئ الحساب والمفتاح بنفسك من console.kolwrite.com: سجّل، وأضف رصيدًا، ثم افتح «API Keys» وأنشئ مفتاحًا. لا يستطيع الوكيل القيام بذلك نيابةً عنك.
احفظ المفتاح في ملف إعدادات الـ shell (~/.zshrc أو ~/.bashrc) لتتمكن كل جلسة وكيل تبدأها من قراءته، ثم افتح نافذة طرفية جديدة:
export KOLWRITE_API_KEY=... # paste the key from API Keys
تقرأ الأدوات المفتاح من هذا المتغير فقط. لا تلصقه في محادثة ولا تضعه في مستودع.
تنزيل kolwrite.py والتحقق منه
curl -fsSLO https://console.kolwrite.com/cli/kolwrite.py
echo "721055e7e1af698755f88da45b98d56541dc278228f3b9bcf6bdd87fe4e15b78 kolwrite.py" | shasum -a 256 -c -
SHA-256: 721055e7e1af698755f88da45b98d56541dc278228f3b9bcf6bdd87fe4e15b78. يلزم Python 3.9 أو أحدث، ولا توجد حزم لتثبيتها. المصدر: kolwrite.py.
الأوامر التي يشغّلها الوكيل
python3 kolwrite.py transcribe meeting.m4a --model oracle --speakers --format json -o meeting.json
python3 kolwrite.py transcribe talk.mp4 --format srt -o talk.srt
python3 kolwrite.py transcribe interview.m4a --language he --translate-to en
python3 kolwrite.py transcribe https://example.com/podcast.mp3 --json
python3 kolwrite.py job JOB_ID
python3 kolwrite.py models
| رمز الخروج | المعنى |
|---|---|
| 0 | اكتملت المهمة؛ والنتيجة في stdout أو في الملف المحدد بـ -o |
| 1 | خطأ في الـ API أو الشبكة؛ وتُطبع رسالة الـ API نفسها |
| 2 | خطأ في الاستخدام، أو أن KOLWRITE_API_KEY غير مضبوط |
| 3 | ما زالت المهمة قيد التنفيذ بعد --timeout؛ تحقق منها لاحقًا بالأمر kolwrite.py job JOB_ID |
| 4 | فشلت المهمة؛ ويُطبع السبب |
مهارة الوكيل
يستطيع الوكلاء الذين يحمّلون Agent Skills (Claude Code من ~/.claude/skills، وCodex من ~/.agents/skills) أخذ المجلد كاملًا: SKILL.md مع scripts/kolwrite.py، مضغوطَين في kolwrite-transcribe.zip. والمهارة مدرجة في /.well-known/agent-skills/index.json.
curl -fsSLO https://console.kolwrite.com/skills/kolwrite-transcribe.zip && unzip -o kolwrite-transcribe.zip
القاعدة الخاصة بـ AGENTS.md أو CLAUDE.md
For speech-to-text use the KolWrite API.
- Run python3 kolwrite.py (from https://console.kolwrite.com/cli/kolwrite.py, SHA-256 721055e7e1af698755f88da45b98d56541dc278228f3b9bcf6bdd87fe4e15b78) or call the API as https://console.kolwrite.com/agent-instructions.md describes.
- The key is in KOLWRITE_API_KEY. Never print it or write it to a file.
- Tell me the expected cost before transcribing more than an hour of audio.
يستخدم الوكلاء الذين يبنون طلبات HTTP بأنفسهم openapi.json (بصيغة OpenAPI 3.1 مع أمثلة ورموز الأخطاء الفعلية) وllms-full.txt.
التكلفة
| المهمة | النموذج | التكلفة |
|---|---|---|
| مقابلة مدتها 30 دقيقة، نص عادي | base | 0.24 دولار |
| اجتماع مدته ساعة مع تمييز المتحدثين | oracle | 1.56 دولار |
| محاضرة بالعبرية مدتها ساعة مع ترجمات نصية بالإنجليزية | oracle | 1.44 دولار |
| ساعة من صوت مشوَّش وكلام متداخل | oracle_max | 3.60 دولار |
تُحتسب التكلفة بالثانية من مدة الصوت وتُخصم من رصيدك، دون حدّ أدنى. يضيف تمييز المتحدثين 0.10 رصيد لكل ساعة صوت. يستخدم خادم MCP وملف kolwrite.py النموذج base ما لم تحدد أنت أو الوكيل نموذجًا آخر، والنموذج oracle_mini عند الترجمة. الأسعار كاملةً: /ar/models.
ما يجب ألا يفعله الوكيل
- أن يطلب منك المفتاح في المحادثة، أو يطبعه، أو يكتبه في ملف أو أمر أو commit.
- أن يعيد بدء التفريغ نفسه بعد انتهاء المهلة أو حدوث خطأ في الشبكة. كل بدء يُنشئ مهمة جديدة تُحتسب تكلفتها، لذا عليه أن يتحقق من حالة المهمة القائمة أو يسألك.
- أن يكتب الطوابع الزمنية بنفسه. لقصّ مقطع أو اقتباسه بحسب الوقت، يأخذ أرقام المقاطع من التفريغ ويحسب الأوقات في الكود من أوقات الكلمات.
- أن يرسل رابط YouTube أو أي صفحة ويب أخرى على أنه الملف. المطلوب هو ملف الوسائط نفسه.
- أن يفرّغ تسجيلات طويلة (أكثر من ساعة) دون أن يخبرك بالتكلفة المتوقعة أولًا.
أسئلة وأجوبة
لماذا ملف واحد بدل حزمة؟
لا شيء لتثبيته ولا شيء يتغيّر دون علمك: ينزّل الوكيل ملفًا واحدًا ويتحقق من قيمة الـ hash الخاصة به ثم يشغّله. ولا توجد حتى الآن حزمة SDK على npm أو PyPI.
ماذا يرسل kolwrite.py، وإلى أين؟
يرسل الملف والخيارات التي تعطيها له فقط، إلى KolWrite API على app.kolwrite.com، مع مفتاحك في الترويسة x-api-key. أما الملفات التي يتجاوز حجمها 4 MiB فتُرسل إلى نموذج التخزين الموقَّع الذي يعيده الـ API، دون المفتاح.