أدلة الوسائط
توليد الموسيقى
أنشئ أغانٍ أو كلمات أغانٍ وانتظر حتى اكتمال الصوت
توليد الموسيقى هو عملية غير متزامنة (asynchronous). يقوم POST /v1/music/generations بإرجاع معرف المهمة (task ID)، والحالة، وعادةً poll_url. قم بعمل GET /v1/tasks/{id} باستخدام ذلك المعرف حتى تصبح حالة المهمة completed أو failed.
اختر ما تريد إنشاءه
| ما تريد إنشاءه | الحقول الرئيسية | ملاحظات |
|---|---|---|
| أغنية كاملة أو مقطوعة موسيقية | model, mv, prompt, اختياري title, tags, action: "MUSIC" | استخدمه عندما يتوقع المستخدم الحصول على الصوت النهائي |
| كلمات الأغاني فقط | model, prompt, action: "LYRICS" | استخدمه فقط مع النماذج التي تدعم توليد كلمات الأغاني |
| متابعة مقطع موجود | model, mv, prompt, continue_clip_id, اختياري continue_at | احتفظ بمعرف المقطع السابق |
| غناء (Cover) أو تمديد صوتك الخاص | model, mv, prompt, audio_url, اختياري audio_operation | يجب أن يكون audio_url رابطاً عاماً. audio_operation هو upload-cover افتراضياً؛ يتطلب upload-extend أيضاً continue_at |
| إضافة آلات موسيقية، استبدال مقطع، أو فصل المسارات | audio_operation: add-instrumental, replace-section, vocal-separate, multi-stem-separation, أو advanced-split | كل عملية لها حقولها المطلوبة؛ راجع إنشاء الموسيقى |
احصل على قائمة نماذج الموسيقى الحالية من:
curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
-H "Authorization: Bearer sk-your-api-key"يستخدم المثال أدناه suno-music مع mv: "chirp-v6". تستخدم نماذج الموسيقى الأخرى، مثل stable-audio-3، حقولاً مختلفة مثل duration و output_format؛ اقرأ تفاصيل النموذج أولاً. بالنسبة لكلمات الأغاني فقط، اختر نموذجاً يوثق توليد الكلمات، وأرسل action: "LYRICS"، واحذف mv.
إنشاء مهمة موسيقى
curl https://api.tokenlab.sh/v1/music/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "suno-music",
"mv": "chirp-v6",
"prompt": "An upbeat synth-pop track with warm vocals and a clean chorus",
"title": "Morning Static",
"tags": "synth-pop, upbeat",
"action": "MUSIC"
}'قد تظهر المطالبات (prompts)، والعناوين، والوسوم في سجل منتجك. لا تضع أبداً مفاتيح API، أو روابط خاصة، أو بيانات تشخيصية فيها.
الحصول على الصوت النهائي
قم باستدعاء GET /v1/tasks/{id} باستخدام id أو task_id الذي تم إرجاعه.
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer sk-your-api-key"شكل الاستجابة
استجابة الإنشاء هي سجل مهمة، وليست الصوت النهائي:
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"created": 1706000000,
"model": "suno-music"
}يمكن أن تتضمن استجابة الاستطلاع المكتملة حقول الوسائط النهائية:
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "completed",
"audio_url": "https://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
"video_url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
"image_url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
"title": "Morning Static",
"lyrics": "[Verse 1]\n...",
"media_retention": {
"days": 30,
"items": [
{
"url": "https://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
"kind": "audio",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
},
{
"url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
"kind": "video",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
},
{
"url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
"kind": "image",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
}
]
}
}تكون حقول الوسائط النهائية غائبة حتى تصبح الحالة completed. المهام الفاشلة تعيد status: "failed" مع error.
الحالات هي pending، و processing، و completed، و failed. يمكن أن تتضمن المهمة المكتملة audio_url، و video_url، و title، و lyrics، وبيانات وصفية أخرى. روابط الوسائط هي روابط TokenLab تظل صالحة لمدة 30 يوماً؛ قم بتنزيل أو حفظ أي نتيجة تحتاجها لفترة أطول.
عرض الحالة الصحيحة
- اعرض حالة "قيد الانتظار" (pending) مباشرة بعد إنشاء المهمة.
- قم بالاستطلاع كل
5-10 ثوانٍللمهام الطويلة، ثم توقف عندcompletedأوfailed. - لا تعرض مشغل الوسائط النهائي إلا عندما تكون المهمة
completedويوجدaudio_url. - بالنسبة لمهام كلمات الأغاني فقط، اعرض مخرجات النص بشكل منفصل عن مهام الصوت حتى يفهم المستخدمون ما يشترونه.
- عند التحديث (refresh)، استأنف العمل من
task_idالمخزن بدلاً من إنشاء مهمة جديدة.
سجلات الفوترة
يمكن لمهام الموسيقى حجز مبلغ تقديري عند إنشائها. يتم تسجيل المبلغ النهائي بعد الاكتمال أو الفشل. احفظ request_id و task_id والنموذج ونقطة النهاية و billing_transaction_id عند ظهوره؛ استخدم سجلات استخدام Management API للرسوم النهائية.
الأخطاء الشائعة
| العرض | السبب المحتمل | الحل |
|---|---|---|
| تم إنشاء المهمة ولكن لا يوجد مشغل | المهمة لا تزال قيد الانتظار أو اكتملت بدون audio_url | استمر في الاستطلاع حتى الوصول للحالة النهائية، ثم تعامل مع المخرجات المفقودة كمهمة مستخدم فاشلة |
| تكرار الأغاني بعد التحديث | قامت واجهة المستخدم بإعادة إنشاء المهمة بدلاً من استئنافها | احتفظ بـ task_id وأعد استخدامه |
| مهمة كلمات الأغاني لا تعيد صوتاً | action: "LYRICS" مخصصة للنص فقط | افصل مسارات واجهة مستخدم كلمات الأغاني عن الموسيقى |
| معامل غير مدعوم | النموذج المختار لا يقبل هذا الحقل | احذفه أو اختر نموذجاً يوثق هذا الحقل |
مرجع API
| الموضوع | المرجع |
|---|---|
| إنشاء الموسيقى | إنشاء الموسيقى |
| الحصول على حالة الموسيقى | الحصول على حالة الموسيقى |
| الحصول على حالة المهمة | الحصول على حالة المهمة |
| قائمة النماذج | قائمة النماذج |
| الفوترة والأسعار | الفوترة والأسعار |