> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

> استنسخ صوتًا من عينة صوتية مرجعية قصيرة باستخدام Chatterbox HD، ثم أنشئ كلامًا من خلال Venice Audio API.

يتيح لك استنساخ الصوت إنشاء كلام بصوتٍ توفّره عينة صوتية مرجعية قصيرة. باستخدام `tts-chatterbox-hd`، ارفع عينة إلى `/audio/voices`، واحفظ معرّف الصوت `vv_...` المُعاد، ثم مرّر هذا المعرّف إلى `/audio/speech`.

<Note>
  معرّفات الصوت مرتبطة بنموذج محدد. يجب استخدام المعرّف الذي أُنشئ باستخدام `tts-chatterbox-hd` مع `tts-chatterbox-hd` فقط.
</Note>

## كيف يعمل

1. **الرفع** - أرسل ملفًا صوتيًا مرجعيًا نظيفًا إلى `POST /audio/voices`
2. **الحفظ** - خزّن معرّف الصوت `id` المُعاد
3. **الإنشاء** - أرسل المعرّف بوصفه `voice` في `POST /audio/speech`

## المتطلبات الأساسية

* مفتاح Venice API
* عينة مرجعية نظيفة بصيغة MP3 أو WAV أو FLAC أو M4A
* ما لا يقل عن 5 إلى 10 ثوانٍ من كلامٍ واضح لمتحدثٍ واحد

عيّن مفتاح API الخاص بك:

```bash theme={"system"}
export VENICE_API_KEY="your-api-key"
```

## الخطوة 1: رفع عينة صوت

أنشئ معرّف صوت برفع الملف الصوتي المرجعي بصيغة multipart form data:

```bash theme={"system"}
curl https://api.venice.ai/api/v1/audio/voices \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "model=tts-chatterbox-hd" \
  -F "file=@./reference-voice.wav"
```

**الاستجابة (200):**

```json theme={"system"}
{
  "id": "vv_voice_abc123xyz",
  "model": "tts-chatterbox-hd"
}
```

احفظ `id` لاستخدامه في إنشاء الكلام:

```bash theme={"system"}
export VENICE_VOICE_ID="vv_voice_abc123xyz"
```

## الخطوة 2: إنشاء الكلام

مرّر معرّف الصوت المستنسخ بوصفه `voice` في طلب الكلام:

```bash theme={"system"}
curl https://api.venice.ai/api/v1/audio/speech \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-chatterbox-hd",
    "voice": "'"$VENICE_VOICE_ID"'",
    "input": "Hello from Venice. This audio is generated with a cloned Chatterbox HD voice.",
    "response_format": "mp3"
  }' \
  --output chatterbox-clone.mp3
```

تكون استجابة الجسم صوتًا ثنائيًا بالصيغة المطلوبة.

***

## مثال كامل

يرفع هذا المثال عينةً مرجعية، ويستخرج معرّف الصوت باستخدام `jq`، ويكتب الصوت المُنشأ إلى `chatterbox-clone.mp3`:

```bash theme={"system"}
VOICE_ID=$(
  curl -s https://api.venice.ai/api/v1/audio/voices \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -F "model=tts-chatterbox-hd" \
    -F "file=@./reference-voice.wav" | jq -r '.id'
)

curl https://api.venice.ai/api/v1/audio/speech \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-chatterbox-hd",
    "voice": "'"$VOICE_ID"'",
    "input": "This is a complete Chatterbox HD voice cloning example.",
    "response_format": "mp3",
    "speed": 1
  }' \
  --output chatterbox-clone.mp3
```

## نصائح حول عينة الصوت

استخدم عينةً بمتحدثٍ واحد وضوضاء خلفية قليلة وبدون موسيقى. الكلام الطبيعي يعمل أفضل من الصوت المهموس أو المُغنّى أو المُعالَج بكثافة.

قد تساعد العينات الأطول عندما يتميز الصوت بإيقاعٍ أو لكنةٍ أو نبرةٍ مميزة، لكن احرص على إبقاء العينة مُركّزة على المتحدث المستهدف.

## انتهاء صلاحية المعرّف

استنساخ Chatterbox HD يعتمد على نهج zero-shot: تخزّن Venice الملف الصوتي المرجعي المرفوع مؤقتًا، ويقرأه النموذج عند توليد الكلام. لا يُنشأ أي قالب صوتي دائم.

تنتهي صلاحية معرّفات الصوت تلقائيًا بعد 7 أيام. بعد انتهاء صلاحية المعرّف، ارفع العينة المرجعية مرةً أخرى لإنشاء معرّف `vv_...` جديد.

## اكتشاف دعم الاستنساخ

تتضمن النماذج التي تدعم الاستنساخ كائن `voice_cloning` ضمن مواصفات النموذج. استعلم عن نماذج TTS للتحقق من الصيغ المدعومة والحد الأدنى لطول العينة ومدة الاحتفاظ:

```bash theme={"system"}
curl "https://api.venice.ai/api/v1/models?type=tts" \
  -H "Authorization: Bearer $VENICE_API_KEY"
```

يُعلن `tts-chatterbox-hd` عن:

```json theme={"system"}
{
  "voice_cloning": {
    "mode": "zero_shot",
    "accepted_formats": ["mp3", "wav", "flac", "m4a"],
    "min_sample_seconds": 5,
    "retention_days": 7
  }
}
```

***

## معاملات API

### إنشاء صوت

| الحقل   | النوع  | مطلوب | الوصف                                                     |
| ------- | ------ | ----- | --------------------------------------------------------- |
| `model` | string | نعم   | يجب أن يكون `tts-chatterbox-hd`                           |
| `file`  | file   | نعم   | عينة صوتية مرجعية. الصيغ المدعومة هي MP3 وWAV وFLAC وM4A. |

### إنشاء الكلام

| الحقل             | النوع   | مطلوب | الافتراضي | الوصف                                                           |
| ----------------- | ------- | ----- | --------- | --------------------------------------------------------------- |
| `model`           | string  | نعم   | -         | يجب أن يطابق النموذج المستخدم لإنشاء معرّف الصوت                |
| `voice`           | string  | نعم   | -         | معرّف `vv_...` الذي يُعيده `POST /audio/voices`                 |
| `input`           | string  | نعم   | -         | النص المراد توليده، حتى 4096 حرفًا                              |
| `response_format` | string  | لا    | `mp3`     | `mp3` أو `opus` أو `aac` أو `flac` أو `wav` أو `pcm`            |
| `speed`           | number  | لا    | `1`       | سرعة الكلام من `0.25` إلى `4.0`                                 |
| `temperature`     | number  | لا    | -         | درجة حرارة العيّنة من `0` إلى `2`. القيم الأعلى قد تضيف تنوعًا. |
| `streaming`       | boolean | لا    | `false`   | بث الصوت جملةً جملة                                             |

## الأخطاء الشائعة

| الحالة | السبب                                        | الحل                                                                            |
| ------ | -------------------------------------------- | ------------------------------------------------------------------------------- |
| `400`  | حاوية صوت غير مدعومة أو معرّف صوت غير متوافق | استخدم MP3 أو WAV أو FLAC أو M4A، واقرن المعرّف بالنموذج نفسه المستخدم لإنشائه. |
| `401`  | مفتاح API مفقود أو غير صالح                  | أرسل `Authorization: Bearer $VENICE_API_KEY`.                                   |
| `402`  | الرصيد غير كافٍ                              | اشحن رصيدك في Venice.                                                           |
| `413`  | الملف المرفوع كبير جدًا                      | استخدم عينة مرجعية أقصر أو أكثر ضغطًا.                                          |
| `429`  | تم تجاوز حد المعدل                           | أعد المحاولة بعد إعادة ضبط نافذة حد المعدل.                                     |