الموسيقى

إنشاء الموسيقى

إنشاء مهمة لتوليد الموسيقى أو الكلمات أو الصوت

POST
/v1/music/generations

استخدم 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)

modelstringالافتراضي: suno-music

معرف نموذج الموسيقى، مثل suno-music أو stable-audio-3. أرسله بشكل صريح. للكلمات فقط، اختر نموذجاً تتضمن عملياته العامة الحالية lyrics.

promptstring

وصف الموسيقى أو نص الاستبدال. مطلوب للموسيقى، والكلمات، و upload-cover، و upload-extend، و replace-section؛ اختياري لـ add-instrumental وفصل المسارات (stem separation).

titlestring

عنوان الأغنية التي تم إنشاؤها.

tagsstring

وسوم النمط (مثال: "pop, upbeat, electronic").

negative_tagsstring

الأنماط المراد تجنبها. مطلوبة عندما تكون audio_operation هي add-instrumental.

actionstring

قيمة اختيارية MUSIC أو LYRICS. اختر نموذجاً يدعم العملية العامة المقابلة؛ هذا الحقل لا يضيف دعم الكلمات إلى نموذج مخصص للموسيقى فقط.

mvstring

محدد إصدار Suno. مطلوب للإنشاء، و upload-cover، و upload-extend، و add-instrumental، والاستبدال من audio_url. اتركه فارغاً للكلمات، والاستبدال من task_id + audio_id، وفصل المسارات. القيم المقبولة: chirp-v6, chirp-v6-mini, chirp-v6-wild.

make_instrumentalboolean

اضبطه على true لإنشاء مخرجات موسيقية بدون غناء.

audio_urlstring

مرجع يمكن الوصول إليه بشكل عام أو رابط صوتي مرفوع. عند توفيره بدون audio_operation، يستخدم TokenLab تدفق upload-cover.

audio_operationstring

عملية الصوت: 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_idstring

معرف المهمة المصدر التابع لمؤسستك، لاستبدال الصوت الذي تم إنشاؤه أو فصل المسارات.

audio_idstring

معرف الصوت المصدر الذي تم إرجاعه في نتيجة المهمة المصدر. مطلوب مع task_id لاستبدال الصوت الذي تم إنشاؤه وفصل المسارات.

infill_start_snumber

وقت بدء الاستبدال بالثواني، يجب أن يكون 0 على الأقل. مطلوب لـ replace-section.

infill_end_snumber

وقت نهاية الاستبدال بالثواني. مطلوب لـ replace-section؛ يجب أن يكون بين 6 و 60 ثانية بعد infill_start_s.

full_lyricsstring

الكلمات الكاملة للأغنية الناتجة. مطلوبة لـ replace-section.

stem_namestring

اسم المسار (Stem). مطلوب لـ advanced-split.

continue_clip_idstring

معرف مقطع سابق للمتابعة منه.

continue_atnumber

الوقت بالثواني الذي يجب المتابعة منه. مطلوب ويجب أن يكون أكبر من 0 لـ upload-extend.

durationinteger

طول الصوت الذي تم إنشاؤه بالثواني، من 1 إلى 380. فقط للنماذج التي تدرج هذا الحقل، مثل stable-audio-3؛ تفاصيل النموذج توضح حدوده الخاصة.

output_formatstring

تنسيق ملف الصوت المدرج بواسطة النموذج، على سبيل المثال mp3 أو wav أو flac. متاح فقط للنماذج التي تدعم إدراجه.

seedinteger

البذرة (Seed) لمخرجات قابلة للتكرار، من 0 إلى 4294967294. فقط للنماذج التي تدرج هذا الحقل.

stepsinteger

عدد خطوات التوليد (generation steps). يعتمد النطاق على النموذج (على سبيل المثال من 4 إلى 8 لنموذج stable-audio-3). متاح فقط للنماذج التي تدرج هذا الخيار.

تدرج بعض النماذج حقولاً إضافية، مثل negative_prompt و n و seconds و guidance_scale. قم بإرسال هذه الحقول فقط عندما تدرجها تفاصيل النموذج؛ حيث سيؤدي إرسال حقل لا يدعمه النموذج المحدد إلى إرجاع الخطأ 400.

cfg_scalenumber

قوة توجيه المطالبة (Prompt)، من 1 إلى 25. فقط للنماذج التي تدرج هذا الحقل.

يقبل prompt ما يصل إلى 5000 حرف؛ وتقبل tags و negative_tags ما يصل إلى 1000 حرف لكل منهما. تعتمد العمليات والمعلمات المدعومة على التفاصيل الحالية للنموذج المختار.

الاستجابة (Response)

idstring

معرف المهمة لاستطلاع الحالة.

task_idstring

اسم مستعار لنفس معرف المهمة غير المتزامنة، عند إرجاعه.

poll_urlstring

رابط الحالة لهذه المهمة. قم بعمل استطلاع لـ GET /v1/tasks/{id} باستخدام id.

statusstring

حالة المهمة: pending أو processing أو completed أو failed.

createdinteger

وقت إنشاء المهمة كطابع زمني 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"
}

الاستجابة

Response
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "model": "suno-music"
}

التفويض

BearerAuth
AuthorizationBearer <token>

مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.

الموضع: header

الترويسات

X-TokenLab-Delivery-Policy?string

سياسة التسليم لكل طلب. تتجاوز إعدادات API key و Workspace الافتراضية. يحاول النظام تلقائياً استخدام TokenLab Verified أولاً، وقد ينتقل مرة واحدة إلى Official فقط قبل المخرجات، أو قبول الطلب، أو إنشاء مورد دائم.

القيم المتاحة

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

مفتاح اختياري يجعل طلب الإنشاء آمناً لإعادة المحاولة. أرسل قيمة فريدة جديدة، مثل UUID، لكل مهمة. إعادة المحاولة بنفس المفتاح ونفس نص الطلب تُرجع نتيجة طلب الإنشاء الأصلي، وعادةً ما تكون المهمة الأصلية، ولا تقوم بإنشاء أو إرسال أو احتساب تكلفة مهمة ثانية. يتم رفض نص الطلب المختلف الذي يستخدم مفتاحاً تم قبوله مسبقاً بالرمز 409. يتم تجاهل المفتاح الذي يتجاوز 255 حرفاً، وعندها لا يتمتع الطلب بحماية idempotency. راجع إعادة المحاولة بأمان باستخدام مفتاح idempotency.

الطول1 <= length <= 255

جسم الطلب

application/json

الاستجابة

application/json

application/json

application/json

application/json

application/json

application/json