action في الطلب نوع العملية. يستخدم المفتاح الأساسي للمشروع id بشكل موحد؛ ويمثل version_id إصدار المشروع الحالي، ويجب أن تقدم جميع عمليات التعديل والتصدير أحدث إصدار لتجنب الكتابة فوق التغييرات المتزامنة.
نظرة عامة على العمليات
تعيد العمليات غير المتزامنة
task_id فورًا. استخدم واجهة /suno/tasks المجانية للاستعلام الدوري، أو مرر callback_url لتلقي نتيجة الحالة النهائية.
الإنشاء والقراءة
Idempotency-Key فريدة. بعد نجاح الإنشاء، يكون data.id في الاستجابة هو معرّف المشروع. قد لا يحتوي المشروع الفارغ الجديد على version_id قبل الحفظ الأول.
state كاملة. يعيد المشروع الفارغ الجديد {"tracks":[],"timing":{"bps":2}}، ويمكن استخدامه مباشرةً للحفظ الأول. يمثل timing.bps عدد النبضات في الثانية، والقيمة الافتراضية هي 2 (120 BPM)، ويجب أن تكون رقمًا موجبًا؛ تستخدم startBeats وendBeats وreadStartBeats للمقاطع وحدة نبضات المشروع، ولا يمكن اعتبار مواضع المقاييس في تحليل الصوت إحداثيات للخط الزمني مباشرةً.
حفظ الحالة الكاملة
version_id عند الحفظ الأول لمشروع فارغ جديد؛ بعد إنشاء إصدار عند الحفظ الأول، يجب تقديم أحدث قيمة في عمليات الحفظ اللاحقة. إذا تغير الإصدار، تعيد الواجهة HTTP 409. عندئذٍ أعد retrieve، وادمج التعديلات ثم أرسلها بمفتاح تكرار جديد؛ لا تعاود محاولة الطلب القديم بشكل أعمى.
رفع المسارات وإضافتها
response.data.candidate.audio_id. ثم أضفه إلى المشروع:
timing.bps الخاص بالمشروع. بعد كل save أو add_track أو commit_candidate أو remove_track، يجب استخدام version_id الجديد في الاستجابة.
التوليد والاستبدال
ينشئgenerate_track مرشحي مسار صوتي لفترة من المشروع؛ ويعيد replace_section مرشحين للاستبدال الموضعي. لا تختار أي من العمليتين النتيجة الفنية تلقائيًا. يجب أن يستخدم النموذج الاسم العام: chirp-v3-5 أو chirp-v4 أو chirp-v4-5 أو chirp-v4-5-plus أو chirp-v5 أو chirp-v5-5 أو chirp-v6 أو chirp-v6-wild أو chirp-v6-mini؛ ويظل توفر العملية المحددة خاضعًا لحالة المهمة النهائية، وتعيد الأسماء غير المدعومة 400 قبل الإرسال. لن يتم التحويل تلقائيًا إلى نموذج آخر.
generate_track أيضًا render_audio_id (صوت تصدير مكتمل للمشروع)، وstem_control_tags، وsource_audio_id للصوت المصدر. تتراوح batch_size من 1 إلى 4، والقيمة الافتراضية هي 2؛ وstart_seconds وend_seconds هما ثواني الصوت المصدر. يجب أن تكون فترة الاستبدال ذات fixed=true أقصر من 26 ثانية.
بعد اختيار المرشح، أرسله:
start_beats أو end_beats. يجب إرسال مرشح المسار الجديد إلى مسار فارغ محفوظ مسبقًا، ويعتمد افتراضيًا نقطة بداية المقطع المصدر، أو مرر صراحةً نطاقًا غير متداخل؛ ويعيد وجود مقاطع متداخلة مسبقًا على المسار نفسه 400. لا تنشئ مسارًا جديدًا بعد التوليد، وإلا فإن تغير الإصدار سيجعل المرشح منتهي الصلاحية.
تصدير الأغنية الكاملة
start_beats وend_beats، يُصدّر افتراضيًا من أقرب نقطة بداية إلى أحدث نقطة نهاية لجميع المقاطع المسموعة؛ ولا تشارك المسارات/المقاطع الصامتة، وعند وجود مسارات solo يتم اختيار مسارات solo فقط. يعيد المشروع الفارغ أو الذي لا يحتوي على مسارات مسموعة صالحة 400. تتضمن نتيجة الحالة النهائية render_id وaudio_id وaudio_url والمدة. يرتبط المشروع ببيئة التنفيذ عند الإنشاء، ولا يمكن ترحيله بين البيئات أو تحويله تلقائيًا عند الفشل.
لا يجوز رفع أو معالجة سوى الصوت الذي تمتلك حقًا قانونيًا لاستخدامه. واجهة API للمشاريع حاليًا في Beta؛ يرجى حفظ عناوين URL النهائية للصوت في النتائج المهمة بشكل دائم.
الاستعلام الدوري واستعادة الفشل
/suno/tasks. تُعد مهام Projects ناجحة عندما يكون finished_at موجودًا وresponse.success=true؛ ويشير response.success=false إلى الفشل. إن إرجاع HTTP 200 أو task_id عند الإرسال يعني فقط أنه تم قبول الطلب، ولا يعني اكتمال الصوت.
سيؤدي نفس Idempotency-Key مع نفس الطلب إلى استرجاع النتيجة الأصلية (بما في ذلك الفشل)، ولن يعيد التوليد تلقائيًا أو يكرر الخصم. لإعادة محاولة عملية فاشلة بشكل صريح، استعلم أولًا عن المهمة الأصلية لتأكيد الفشل، ثم استخدم مفتاحًا جديدًا؛ لا تُعد الإرسال بينما لا تزال المهمة الأصلية قيد المعالجة أو عندما تكون النتيجة غير مؤكدة.
تشمل تصنيفات الأخطاء studio_unavailable / studio_model_unavailable (503، يتعذر المعالجة مؤقتًا أو النموذج غير متاح)، وstudio_model_unsupported (400، النموذج لا يدعم هذه العملية)، وstudio_state_invalid (400، حالة المشروع أو نطاق التصدير غير صالح)، وtoo_many_requests (429)، وstudio_audio_unavailable (403، لا يمكن استخدام الصوت المُشار إليه لتصدير المشروع)، وcontent_rejected (403). احتفظ بـtrace_id لأغراض التحقيق.