الأصوات

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

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

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

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

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

Authorization: Bearer <API_KEY>

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

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

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

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"`)، وتظهر فقط في الأصوات التي أُنشئت مع عينة استرسال.

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

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

GET /v1/voices/{voice_id}

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

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

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

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

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.

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

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

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

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`	خدمة دليل الأصوات غير مهيأة أو غير متوفرة حالياً.

الأصوات

في هذه الصفحة