# تحويل الكلام العربي إلى نص عبر API: دليل المطوّر لتفريغ اللهجة الخليجية

> طلب POST واحد، وملف صوتي، ونص عربي يعود إليك واللهجة كما هي. ماذا ترسل، وماذا يعود، وكم يكلّف، وأين يخطئ التعرّف على الكلام العربي عادةً.

- المصدر: https://nutq.dev/ar/blog/arabic-speech-to-text-api
- نُشر: 2026-09-24
- حُدّث: 2026-09-25
- الكاتب: nutq team (https://nutq.dev)

## الجواب المختصر

لتحويل الكلام العربي إلى نص عبر واجهة برمجية، أرسل الملف الصوتي بصيغة multipart إلى نقطة التفريغ واقرأ النص من استجابة JSON. في نُطق يكفي طلب POST واحد إلى ‎/v1/transcribe بمفتاح API؛ يتعرّف على اللغة تلقائيًا، ويحافظ على اللهجة الخليجية والشامية كما نُطقت بدل تحويلها إلى الفصحى، ويقبل ملفات حتى ساعة، وسعره 0.15 دولار لكل ساعة صوت.

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

## ماذا تفعل واجهة تحويل الكلام العربي إلى نص فعلًا؟

تأخذ تسجيلًا وتعيد كلماته نصًا. لكن هذه المهمة البسيطة فيها ثلاثة أجزاء صعبة مع العربية:

1. **اللهجة.** الناس في دبي والرياض وعمّان لا يتكلمون الفصحى على الهاتف. كثير من النماذج دُرّبت على الفصحى أساسًا، ف"تصحّح" اللهجة إليها، وهذا يغيّر ما قيل. نفصّل ذلك في [اللهجة الخليجية مقابل الفصحى في التفريغ](/ar/blog/gulf-arabic-vs-msa-transcription).
2. **جودة الصوت.** معظم الصوت العربي الذي يستحق التفريغ — مكالمات الدعم والمبيعات والرسائل الصوتية — ضيّق النطاق وفيه ضجيج. الدقة المقيسة على صوت إذاعي نظيف لا تخبرك بالكثير عن مركز اتصال.
3. **المزج بين اللغتين.** الكلام الخليجي يُدخل كلمات إنجليزية وسط الجملة، والنموذج الذي يفرض لغة واحدة على الملف كله يشوّهها.

## كيف تفرّغ ملفًا صوتيًا عربيًا بطلب واحد؟

أنشئ مفتاحًا من [لوحة التحكم](/sign-up)، ثم أرسل الملف:

```bash
curl -X POST https://nutq.dev/v1/transcribe \
  -H "Authorization: Bearer $NUTQ_API_KEY" \
  -F "file=@call.mp3"
```

لا مكتبة تحتاج إلى تثبيتها. الطلب نفسه بلغة JavaScript:

```js
const body = new FormData()
body.append('file', file)

const res = await fetch('https://nutq.dev/v1/transcribe', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.NUTQ_API_KEY}` },
  body,
})
const { text, usage } = await res.json()
```

وبلغة Python:

```python
import requests

with open("call.mp3", "rb") as f:
    res = requests.post(
        "https://nutq.dev/v1/transcribe",
        headers={"Authorization": f"Bearer {NUTQ_API_KEY}"},
        files={"file": f},
    )
print(res.json()["text"])
```

## ماذا يعود في الاستجابة؟

```json
{
  "text": "هلا وغلا فيك، شحالك اليوم؟",
  "language": "ar",
  "language_source": "detected",
  "language_confidence": 1,
  "usage": { "audio_seconds": 13.23, "cost_usd": 0.00056 },
  "model": "nutq-listen-1"
}
```

ثلاثة حقول تستحق الانتباه:

- **`language_source`** يخبرك كيف اختيرت اللغة: `requested` (حددتها أنت)، أو `detected` (أرسلت `auto`)، أو `corrected` (حددت لغة لكن التسجيل كان بلغة أخرى بوضوح)، أو `fallback` (التسجيل أقصر من أن يُحكم عليه، فاعتُمدت العربية).
- **`usage`** هو ما كلّفه هذا الطلب فعلًا، لا تقديرًا. سجّله بجانب النص وستتطابق فواتيرك تلقائيًا.
- **`model`** يسمّي النموذج الذي خدم الطلب، فيمكن تتبّع أي نص إلى إصداره.

## ما اللهجات واللغات المدعومة؟

| الكلام | الدعم |
|---|---|
| الخليجية (الإماراتية، السعودية، الكويتية، القطرية…) | مضبوط عليها؛ اللهجة تبقى كما نُطقت |
| الشامية | مضبوط عليها؛ اللهجة تبقى كما نُطقت |
| الفصحى | مدعومة |
| المغاربية واليمنية والسودانية | يتعرّف عليها بدقة أقل |
| 13 لغة أخرى | en, fr, es, de, it, pt, nl, pl, el, ja, ko, zh, vi |

إن كنت تعرف اللغة فمرّرها `language=ar` (أو أي رمز أعلاه). وإن كان التسجيل بلغة أخرى بوضوح، تفرّغ الواجهة ما قيل فعلًا وتخبرك بذلك، بدل فرض لغة خاطئة عليه.

## ما مدى الدقة على الصوت الحقيقي؟

ننشر اختبارًا واحدًا لأنه يطابق طريقة تسجيل الصوت العربي فعلًا: على مكالمة هاتفية حقيقية ضيّقة النطاق، ارتكب نُطق **أخطاء حروف أقل بنسبة 40%** من المزوّد العربي الرائد. وشمل التقييم الأوسع **986 مقطعًا** — بثّ إذاعي ومقابلات عفوية ومكالمات هاتفية — قورنت كلها بنصوص كتبها بشر. التفاصيل، ولماذا يكسر صوت الهاتف أغلب النماذج، في [تفريغ المكالمات الهاتفية العربية](/ar/blog/transcribe-arabic-phone-calls).

والسرعة مهمة في المعالجة الجماعية: التفريغ أسرع من الزمن الحقيقي بنحو **22 مرة**، فتسجيل مدته ساعة يعود في أقل من ثلاث دقائق.

## كم يكلّف تفريغ الصوت العربي؟

| | السعر |
|---|---|
| تحويل الكلام إلى نص | 0.15 دولار لكل ساعة صوت |
| رصيد مجاني عند التسجيل | 5 دولارات، نحو 33 ساعة، بلا بطاقة |
| الطلبات الفاشلة | لا تُحتسب |

يصل حجم الملف إلى 100 ميغابايت ومدته إلى ساعة؛ والتسجيلات الأطول تُقسَّم وتُجمع تلقائيًا، فترسل طلبًا واحدًا في الحالتين.

## كيف تختبر واجهة تفريغ عربية قبل الالتزام بها؟

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

- كلمات لهجية تحوّلت إلى مقابلها الفصيح،
- كلمات إنجليزية داخل جمل عربية،
- الأسماء والأرقام ومصطلحات منتجك،
- الثواني الأخيرة من كل ملف، حيث تُسقط بعض الأنظمة الصوت.

ورصيدك المجاني البالغ 5 دولارات يغطي أضعاف ما يحتاجه هذا الاختبار.

## هل يمكن تشغيله على خوادمنا؟

نعم. للبنوك والجهات الحكومية وكل من لا يجوز أن تغادر تسجيلاته المبنى، تعمل النماذج نفسها **داخل شبكتك على بطاقة رسومية واحدة بذاكرة 24 غيغابايت**، دون إرسال أي صوت إلينا ودون رسوم على الدقيقة. [تحدّث معنا عن التشغيل الداخلي](/docs).

## إلى أين بعد ذلك؟

- [التوثيق الكامل](/docs) يغطي البث المباشر والأخطاء وOAuth للتطبيقات التي تعمل نيابة عن المستخدم.
- تريد تحويل النص إلى كلام؟ اقرأ [تحويل النص العربي إلى كلام واستنساخ الصوت](/ar/blog/arabic-text-to-speech-voice-cloning).
- تضيف ترجمة إلى فيديو؟ [الترجمة العربية التلقائية للفيديو](/ar/blog/auto-arabic-subtitles-for-video) تشرح الطريق بلا برمجة.

## أسئلة شائعة

### هل توجد واجهة برمجية لتحويل الصوت إلى نص تدعم اللهجات العربية؟

نعم. نموذج nutq-listen-1 من نُطق مضبوط على اللهجتين الخليجية والشامية، ويكتب الكلام باللهجة التي قيل بها بدل تحويله إلى الفصحى. ويتعرّف كذلك على اللهجات المغاربية واليمنية والسودانية بدقة أقل.

### كم تكلفة تفريغ الصوت العربي؟

0.15 دولار لكل ساعة صوت، تُحسب بالثانية. الحسابات الجديدة تحصل على رصيد 5 دولارات بلا بطاقة، أي نحو 33 ساعة تفريغ. والطلبات التي تفشل لا تُحتسب.

### ما صيغ الملفات وأطوالها المقبولة؟

أي صيغة صوت أو فيديو شائعة، حتى 100 ميغابايت وساعة واحدة للملف. التسجيلات الطويلة تُقسَّم ثم تُجمع تلقائيًا.

### هل يجب أن أحدد لغة التسجيل؟

لا. القيمة الافتراضية auto تتعرّف على اللغة من أول ثانيتين من الكلام. ويمكنك تحديد واحدة من 14 لغة، وتخبرك الاستجابة باللغة المستخدمة وكيف تقرّرت.

### هل يمكن تفريغ الصوت المباشر لا الملفات فقط؟

نعم. نقطة WebSocket تستقبل صوت PCM خامًا وتعيد النص كلما توقف المتحدث. وهي تتبع بروتوكول Deepgram المباشر، فيعمل أي عميل Deepgram موجود بتغيير الرابط فقط.