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

# إنشاء كلام

> ينشئ صوتًا من النص المُدخل

## نص الطلب

**مهلة الطلبات المتزامنة:** ينتظر هذا الـ endpoint غير الخاص بالمحادثة حتى ينتهي النموذج الذي تم التوجيه إليه. قد تتجاوز المدخلات الكبيرة أو الصوت الطويل أو الدُفعات الكبيرة القيمة الافتراضية الشائعة للعميل وهي 30s، لذا اضبط مهلة عميل HTTP على `120s` على الأقل.

تختلف الحقول الاختيارية حسب عائلة النموذج. يتحقق TokenLab من مصفوفة الحقول قبل التوجيه: تقبل نماذج OpenAI TTS الحقول `voice` و`instructions` و`response_format` و`stream_format` و`speed`؛ وتقبل نماذج MiniMax speech الحقول `voice` و`voice_id` و`response_format` و`stream_format` و`speed`؛ وتقبل نماذج Gemini TTS الحقول `prompt` و`language_code` و`voice` و`response_format` و`stream_format` و`speed` و`temperature`؛ وقد تقبل مسارات TTS الأضيق من نوع Vidu/Kling الحقلين `input` و`stream_format` فقط. الحقول العلوية غير المعروفة، بما في ذلك `user`، ترجع `400 unsupported_parameter` بدلًا من تجاهلها.

<ParamField body="model" type="string" default="tts-1">
  نموذج TTS. تشمل الأمثلة `tts-1` و`gpt-4o-mini-tts` و`speech-02-hd` و`gemini-2.5-flash-tts`. استخدم `GET /v1/models?recommended_for=tts` للحصول على القائمة الحالية.
</ParamField>

<ParamField body="input" type="string" required>
  النص المطلوب إنشاء صوت له. الحد الأقصى 4096 حرفًا.
</ParamField>

<ParamField body="voice" type="string | object">
  محدد الصوت. مرر اسم صوت مدمج مثل `nova`، أو صوت Gemini مثل `Kore`، أو كائنًا مثل `{ "id": "voice-id" }` للأصوات المخصصة المتوافقة.
</ParamField>

<ParamField body="voice_id" type="string">
  محدد الصوت الأصلي للمزوّد لنماذج speech المتوافقة مع MiniMax.
</ParamField>

<ParamField body="instructions" type="string">
  تعليمات اختيارية للأسلوب أو الإلقاء لنماذج TTS المتوافقة مع OpenAI التي تدعمها.
</ParamField>

<ParamField body="prompt" type="string">
  Prompt اختياري لأسلوب الإلقاء في نماذج Gemini TTS.
</ParamField>

<ParamField body="language_code" type="string">
  رمز لغة اختياري، مثل `en-US`، لمسارات Gemini وxAI وTTS المتوافقة.
</ParamField>

<ParamField body="response_format" type="string">
  تنسيق الصوت. تشمل القيم الشائعة `mp3` و`opus` و`aac` و`flac` و`wav` و`pcm`؛ تختلف القيم المدعومة حسب عائلة النموذج.
</ParamField>

<ParamField body="stream_format" type="string" default="audio">
  تنسيق التسليم في TokenLab: `audio` أو `sse`. لا يدعم `tts-1` و`tts-1-hd` القيمة `stream_format=sse`.
</ParamField>

<ParamField body="speed" type="number">
  سرعة الكلام لعائلات النماذج التي تدعمها (من 0.25 إلى 4.0).
</ParamField>

<ParamField body="temperature" type="number">
  درجة حرارة العينة لمسارات Gemini-compatible TTS (من 0 إلى 2).
</ParamField>

## الاستجابة

يعيد ملف الصوت بالتنسيق المطلوب.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.tokenlab.sh/v1/audio/speech" \
    -H "Authorization: Bearer sk-your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "tts-1-hd",
      "voice": "nova",
      "input": "Hello, welcome to TokenLab!"
    }' \
    --output speech.mp3
  ```

  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="sk-your-api-key",
      base_url="https://api.tokenlab.sh/v1"
  )

  response = client.audio.speech.create(
      model="tts-1-hd",
      voice="nova",
      input="Hello, welcome to TokenLab!"
  )

  response.stream_to_file("speech.mp3")
  ```

  ```javascript JavaScript theme={null}
  import OpenAI from 'openai';
  import fs from 'fs';

  const client = new OpenAI({
    apiKey: 'sk-your-api-key',
    baseURL: 'https://api.tokenlab.sh/v1'
  });

  const response = await client.audio.speech.create({
    model: 'tts-1-hd',
    voice: 'nova',
    input: 'Hello, welcome to TokenLab!'
  });

  const buffer = Buffer.from(await response.arrayBuffer());
  fs.writeFileSync('speech.mp3', buffer);
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://api.tokenlab.sh/v1/audio/speech');

  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          'Content-Type: application/json',
          'Authorization: Bearer sk-your-api-key'
      ],
      CURLOPT_POSTFIELDS => json_encode([
          'model' => 'tts-1-hd',
          'voice' => 'nova',
          'input' => 'Hello, welcome to TokenLab!'
      ])
  ]);

  $audio = curl_exec($ch);
  curl_close($ch);

  file_put_contents('speech.mp3', $audio);
  ```
</RequestExample>

## عينات الأصوات

| الصوت     | الوصف                       |
| --------- | --------------------------- |
| `alloy`   | محايد، متوازن               |
| `ash`     | هادئ، متزن                  |
| `ballad`  | لحني، تعبيري                |
| `coral`   | دافئ، جذاب                  |
| `echo`    | دافئ، حواري                 |
| `fable`   | تعبيري، سردي                |
| `nova`    | ودود، واضح                  |
| `onyx`    | عميق، موثوق                 |
| `sage`    | حكيم، متأمل                 |
| `shimmer` | ناعم، لطيف                  |
| `verse`   | ديناميكي، متعدد الاستخدامات |

## مثال الاستجابة

<ResponseExample>
  ```binary 200 OK theme={null}
  <binary audio data>
  ```
</ResponseExample>

## حقول مهمة

<ResponseField name="Content-Type" type="string">نوع الحدث أو الرسالة الذي تعيده API.</ResponseField>
<ResponseField name="body" type="binary">جسم الاستجابة الخام. احفظه مباشرة ولا تحلله كـ JSON.</ResponseField>