استنساخ الصوت

تتيح واجهة استنساخ الصوت البرمجية إنشاء أصوات مخصصة من عينات صوتية مرجعية، ومتابعة مراحل معالجتها، واستخدام معرّف الصوت الناتج في عمليات توليف الكلام.

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

تتطلب جميع نقاط نهاية استنساخ الصوت مصادقة عبر ترويسة Authorization القياسية:

Authorization: Bearer <API_KEY>

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

استنساخ صوت جديد

لإنشاء صوت مستنسخ جديد، أرسل طلباً بتنسيق multipart/form-data إلى مسار الأصوات:

POST /v1/voices
Content-Type: multipart/form-data

حقول النموذج

كائن التصنيفات الوصفية (labels)

يُمرر الحقل labels كنص بتنسيق JSON يحتوي على الخصائص التالية:

مثال على الطلب

curl -X POST "https://api.sawtakarabi.ai/v1/voices" \
  -H "Authorization: Bearer <API_KEY>" \
  -F "name=صوت مخصص" \
  -F 'labels={"dialect":"saudi-najdi","gender":"male","age":"middle","use_case":"conversational"}' \
  -F "description=صوت مستنسخ لتطبيقات المحادثة التفاعلية" \
  -F "files=@reference_audio.wav"

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

يُرجع الطلب الناجح رمز الحالة 201 Created مع كائن يتضمن معرّف الصوت المخصص وحالة الجاهزية الأولية:

{
  "object": "voice",
  "id": "7b8e62c1-9689-4a7b-a320-912b7a94f6f4",
  "status": "processing"
}

وفي حال إرسال عينة استرسال مع الطلب، تتضمن الاستجابة حقل continuation_status:

{
  "object": "voice",
  "id": "7b8e62c1-9689-4a7b-a320-912b7a94f6f4",
  "status": "processing",
  "continuation_status": "processing"
}

دورة حياة الجاهزية

تتم معالجة استنساخ الصوت بشكل غير متزامن. للتحقق من جاهزية الصوت للاستخدام، استعلم عن مورِد الصوت عبر معرّفه:

GET /v1/voices/{voice_id}
Authorization: Bearer <API_KEY>

حالات الجاهزية

يوضح الحقل status مرحلة معالجة الصوت:

عند رفع عينة استرسال، يتتبع الحقل continuation_status حالتها بشكل مستقل (processing أو ready أو failed). وإذا كانت حالة الصوت الأساسية ready، يمكن توليف الكلام به بنجاح حتى لو كانت عينة الاسترسال قيد المعالجة أو غير متوفرة.

استخدام معرّف الصوت في توليف الكلام

بمجرد وصول الصوت إلى حالة الجاهزية ready، مرّر معرّف الصوت (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": "مرحبا بك، هذا اختبار للصوت المستنسخ."
  }' \
  --output output.wav

معالجة الطلبات المبكرة

في حال محاولة توليف الكلام بصوت لا يزال في حالة المعالجة processing، يرفض المسار الطلب برمز الحالة 409 Conflict:

{
  "error": {
    "message": "Voice '<VOICE_ID>' is still processing. Its encode is retried on each request; poll GET /v1/voices/<VOICE_ID> for status.",
    "type": "invalid_request_error",
    "code": "voice_processing"
  }
}

يجب استطلاع المسار GET /v1/voices/{voice_id} دورياً حتى تتغير الحالة إلى ready قبل طلب التوليف.

التحكم في الاسترسال

بالنسبة للأصوات المنشأة مع عينة استرسال، يعتمد التوليف سياق الاسترسال تلقائياً، ويمكن تعطيل ذلك بتمرير "use_continuation": false في جسم طلب التوليف.

حالات التعافي وإدارة الموارد

مصفوفة الأخطاء وسبل المعالجة

تحديث البيانات الوصفية للصوت

يمكن تعديل اسم الصوت أو وصفه أو تصنيفاته الوصفية عبر المسار التالي:

PATCH /v1/voices/{voice_id}
Authorization: Bearer <API_KEY>
Content-Type: application/json

{
  "name": "اسم الصوت المعدل",
  "description": "وصف محدث للصوت",
  "labels": {
    "use_case": "narration"
  }
}

حذف الصوت

لحذف صوت مستنسخ نهائياً وتحرير سعة شاغرة ضمن الحد الأقصى لحسابك:

DELETE /v1/voices/{voice_id}
Authorization: Bearer <API_KEY>

يُرجع الحذف الناجح رمز الحالة 204 No Content.