---
title: استنساخ الصوت
description: أنشئ صوتاً مستنسخاً مصرّحاً به واستخدمه عبر واجهة برمجة التطبيقات.
---

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

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

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

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

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

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

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

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

### حقول النموذج

| الحقل | النوع | مطلوب | الوصف |
| :--- | :--- | :--- | :--- |
| `files` | ملف صوتي | نعم | الملف الصوتي المرجعي. يجب إرسال ملف صوتي واحد فقط في هذا الحقل. |
| `name` | نص | نعم | الاسم المعروض للصوت المستنسخ. |
| `labels` | نص (JSON) | نعم | كائن مشفر بتنسيق JSON يحتوي على بيانات التصنيف الوصفية، ويجب أن يشتمل على الحقل `dialect`. |
| `description` | نص | لا | وصف اختياري للصوت (بحد أقصى 180 حرفاً). |
| `continuation_file` | ملف صوتي | لا | عينة صوتية إضافية اختيارية لتحديد نمط الأداء والاسترسال. يجب إرسالها مقترنة بالحقل `continuation_text`. |
| `continuation_text` | نص | لا | النص المنطوق المطابق تماماً لملف `continuation_file`. يجب إرساله مقترناً بملف الاسترسال. |

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

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

| الخاصية | النوع | مطلوبة | الوصف |
| :--- | :--- | :--- | :--- |
| `dialect` | نص | نعم | معرّف اللهجة المعتمدة، ويجب أن يطابق إحدى اللهجات المدعومة. |
| `gender` | نص | لا | جنس الصوت. القيم المقبولة: `male` (ذكر)، `female` (أنثى)، `neutral` (محايد). القيمة الافتراضية: `male`. |
| `age` | نص | لا | الفئة العمرية. القيم المقبولة: `young` (شاب)، `middle` (متوسط)، `old` (متقدم). القيمة الافتراضية: `middle`. |
| `use_case` | نص | لا | مجال الاستخدام. القيم المقبولة: `conversational` (محادثة)، `narration` (سرد)، `advertisement` (إعلانات)، أو نص فارغ `""` (الافتراضي). |

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

```bash
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` مع كائن يتضمن معرّف الصوت المخصص وحالة الجاهزية الأولية:

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

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

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

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

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

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

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

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

| الحالة | الوصف |
| :--- | :--- |
| `processing` | المقطع الصوتي قيد المعالجة حالياً. لا يمكن استخدام الصوت في التوليف أثناء هذه الحالة. |
| `ready` | اكتملت المعالجة بنجاح. أصبح معرّف الصوت جاهزاً لتوليف الكلام. |
| `failed` | تعذرت معالجة العينة الصوتية، ولا يمكن استخدام الصوت. |

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

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

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

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

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

```json
{
  "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` في جسم طلب التوليف.

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

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

| رمز الحالة | كود الخطأ | السبب وطريقة التعافي |
| :--- | :--- | :--- |
| `400 Bad Request` | `bad_request` | بنية غير صالحة لطلب `multipart`، أو غياب الملف الصوتي، أو إرسال أكثر من ملف في الحقل `files`، أو ملف صوتي فارغ، أو نص غير صالح في `labels`، أو غياب `dialect` أو كونه غير مدعوم، أو قيم غير مقبولة في التصنيفات، أو تجاوز الوصف 180 حرفاً، أو عدم دعم تنسيق الصوت. تحقق من الحقول وأعد إرسال الطلب. |
| `400 Bad Request` | `continuation_pair` | إرسال `continuation_file` دون `continuation_text` أو العكس. يجب إرسال الحقلين معاً كزوج متكامل. |
| `401 Unauthorized` | `auth_missing` / `auth_failed` | مفتاح الواجهة البرمجية مفقود أو غير صالح. تأكد من ترويسة `Authorization`. |
| `402 Payment Required` | `insufficient_balance` | الرصيد المالي في الحساب غير كافٍ لإتمام عملية الاستنساخ. اشحن رصيد الحساب ثم أعد المحاولة. |
| `403 Forbidden` | `insufficient_scope` | المفتاح يفتقر لنطاق الصلاحية `voices`. استخدم مفتاحاً يتضمن الصلاحية المطلوبة. |
| `404 Not Found` | `voice_not_found` | معرّف الصوت غير موجود أو يعود لحساب آخر. |
| `409 Conflict` | `voice_limit_reached` | وصل الحساب إلى الحد الأقصى المسموح به من الأصوات. احذف صوتاً موجوداً لتتمكن من استنساخ صوت جديد. |
| `409 Conflict` | `voice_processing` | محاولة توليف الكلام قبل اكتمال معالجة الصوت. استطلع حالة الصوت حتى تصبح `ready`. |
| `413 Payload Too Large` | `clip_too_large` | حجم العينة الصوتية المرفوعة يتجاوز الحد الأقصى المسموح به. قلّص حجم الملف وأعد المحاولة. |
| `503 Service Unavailable` | `voices_unconfigured` / `storage_unavailable` | خدمة الأصوات أو خدمة التخزين غير متوفرة مؤقتاً. أعد المحاولة لاحقاً. |

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

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

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

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

### حذف الصوت

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

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

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