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

# توليد الموسيقى

> إنشاء مهام الموسيقى أو الكلمات، الاستطلاع للحصول على الصوت النهائي، وتخزين مخرجات الموسيقى الموجهة للمستخدم بشكل آمن.

توليد الموسيقى غير متزامن. `POST /v1/music/generations` ينشئ مهمة TokenLab عامة ويعيد `id` / `task_id`، `status`، وعادةً `poll_url`. يجب على تطبيقك تخزين هوية تلك المهمة، عرض التقدم، والاستطلاع حتى الوصول إلى حالة نهائية.

## اختر سير العمل

| سير العمل                     | الحقول الرئيسية                                               | ملاحظات                                                        |
| ----------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------- |
| أغنية كاملة أو موسيقى تصويرية | `model`, `prompt`, `title` اختياري، `tags`, `action: "MUSIC"` | استخدم عندما يتوقع المستخدم صوتًا نهائيًا                      |
| كلمات فقط                     | `model`, `prompt`, `action: "LYRICS"`                         | استخدم فقط مع النماذج التي تعرض توليد الكلمات                  |
| متابعة مقطع موجود             | `continue_clip_id`, `continue_at` اختياري                     | قم بتخزين هوية المقطع/المهمة العامة السابقة قبل تقديم المتابعة |

استعلم عن كتالوج النموذج الحالي قبل شحن قائمة نماذج مشفرة:

```bash theme={null}
curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
  -H "Authorization: Bearer sk-your-api-key"
```

تستخدم الأمثلة العامة الحالية `suno_music` لتوليد الموسيقى. بالنسبة لتدفقات الكلمات فقط، أرسل `action: "LYRICS"` مع نموذج وثائقه العامة توثق توليد الكلمات. اعتبر معرفات النماذج كمعرفات TokenLab العامة، وليس كضمان أن الحقول الخاصة بالمزود هي حقول عقد عامة.

## إنشاء مهمة موسيقية

```bash theme={null}
curl https://api.tokenlab.sh/v1/music/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno_music",
    "prompt": "مقطوعة موسيقية مبهجة من نوع الساينث بوب مع أصوات دافئة وكورس نظيف",
    "title": "صوت الصباح",
    "tags": "ساينث بوب، مبهج",
    "action": "MUSIC"
  }'
```

احتفظ بالمطالبات، العناوين، والوسوم مرئية للمستخدم وآمنة للتخزين. لا تضع مفاتيح API، روابط خاصة، أو معلومات توجيه داخلية في أي حقل من حقول المطالبات.

## الاستطلاع من أجل الاكتمال

استخدم `poll_url` أولاً. إذا كان عميلك يحتاج إلى مسار ثابت، اتصل بـ `GET /v1/tasks/{id}` مع `id` أو `task_id` المعاد.

```bash theme={null}
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"
```

الحالات العامة المتوقعة هي `pending`، `processing`، `completed`، و`failed`. يمكن أن تتضمن مهمة الموسيقى المكتملة `audio_url`، `video_url`، `title`، `lyrics`، وبيانات وصفية موحدة. قم بتخزين الروابط النهائية في قاعدة بياناتك الخاصة حتى يتمكن المستخدم من إعادة فتح النتيجة دون إعادة بدء التوليد.

## واجهة المستخدم ومعالجة الحالة

* عرض حالة الانتظار مباشرة بعد إنشاء المهمة.
* الاستطلاع كل `5-10s` للمهام الطويلة، ثم التوقف عند `completed` أو `failed`.
* لا تعرض مشغلًا نهائيًا حتى تكون المهمة `completed` ويوجد `audio_url`.
* بالنسبة لمهام الكلمات فقط، قم بعرض مخرجات النص بشكل منفصل عن مهام الصوت حتى يفهم المستخدمون ما يشترونه.
* عند التحديث، استأنف من `task_id` المخزنة بدلاً من إنشاء مهمة جديدة.

## الفوترة والتسوية

يمكن لمهام الموسيقى حجز مبلغ تقديري عند الإنشاء والتسوية بعد معرفة الحالة النهائية. قم بتخزين `request_id`، `task_id`، النموذج، نقطة النهاية، و`billing_transaction_id` عند ظهوره. استخدم سجلات استخدام واجهة إدارة API للتسوية بدلاً من معرفات مهام المزود.

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

| العرض                             | السبب المحتمل                                            | الحل                                                                                                 |
| --------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| تم إنشاء المهمة ولكن لا يوجد مشغل | المهمة لا تزال في حالة انتظار أو اكتملت بدون `audio_url` | استمر في الاستطلاع حتى الوصول إلى الحالة النهائية، ثم تعامل مع المخرجات المفقودة كوظيفة مستخدم فاشلة |
| أغاني مكررة بعد التحديث           | أعادت واجهة المستخدم إنشاء المهمة بدلاً من الاستئناف     | احتفظ وكرر استخدام `task_id`                                                                         |
| مهمة الكلمات لا تعيد صوتًا        | `action: "LYRICS"` هو نص فقط                             | فصل مسارات واجهة المستخدم للكلمات والموسيقى                                                          |
| معلمة غير مدعومة                  | الحقل غير موجود في عقد النموذج العام                     | إزالة الحقول الخاصة بالمزود أو اختيار نموذج يوثقها                                                   |

## مرجع API

| الموضوع                  | المرجع                                                               |
| ------------------------ | -------------------------------------------------------------------- |
| إنشاء موسيقى             | [إنشاء موسيقى](/ar/api-reference/music/create-music)                 |
| الحصول على حالة الموسيقى | [الحصول على حالة الموسيقى](/ar/api-reference/music/get-music-status) |
| الحصول على حالة المهمة   | [الحصول على حالة المهمة](/ar/api-reference/tasks/get-task-status)    |
| قائمة النماذج            | [قائمة النماذج](/ar/api-reference/models/list-models)                |
| الفوترة والتسعير         | [الفوترة والتسعير](/ar/guides/billing)                               |