# كيف يفرّغ أي وكيل ذكاء اصطناعي الصوت عبر KolWrite؟

> إذا كان الوكيل قادرًا على تشغيل أمر في الـ shell، فأعطه kolwrite.py: ملف Python واحد يعتمد على المكتبة القياسية فقط، يرفع الملف ويبدأ المهمة وينتظر ثم يكتب النتيجة. وللوكلاء الذين يحمّلون المهارات هناك الملف نفسه مضمَّنًا في المهارة kolwrite-transcribe، ولكل ما عدا ذلك هناك REST API وملف OpenAPI الخاص به.

آخر تحديث: 2026-11-21 · HTML: https://console.kolwrite.com/ar/agents/any-agent

## ما تفعله مرة واحدة

أنشئ الحساب والمفتاح بنفسك من [console.kolwrite.com](https://console.kolwrite.com/auth?lang=ar): سجّل، وأضف رصيدًا، ثم افتح «API Keys» وأنشئ مفتاحًا. لا يستطيع الوكيل القيام بذلك نيابةً عنك.

احفظ المفتاح في ملف إعدادات الـ shell (`~/.zshrc` أو `~/.bashrc`) لتتمكن كل جلسة وكيل تبدأها من قراءته، ثم افتح نافذة طرفية جديدة:

```bash
export KOLWRITE_API_KEY=...   # paste the key from API Keys
```

تقرأ الأدوات المفتاح من هذا المتغير فقط. لا تلصقه في محادثة ولا تضعه في مستودع.

## تنزيل kolwrite.py والتحقق منه

```bash
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](https://console.kolwrite.com/cli/kolwrite.py).

## الأوامر التي يشغّلها الوكيل

```bash
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](https://console.kolwrite.com/skills/kolwrite-transcribe/SKILL.md) مع `scripts/kolwrite.py`، مضغوطَين في [kolwrite-transcribe.zip](https://console.kolwrite.com/skills/kolwrite-transcribe.zip). والمهارة مدرجة في [/.well-known/agent-skills/index.json](https://console.kolwrite.com/.well-known/agent-skills/index.json).

```bash
curl -fsSLO https://console.kolwrite.com/skills/kolwrite-transcribe.zip && unzip -o kolwrite-transcribe.zip
```

## القاعدة الخاصة بـ AGENTS.md أو CLAUDE.md

```markdown
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](https://console.kolwrite.com/openapi.json) (بصيغة OpenAPI 3.1 مع أمثلة ورموز الأخطاء الفعلية) و[llms-full.txt](https://console.kolwrite.com/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](https://console.kolwrite.com/ar/models).

## ما يجب ألا يفعله الوكيل

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

## أسئلة وأجوبة

### لماذا ملف واحد بدل حزمة؟

لا شيء لتثبيته ولا شيء يتغيّر دون علمك: ينزّل الوكيل ملفًا واحدًا ويتحقق من قيمة الـ hash الخاصة به ثم يشغّله. ولا توجد حتى الآن حزمة SDK على npm أو PyPI.

### ماذا يرسل kolwrite.py، وإلى أين؟

يرسل الملف والخيارات التي تعطيها له فقط، إلى KolWrite API على app.kolwrite.com، مع مفتاحك في الترويسة `x-api-key`. أما الملفات التي يتجاوز حجمها 4 MiB فتُرسل إلى نموذج التخزين الموقَّع الذي يعيده الـ API، دون المفتاح.

## صفحات ذات صلة

- [Claude Code](https://console.kolwrite.com/ar/agents/claude-code)
- [Codex](https://console.kolwrite.com/ar/agents/codex)
- [أداة تفريغ لوكلاء الذكاء الاصطناعي](https://console.kolwrite.com/ar/guides/transcription-tool-for-ai-agents)
- [وكلاء الذكاء الاصطناعي والبرمجة بالإيحاء](https://console.kolwrite.com/ar/use-cases/ai-agents)
- [توثيق الـ API](https://console.kolwrite.com/ar/public_api_docs)

---
احصل على مفتاح API: https://console.kolwrite.com/auth?lang=ar · توثيق الـ API: https://console.kolwrite.com/ar/public_api_docs · llms.txt: https://console.kolwrite.com/llms.txt
