---
title: البدء السريع
description: أرسل أول طلب لتحويل النص إلى كلام عربي.
---

تحويل النص إلى كلام عربي باستخدام نقطة النهاية `/v1/audio/speech`. يوضح هذا الدليل خطوات المصادقة، واختيار الصوت، وإرسال طلب تحويل النص إلى كلام، وحفظ الملف الصوتي الناتج، والتعامل مع حالات الخطأ المدعومة.

اضبط هذين المتغيرين مرة واحدة قبل تشغيل الأمثلة:

```bash
export SAWTAK_API_BASE_URL="https://api.sawtakarabi.ai/v1"
export SAWTAK_API_KEY="<API_KEY>"
```

## 1. إنشاء مفتاح API

تتطلب الطلبات رمز حامل (Bearer token) يُمرر في ترويسة `Authorization`.

- لتحويل النص إلى كلام، يجب أن يتضمن مفتاح API نطاق `tts`.
- لاستعراض دليل الأصوات، يجب أن يتضمن مفتاح API نطاق `voices`.

مرر المفتاح عبر متغير البيئة `SAWTAK_API_KEY` في ترويسة الطلب:

```bash
-H "Authorization: Bearer $SAWTAK_API_KEY"
```

## 2. اختيار الصوت

استعرض دليل الأصوات المتاحة بإرسال طلب `GET $SAWTAK_API_BASE_URL/voices`:

```bash
curl --fail --show-error "$SAWTAK_API_BASE_URL/voices" \
  -H "Authorization: Bearer $SAWTAK_API_KEY"
```

تُعيد الواجهة غلاف قائمة (`object: "list"`) يضم كائنات الأصوات في مصفوفة `data`. يتضمن كل عنصر معرّف الصوت (`id`) والاسم (`name`) والحالة (`status`) والتصنيفات (`labels`) مثل اللهجة (`dialect`) والنوع (`gender`).

لتخصيص الصوت، مرر معرّف الصوت (`id`) في الحقل `voice` ضمن طلب تحويل النص إلى كلام. وإذا حذفت الحقل `voice`، تستخدم نقطة النهاية الصوت الافتراضي.

## 3. إرسال طلب تحويل النص إلى كلام

أرسل طلب `POST` إلى `$SAWTAK_API_BASE_URL/audio/speech` محددًا النموذج والنص وتنسيق الاستجابة المطلوب:

```bash
curl --fail --show-error "$SAWTAK_API_BASE_URL/audio/speech" \
  -H "Authorization: Bearer $SAWTAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "arabic-tts-1",
    "input": "مرحبا بك",
    "response_format": "wav"
  }' \
  --output speech.wav
```

لتحديد صوت معين من الدليل، أضف خاصية `voice` مع قيمة `id` الخاصة بذلك الصوت.

## 4. تشغيل الصوت أو حفظه

تبث نقطة النهاية البيانات الصوتية مباشرة في الملف المحدد عبر الخيار `--output`:

- **صيغة WAV (`response_format: "wav"`)**: تُرفق البوابة ترويسة RIFF/WAV قياسية مع الدفق الصوتي (`audio/wav`). يمكنك تشغيل الملف فورًا عبر سطر الأوامر:
  ```bash
  afplay speech.wav
  ```
  أو على أنظمة Linux:
  ```bash
  aplay speech.wav
  ```
- **صيغة PCM (`response_format: "pcm"`)**: تبث البوابة دفق PCM خام بعمق 16 بت (`audio/pcm`). احفظ الدفق في `speech.pcm` عند التكامل مع أنظمة معالجة تقبل PCM المباشر الخالي من الترويسات.

## 5. استجابات الفشل المدعومة

تتبع استجابات الأخطاء غلاف أخطاء متوافق مع مواصفات OpenAI يحتوي على `message` و`type` و`code` و`param` و`request_id`.

### صوت غير معروف (`400 Bad Request`)

تؤدي كتابة معرّف صوت غير موجود إلى إرجاع خطأ من نوع `invalid_request_error` مع الرمز `bad_voice`:

```json
{
  "error": {
    "message": "Unknown voice 'unknown-voice-id'. `voice` must be one of your voice ids from /v1/voices; omit it for the default voice.",
    "type": "invalid_request_error",
    "code": "bad_voice",
    "param": null,
    "request_id": null
  }
}
```

### نطاق الصلاحيات غير كافٍ (`403 Forbidden`)

يؤدي استخدام مفتاح يفتقر إلى نطاق `tts` المطلوب إلى إرجاع خطأ من نوع `permission_error`:

```json
{
  "error": {
    "message": "Insufficient scope",
    "type": "permission_error",
    "code": "insufficient_scope",
    "param": null,
    "request_id": null
  }
}
```

### فشل المصادقة (`401 Unauthorized`)

يؤدي حذف رمز التفويض أو إرسال مفتاح غير صالح إلى إرجاع خطأ من نوع `authentication_error`:

```json
{
  "error": {
    "message": "Authentication failed",
    "type": "authentication_error",
    "code": "auth_failed",
    "param": null,
    "request_id": null
  }
}
```