---
title: الأصوات
description: اعثر على الصوت المناسب واستخدم معرّفه في الطلب.
---

تتيح واجهة الأصوات البرمجية البحث في دليل الأصوات وتصفيتها ومعاينة عيناتها الصوتية، واستخراج معرّف الصوت (`id`) المطلوب لتوليف الكلام.

## المصادقة ونطاقات الصلاحية

تعتمد صلاحية الوصول على كون الصوت عاماً أو خاصاً:

- **الأصوات العامة**: يمكن استعراضها ومعاينتها صوتياً دون مصادقة، مما يتيح تشغيل العينات الصوتية مباشرة في المتصفحات وتطبيقات العميل.
- **الأصوات الخاصة**: تتطلب تمرير مفتاح الواجهة البرمجية في ترويسة `Authorization` القياسية:

```http
Authorization: Bearer <API_KEY>
```

- **نطاق الصلاحية المطلوب**: يجب أن يتضمن المفتاح نطاق الصلاحية `voices` (أو أن يمتلك صلاحيات غير مقيدة). وإذا كان نطاق الصلاحية غير متوفر، تُرجع الواجهة رمز الحالة `403 Forbidden` وكود الخطأ `insufficient_scope`.

## استعراض قائمة الأصوات

استرجاع قائمة الأصوات المتاحة مع دعم تقسيم النتائج إلى صفحات.

```http
GET /v1/voices
```

### معاملات الاستعلام

جميع معاملات الاستعلام اختيارية:

| المعامل | النوع | القيمة الافتراضية | الوصف |
| :--- | :--- | :--- | :--- |
| `sort` | نص | `newest` | ترتيب النتائج. القيم المدعومة: `newest` (الأحدث)، `oldest` (الأقدم)، `most_liked` (الأكثر إعجاباً). إرسال أي قيمة أخرى يُرجع رمز الحالة `400` (`bad_request`). |
| `limit` | عدد صحيح | `25` | عدد الأصوات المسترجعة في الصفحة الواحدة. يجب أن يكون عدداً صحيحاً بين `1` و`100` (شاملاً). القيم خارج هذا النطاق تُرجع رمز الحالة `400` (`bad_request`). |
| `after` | نص | `null` | مؤشر ترقيم الصفحات المشفر المستلم من استجابة سابقة (`next_cursor`) لجلب الصفحة التالية. |
| `sharing_status` | نص | `null` | التصفية حسب حالة ظهور الصوت: `public` (عام) أو `private` (خاص). عند إهمال هذا المعامل، تُرجع الطلبات المصادق عليها أصوات المستخدم الخاصة بالإضافة إلى جميع الأصوات العامة، بينما تُرجع الطلبات غير المصادق عليها الأصوات العامة فقط. |
| `dialect` | نص | `null` | التصفية حسب وسم اللهجة. يمكن تكرار هذا المعامل عدة مرات في الطلب نفسه (مثال: `?dialect=saudi-najdi&dialect=eg-cairene`) لمطابقة أي من اللهجات المحددة. |
| `gender` | نص | `null` | التصفية حسب وسم الجنس (مثال: `male`، `female`، `neutral`). |
| `age` | نص | `null` | التصفية حسب وسم الفئة العمرية (مثال: `young`، `middle`، `old`). |
| `use_case` | نص | `null` | التصفية حسب وسم مجال الاستخدام (مثال: `conversational`، `narration`، `advertisement`). |
| `search` | نص | `null` | بحث غير حساس لحالة الأحرف عن نص جزئي يطابق اسم الصوت. |

### بنية الاستجابة

تُرجع نقطة النهاية كائن غلاف القائمة:

| الحقل | النوع | الوصف |
| :--- | :--- | :--- |
| `object` | نص | قيمته دائماً `"list"`. |
| `data` | مصفوفة | مصفوفة تحتوي على كائنات الأصوات المطابقة لمعايير الاستعلام. |
| `first_id` | نص أو null | معرّف (`id`) أول صوت في المصفوفة `data`، أو `null` إذا كانت القائمة فارغة. |
| `last_id` | نص أو null | معرّف (`id`) آخر صوت في المصفوفة `data`، أو `null` إذا كانت القائمة فارغة. |
| `has_more` | قيمة منطقية | توضح ما إذا كانت هناك صفحات إضافية متوفرة بعد الصفحة الحالية. |
| `next_cursor` | نص (اختياري) | مؤشر مشفر يُدرج عند تحقق `has_more: true`. يُمرر هذا المؤشر إلى المعامل `after` لجلب الصفحة التالية. |

## كائن الصوت

يتضمن كل عنصر داخل المصفوفة `data`، وكذلك استجابة المسار `GET /v1/voices/{voice_id}`، الحقول التالية:

| الحقل | النوع | الوصف |
| :--- | :--- | :--- |
| `object` | نص | قيمته دائماً `"voice"`. |
| `id` | نص | المعرّف الفريد للصوت. يُمرر هذا المعرّف كقيمة للمعامل `voice` في طلبات توليف الكلام. |
| `name` | نص | الاسم المعروض للصوت. |
| `status` | نص | حالة جاهزية الصوت: `"ready"` (جاهز)، `"processing"` (قيد المعالجة)، أو `"failed"` (فشل). تُستخدم الأصوات ذات الحالة `"ready"` فقط في توليف الكلام. |
| `labels` | كائن | بيانات التصنيف الوصفية وتشمل قيم النصوص: `dialect` (اللهجة)، `gender` (الجنس)، `age` (الفئة العمرية)، و`use_case` (مجال الاستخدام). |
| `preview_url` | نص | رابط استدعاء العينة الصوتية لهذا الصوت (`/v1/voices/{id}/preview`). |
| `sharing` | كائن | بيانات الظهور وتشمل `status` (إما `"public"` أو `"private"`) و`liked_by_count` (عدد الإعجابات كعدد صحيح). |
| `created_at` | نص | الطابع الزمني لإنشاء الصوت بتنسيق ISO 8601 وفق التوقيت العالمي المنسق (UTC). |
| `description` | نص (اختياري) | وصف نصي للصوت عند توفره. |
| `preview_text` | نص (اختياري) | النص المنطوق المستخدم في العينة الصوتية عند توفره. |
| `continuation_status` | نص (اختياري) | حالة معالجة بيانات الاسترسال (`"ready"` أو `"processing"` أو `"failed"`)، وتظهر فقط في الأصوات التي أُنشئت مع عينة استرسال. |

## جلب بيانات صوت محدد

استرجاع بيانات وحالة صوت محدد باستخدام معرّفه.

```http
GET /v1/voices/{voice_id}
```

### صلاحيات الوصول والظهور

- يُرجع كائن الصوت إذا كان الصوت عاماً أو كان مملوكاً للمستخدم صاحب الطلب المصادق عليه.
- إذا كان الصوت غير موجود، أو كان صوتاً خاصاً ينتمي إلى حساب آخر، يُرجع المسار رمز الحالة `404 Not Found` (`voice_not_found`). لا يمكن تمييز الأصوات الخاصة التابعة للحسابات الأخرى عن الأصوات غير الموجودة.

## معاينة العينة الصوتية

الاستماع إلى عينة صوتية مسجلة مسبقاً للصوت قبل اعتماده في التوليف.

```http
GET /v1/voices/{voice_id}/preview
```

### مواصفات وترويسات العينة الصوتية

- **صيغة الصوت**: WAV القياسية (`audio/wav`).
- **التخزين المؤقت**: `Cache-Control: public, max-age=300`.
- **الأصوات العامة**: يُسمح بالوصول إليها دون مصادقة لتتمكن مشغلات الويب وتطبيقات العميل من تشغيل العينة مباشرة.
- **الأصوات الخاصة**: تتطلب مفتاح واجهة برمجية مصادقاً عليه يتضمن نطاق الصلاحية `voices` وتعود ملكيته لصاحب الصوت.
- **حد معدل الطلبات**: تقتصر طلبات المعاينة غير المصادق عليها على `60` طلباً في الدقيقة لكل عنوان IP. وفي حال تجاوز هذا الحد، يُرجع المسار رمز الحالة `429 Too Many Requests` مع الترويسة `Retry-After: 60`.

## اختيار الصوت لتوليف الكلام

لتوليف الكلام باستخدام صوت محدد:

1. **البحث عن صوت**: استدعاء `GET /v1/voices` مع تحديد تصفيات اللهجة أو الجنس أو مجال الاستخدام المناسبة.
2. **التحقق من الجاهزية**: التأكد من أن كائن الصوت يحمل الحالة `"status": "ready"`. لا يمكن توليف الكلام باستخدام أصوات بحالة `"processing"` أو `"failed"`.
3. **الاستماع إلى العينة**: معاينة الصوت عبر الرابط `preview_url` أو عبر المسار `GET /v1/voices/{voice_id}/preview` لتقييم جودته وملاءمته.
4. **إرسال طلب التوليف**: تمرير معرّف الصوت (`id`) في الحقل `voice` ضمن طلب توليف الكلام:

```bash
curl -X POST "https://api.sawtakarabi.ai/v1/audio/speech" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "arabic-tts-1",
    "voice": "<VOICE_ID>",
    "input": "مرحبا بك",
    "response_format": "wav"
  }' \
  --output speech.wav
```

إذا أُهمل المعامل `voice`، يعتمد مسار توليف الكلام الصوت الافتراضي للنظام.

## مرجع الأخطاء

تُرجع واجهة الأصوات البرمجية استجابات الأخطاء القياسية التالية:

| رمز الحالة | كود الخطأ | الوصف |
| :--- | :--- | :--- |
| `400 Bad Request` | `bad_request` | معامل غير صالح، مثل قيمة غير مدعومة للمعامل `sort`، أو قيمة `limit` خارج النطاق `1`..`100`، أو مؤشر ترقيم صفحات غير صالح، أو قيمة غير صحيحة للمعامل `sharing_status`. |
| `401 Unauthorized` | `auth_missing` / `auth_failed` | غياب مفتاح الواجهة البرمجية أو عدم صلاحيته عند محاولة الوصول إلى أصوات خاصة. |
| `403 Forbidden` | `insufficient_scope` | مفتاح الواجهة البرمجية لا يتضمن نطاق الصلاحية المطلوب `voices`. |
| `404 Not Found` | `voice_not_found` | معرّف الصوت غير موجود، أو لا يحتوي على عينة معاينة صوتية، أو يعود لصوت خاص يملكه حساب آخر. |
| `429 Too Many Requests` | `rate_limit_error` | تجاوز حد معدل طلبات المعاينة المحدد بـ 60 طلباً في الدقيقة لكل عنوان IP. راجع ترويسة `Retry-After`. |
| `503 Service Unavailable` | `voices_unconfigured` | خدمة دليل الأصوات غير مهيأة أو غير متوفرة حالياً. |