POST https://api.acedata.cloud/suno/projects هي واجهة Beta لإدارة المشاريع متعددة المسارات. يتم التمييز بين الإنشاء والحفظ وتوليد المرشحات وتقديم المرشحات والتصدير عبر action.
retrieve، كل عملية تتطلب Idempotency-Key. المفتاح نفسه مع الطلب نفسه يعيد فقط النتيجة الأصلية؛ والمفتاح نفسه مع طلب مختلف يعيد 409. عند مواجهة مهلة شبكة أو عدم تأكد من نتيجة الإرسال أثناء التوليد المدفوع، استعلم أولًا باستخدام معرّف المهمة الأصلي أو مفتاح عدم التكرار نفسه، ولا تغيّر المفتاح وتعيد الإرسال مباشرة.
المعرّفات ووحدات الوقت
start_seconds / end_seconds هي ثوانٍ ضمن الصوت المصدر؛ وstart_beats / end_beats هي عدد النبضات على المخطط الزمني للمشروع. state.timing.bps هو عدد النبضات في الثانية، والقيمة الافتراضية هي 2. على سبيل المثال، مقطع مدته 41 ثانية يبدأ من النبضة 0، تكون نقطة نهايته الافتراضية النبضة 82. يُستخدم نطاق الثواني في generate_track لتحديد مرجع التوليد، ولا يضمن أن يكون طول المرشح هو هذا النطاق فقط.
سير العمليات
إذا كان المطلوب استبدالًا جزئيًا فقط، فيكفي وجود صوت مصدر قابل للاستخدام، ولا حاجة إلى
render أولًا؛ وإذا كان صوت المصدر موجودًا بالفعل في المشروع، يمكن أيضًا تجاوز upload وadd_track. إن render_audio_id هو مرجع إلزامي فقط لـ generate_track.
عند إرسال عملية غير متزامنة، يتم إرجاع { "task_id": "...", "trace_id": "..." } أولًا، وهذا لا يعني نجاح التوليد. الاستعلام الدوري:
finished_at، وكانت قيمة response.success فيه true؛ وعندما تكون response.success=false، اقرأ response.error. رغم أن save قد يحتوي على task_id، فإنه يكتمل بشكل متزامن ضمن هذه الواجهة. لا تعدّل upload وrender وgenerate_track وreplace_section إصدار المشروع؛ وبعد نجاح save وadd_track وcommit_candidate وremove_track يجب أخذ version_id الجديد.
اتفاقيات الطلبات
توضح الأمثلة التالية بصورة مترابطة تمرير المعرّفات والإصدارات بين العمليات. لا تسرد الاستجابات سوى الحقول المرتبطة بالخطوة الحالية؛ عند التكامل، استبدل معرّفات الأمثلة بقيم الاستجابة من تطبيقك الحالي.
إنشاء المشروع وقراءته
إنشاء مشروع: create
الطلب:
قراءة المشروع: retrieve
الطلب:```json
{
“action”: “retrieve”,
“id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”
}
start_seconds/end_seconds ضمانًا لمدة الإخراج.
اعتماد المرشح: commit_candidate
ينتج التوليد مرشحين فقط، ولا يضعهم تلقائيًا في المشروع. يتحقق
commit_candidate من أن المرشح لا يزال ينتمي إلى الإصدار الحالي. لا يمكن إرسال مرشحات الاستبدال الجزئي تلقائيًا إلا عندما يمكن مطابقة المدة الفعلية بشكل موثوق مع الصوت المصدر الكامل أو النطاق المحدد؛ وعند عدم التطابق، يُحتفظ بالمشروع الأصلي ويُعاد خطأ، ولا يمكن فرض الوصل من خلال التخمين اليدوي لعدد النبضات.
التصدير بعد الإرسال
بعد إرسال مرشح المسار الجديد، تم رفض تصدير الأغنية الكاملة التي تتضمن ذلك المرشح. الطلب والحالة النهائية:studio_audio_unavailable، يجب الاحتفاظ بالمشروع الأصلي والتحقق من مدى توفر الصوت المشار إليه.
استبدال مقطع موجود
يمكن لـreplace_section استخدام الصوت المصدر الموجود مباشرةً، دون الحاجة إلى تصدير مزيج أولًا. يعيد التوليد مرشحين فقط؛ وعند الإرسال، اختر المسار الأصلي الذي يحتوي على مقطع المصدر الفريد.
توليد مرشح الاستبدال: replace_section
عدم تطابق مدة المرشح
عند إرسال مرشحي الاستبدال الجزئي، يجب أن يشيرtrack_id إلى المسار الأصلي الذي يحتوي على المقطع المصدر الوحيد، مع حذف start_beats وend_beats. لن تحدّث الواجهة المشروع إلا عندما يمكن مطابقة مدة المرشح بشكل موثوق مع الصوت المصدر الكامل أو النطاق المحدد.
بعد اختيار نطاق مدته 8 ثوانٍ، كان كلا المرشحين مدته 36 ثانية، ولا تساوي مدة الصوت الأصلي البالغة 41 ثانية ولا 8 ثوانٍ المحددة. عند إرسال أحد المرشحين، يتم إرجاع:
حذف المسار
يتطلبremove_track كلاً من version_id الحالي وstate.tracks[].id؛ وبعد النجاح استخدم الإصدار الجديد المُعاد. فيما يلي حذف مسار المرشح الذي لا يمكن استخدامه لتصدير الأغنية الكاملة، وإعادة قراءة حالة المشروع.
التصدير بعد الحذف
بعد حذف مسار المرشح هذا، ظل المسار المصدر الأصلي موجودًا، واكتمل التصدير بنجاح مرة أخرى باستخدام أحدث إصدار:audio_url المُصدَّر بنجاح للتنزيل أو التشغيل. إن إمكانية الوصول إلى رابط الصوت لا تثبت أن المرشحين الآخرين مؤهلون أيضًا للتصدير الهندسي.
الأخطاء والاسترداد
يرتبط المشروع والمرشحون بالتطبيق الذي أنشأهم؛ يُرجى استخدام التطبيق الأصلي للوصول إليهم. احفظ بشكل دائم عنوان URL النهائي للصوت الذي تم تصديره بنجاح، واحتفظ بـ
trace_id لتسهيل استكشاف الأخطاء وإصلاحها.
