الموسيقى
إنشاء الموسيقى
إنشاء مهمة لتوليد الموسيقى أو الكلمات أو الصوت
استخدم GET /v1/models?recommended_for=music للحصول على نماذج الموسيقى الحالية.
قم بإنشاء الموسيقى والكلمات والأصوات باستخدام الذكاء الاصطناعي. هذه واجهة برمجة تطبيقات (API) غير متزامنة. تُرجع استجابات الإنشاء معرف المهمة. قم بعمل استطلاع (Poll) باستخدام GET /v1/tasks/{id} لمعرفة الحالة.
تختلف النماذج في الحقول التي تقبلها. تحقق من GET /v1/models/{model} قبل إرسال الحقول الاختيارية؛ فالحقل الذي لا يدرجه النموذج قد يؤدي إلى إرجاع 400 unsupported_parameter. تنطبق حقول Suno (mv و title و tags و negative_tags و audio_operation والحقول المرتبطة بها) على نماذج Suno. الحقل user غير مدعوم ويُرجع 400.
نص الطلب (Request Body)
suno-musicمعرف نموذج الموسيقى، مثل suno-music أو stable-audio-3. أرسله بشكل صريح. للكلمات فقط، اختر نموذجاً تتضمن عملياته العامة الحالية lyrics.
وصف الموسيقى أو نص الاستبدال. مطلوب للموسيقى، والكلمات، و upload-cover، و upload-extend، و replace-section؛ اختياري لـ add-instrumental وفصل المسارات (stem separation).
عنوان الأغنية التي تم إنشاؤها.
وسوم النمط (مثال: "pop, upbeat, electronic").
الأنماط المراد تجنبها. مطلوبة عندما تكون audio_operation هي add-instrumental.
قيمة اختيارية MUSIC أو LYRICS. اختر نموذجاً يدعم العملية العامة المقابلة؛ هذا الحقل لا يضيف دعم الكلمات إلى نموذج مخصص للموسيقى فقط.
محدد إصدار Suno. مطلوب للإنشاء، و upload-cover، و upload-extend، و add-instrumental، والاستبدال من audio_url. اتركه فارغاً للكلمات، والاستبدال من task_id + audio_id، وفصل المسارات. القيم المقبولة: chirp-v6, chirp-v6-mini, chirp-v6-wild.
اضبطه على true لإنشاء مخرجات موسيقية بدون غناء.
مرجع يمكن الوصول إليه بشكل عام أو رابط صوتي مرفوع. عند توفيره بدون audio_operation، يستخدم TokenLab تدفق upload-cover.
عملية الصوت: upload-cover, upload-extend, add-instrumental, replace-section, vocal-separate, multi-stem-separation, advanced-split.
تتطلب vocal-separate و multi-stem-separation و advanced-split كلاً من task_id + audio_id؛ كما تتطلب advanced-split أيضاً stem_name. تتطلب upload-extend قيمة continue_at أكبر من 0. تتطلب add-instrumental كلاً من audio_url و title و tags و negative_tags.
بالنسبة لـ replace-section، أرسل prompt و tags و title و infill_start_s و infill_end_s و full_lyrics. اختر مصدراً واحداً فقط: task_id + audio_id، أو audio_url + mv. يجب أن تكون فترة الاستبدال بين 6 و 60 ثانية.
معرف المهمة المصدر التابع لمؤسستك، لاستبدال الصوت الذي تم إنشاؤه أو فصل المسارات.
معرف الصوت المصدر الذي تم إرجاعه في نتيجة المهمة المصدر. مطلوب مع task_id لاستبدال الصوت الذي تم إنشاؤه وفصل المسارات.
وقت بدء الاستبدال بالثواني، يجب أن يكون 0 على الأقل. مطلوب لـ replace-section.
وقت نهاية الاستبدال بالثواني. مطلوب لـ replace-section؛ يجب أن يكون بين 6 و 60 ثانية بعد infill_start_s.
الكلمات الكاملة للأغنية الناتجة. مطلوبة لـ replace-section.
اسم المسار (Stem). مطلوب لـ advanced-split.
معرف مقطع سابق للمتابعة منه.
الوقت بالثواني الذي يجب المتابعة منه. مطلوب ويجب أن يكون أكبر من 0 لـ upload-extend.
طول الصوت الذي تم إنشاؤه بالثواني، من 1 إلى 380. فقط للنماذج التي تدرج هذا الحقل، مثل stable-audio-3؛ تفاصيل النموذج توضح حدوده الخاصة.
تنسيق ملف الصوت المدرج بواسطة النموذج، على سبيل المثال mp3 أو wav أو flac. متاح فقط للنماذج التي تدعم إدراجه.
البذرة (Seed) لمخرجات قابلة للتكرار، من 0 إلى 4294967294. فقط للنماذج التي تدرج هذا الحقل.
عدد خطوات التوليد (generation steps). يعتمد النطاق على النموذج (على سبيل المثال من 4 إلى 8 لنموذج stable-audio-3). متاح فقط للنماذج التي تدرج هذا الخيار.
تدرج بعض النماذج حقولاً إضافية، مثل negative_prompt و n و seconds و guidance_scale. قم بإرسال هذه الحقول فقط عندما تدرجها تفاصيل النموذج؛ حيث سيؤدي إرسال حقل لا يدعمه النموذج المحدد إلى إرجاع الخطأ 400.
قوة توجيه المطالبة (Prompt)، من 1 إلى 25. فقط للنماذج التي تدرج هذا الحقل.
يقبل prompt ما يصل إلى 5000 حرف؛ وتقبل tags و negative_tags ما يصل إلى 1000 حرف لكل منهما. تعتمد العمليات والمعلمات المدعومة على التفاصيل الحالية للنموذج المختار.
الاستجابة (Response)
معرف المهمة لاستطلاع الحالة.
اسم مستعار لنفس معرف المهمة غير المتزامنة، عند إرجاعه.
رابط الحالة لهذه المهمة. قم بعمل استطلاع لـ GET /v1/tasks/{id} باستخدام id.
حالة المهمة: pending أو processing أو completed أو failed.
وقت إنشاء المهمة كطابع زمني Unix، عند إرجاعه.
الطلب
curl -X POST "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 electronic dance track with heavy bass",
"title": "Night Drive",
"tags": "electronic, EDM, energetic"
}'مثال على توليد الصوت لنموذج يأخذ duration و output_format بدلاً من حقول Suno:
{
"model": "stable-audio-3",
"prompt": "Warm lo-fi beat with soft vinyl crackle",
"duration": 30,
"output_format": "mp3"
}الاستجابة
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"model": "suno-music"
}التفويض
BearerAuth مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.
الموضع: header
الترويسات
سياسة التسليم لكل طلب. تتجاوز إعدادات API key و Workspace الافتراضية. يحاول النظام تلقائياً استخدام TokenLab Verified أولاً، وقد ينتقل مرة واحدة إلى Official فقط قبل المخرجات، أو قبول الطلب، أو إنشاء مورد دائم.
القيم المتاحة
- "auto"
- "verified"
- "official"
مفتاح اختياري يجعل طلب الإنشاء آمناً لإعادة المحاولة. أرسل قيمة فريدة جديدة، مثل UUID، لكل مهمة. إعادة المحاولة بنفس المفتاح ونفس نص الطلب تُرجع نتيجة طلب الإنشاء الأصلي، وعادةً ما تكون المهمة الأصلية، ولا تقوم بإنشاء أو إرسال أو احتساب تكلفة مهمة ثانية. يتم رفض نص الطلب المختلف الذي يستخدم مفتاحاً تم قبوله مسبقاً بالرمز 409. يتم تجاهل المفتاح الذي يتجاوز 255 حرفاً، وعندها لا يتمتع الطلب بحماية idempotency. راجع إعادة المحاولة بأمان باستخدام مفتاح idempotency.
1 <= length <= 255جسم الطلب
application/json
الاستجابة
application/json
application/json
application/json
application/json
application/json
application/json