> ## 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.

# الموسيقى والمؤثرات الصوتية

> ولِّد الموسيقى والمؤثرات الصوتية باستخدام واجهة برمجة تطبيقات الصوت غير المتزامنة من Venice: اختر نموذجًا، واحصل على عرض سعر للتكلفة، وضع مهمة في قائمة الانتظار، ثم نزّل الصوت المكتمل.

توليد الموسيقى والمؤثرات الصوتية غير متزامن. اختر نموذجًا، واطلب عرض سعر، وضع عملية التوليد في قائمة الانتظار، ثم استعلم دوريًا إلى أن تُعيد Venice ملف الصوت النهائي.

## اختيار نموذج

تصفَّح [نماذج الموسيقى والمؤثرات الصوتية](/models/music) للاطلاع على معرّفات النماذج الحالية والأسعار وحدود المدة والميزات المدعومة.

يمكنك أيضًا استكشاف قدرات النماذج في وقت التشغيل:

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

راجع بيانات كل نموذج التعريفية قبل تعيين الحقول الاختيارية مثل `duration_seconds` أو `lyrics_prompt` أو `force_instrumental` أو `loop`. الحقول غير المدعومة تؤدي إلى استجابة HTTP `400`.

## سير عملية التوليد

| نقطة النهاية                                                     | الغرض                                       |
| ---------------------------------------------------------------- | ------------------------------------------- |
| [`POST /audio/quote`](/api-reference/endpoint/audio/quote)       | تقدير تكلفة التوليد بالدولار الأمريكي       |
| [`POST /audio/queue`](/api-reference/endpoint/audio/queue)       | بدء توليد موسيقى أو مؤثر صوتي               |
| [`POST /audio/retrieve`](/api-reference/endpoint/audio/retrieve) | استعلام دوري عن المهمة وتنزيل الصوت المكتمل |
| [`POST /audio/complete`](/api-reference/endpoint/audio/complete) | حذف الوسائط المُخزَّنة بعد تنزيلها          |

## 1. احصل على عرض سعر

اطلب عرض سعر للطلب قبل توليد الوسائط. أدرج النموذج والمدة نفسيهما اللذين تعتزم إرسالهما إلى نقطة نهاية قائمة الانتظار.

```bash theme={"system"}
curl https://api.venice.ai/api/v1/audio/quote \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs-music",
    "duration_seconds": 30
  }'
```

تحتوي الاستجابة على التكلفة المقدَّرة بالدولار الأمريكي:

```json theme={"system"}
{
  "quote": 0.75
}
```

## 2. ضع عملية التوليد في قائمة الانتظار

<CodeGroup>
  ```bash Music theme={"system"}
  curl https://api.venice.ai/api/v1/audio/queue \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "elevenlabs-music",
      "prompt": "Warm cinematic strings with a gentle piano melody, hopeful and spacious",
      "duration_seconds": 30,
      "force_instrumental": true
    }'
  ```

  ```bash Sound effect theme={"system"}
  curl https://api.venice.ai/api/v1/audio/queue \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "elevenlabs-sound-effects-v2",
      "prompt": "Ocean waves rolling onto a pebble beach at night",
      "duration_seconds": 10
    }'
  ```
</CodeGroup>

يُعيد الطلب الناجح النموذج ومعرّف قائمة الانتظار:

```json theme={"system"}
{
  "model": "elevenlabs-music",
  "queue_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "QUEUED"
}
```

احفظ كلًّا من `model` و`queue_id`؛ فنقطتا نهاية الاسترجاع والإكمال تتطلبانهما.

## 3. الاستعلام الدوري والتنزيل

استدعِ `/audio/retrieve` بالقيم المُستلمة من استجابة قائمة الانتظار:

```bash theme={"system"}
curl https://api.venice.ai/api/v1/audio/retrieve \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs-music",
    "queue_id": "123e4567-e89b-12d3-a456-426614174000"
  }' \
  --output response.bin
```

افحص `Content-Type` في الاستجابة:

| Content-Type                                | المعنى                       | الإجراء                                       |
| ------------------------------------------- | ---------------------------- | --------------------------------------------- |
| `application/json`                          | لا يزال التوليد قيد المعالجة | اقرأ حقول التوقيت، وانتظر، ثم استعلم مرة أخرى |
| `audio/mpeg` أو `audio/wav` أو `audio/flac` | اكتمل التوليد                | احفظ الجسم الثنائي بالامتداد المطابق          |

تبدو استجابة المعالجة كما يلي:

```json theme={"system"}
{
  "status": "PROCESSING",
  "average_execution_time": 20000,
  "execution_duration": 5200
}
```

كلا قيمتَي التوقيت بالميلي ثانية.

## مثال كامل

يضع مثال Python هذا موسيقى آلية في قائمة الانتظار، ويستعلم دوريًا كل خمس ثوانٍ، ويحفظ النتيجة بامتداد يستند إلى نوع المحتوى.

```python theme={"system"}
import os
import time
from pathlib import Path

import requests

BASE_URL = "https://api.venice.ai/api/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
    "Content-Type": "application/json",
}

generation = {
    "model": "elevenlabs-music",
    "prompt": "Warm cinematic strings with a gentle piano melody, hopeful and spacious",
    "duration_seconds": 30,
    "force_instrumental": True,
}

quote = requests.post(f"{BASE_URL}/audio/quote", json={
    "model": generation["model"],
    "duration_seconds": generation["duration_seconds"],
})
quote.raise_for_status()
print(f"Estimated cost: ${quote.json()['quote']:.2f}")

queued = requests.post(f"{BASE_URL}/audio/queue", headers=HEADERS, json=generation)
queued.raise_for_status()
job = queued.json()

content_type_to_extension = {
    "audio/mpeg": ".mp3",
    "audio/wav": ".wav",
    "audio/flac": ".flac",
}

while True:
    result = requests.post(
        f"{BASE_URL}/audio/retrieve",
        headers=HEADERS,
        json={"model": job["model"], "queue_id": job["queue_id"]},
    )
    result.raise_for_status()
    content_type = result.headers.get("Content-Type", "").split(";")[0]

    if content_type in content_type_to_extension:
        output = Path("generated-audio" + content_type_to_extension[content_type])
        output.write_bytes(result.content)
        print(f"Saved {output}")
        break

    status = result.json()
    print(f"Status: {status['status']}")
    time.sleep(5)

requests.post(
    f"{BASE_URL}/audio/complete",
    headers=HEADERS,
    json={"model": job["model"], "queue_id": job["queue_id"]},
).raise_for_status()
```

<Note>
  لا تتطلب نقطة نهاية عرض السعر مصادقة، لكن طلبات قائمة الانتظار والاسترجاع والإكمال تتطلبها.
</Note>

## نصائح لكتابة المطالبات

* بالنسبة للموسيقى، صِف النوع والآلات والمزاج والإيقاع والبنية وما إذا كانت الأصوات مطلوبة.
* بالنسبة للمؤثرات الصوتية، صِف المصدر والبيئة والشدة والتوقيت ومنظور الاستماع.
* استخدم `lyrics_prompt` فقط عندما يدعم النموذج المُختار كلمات الأغاني.
* استخدم `force_instrumental` أو `loop` فقط عندما تُفيد بيانات النموذج التعريفية بدعمهما.

## موارد ذات صلة

* [نماذج الموسيقى والمؤثرات الصوتية](/models/music)
* [واجهة برمجة تطبيقات وضع الصوت في قائمة الانتظار](/api-reference/endpoint/audio/queue)
* [واجهة برمجة تطبيقات استرجاع الصوت](/api-reference/endpoint/audio/retrieve)