الانتقال إلى المحتوى الرئيسي
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” }
{ “success”: true, “trace_id”: “a335ceac-5cb7-4b1c-9773-77b9d5c84bd7”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “title”: “Suno Projects Documentation Verification 2026-10-09”, “state”: { “tracks”: [], “timing”: { “bps”: 2 } } }
{ “action”: “save”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “title”: “Suno Projects Documentation Verification 2026-10-09”, “state”: { “tracks”: [], “timing”: { “bps”: 2 } } }
{ “success”: true, “task_id”: “ab172b47-4d89-404b-a10e-71f67c36ccba”, “trace_id”: “fc7b2e43-7a7a-4276-8671-27008a1153ea”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “8f0c62fb-304f-420e-9707-426e8b64b5e3”, “state”: { “timing”: { “bps”: 2 }, “tracks”: [] } } }
{ “action”: “upload”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “8f0c62fb-304f-420e-9707-426e8b64b5e3”, “audio_url”: “https://cdn.acedata.cloud/suno_demo.mp3”, “async”: true }
{ “task_id”: “3fe60d9c-cada-4aab-b1f4-8c0b28247243”, “trace_id”: “4a54cb56-befb-45da-8001-2a20cdb67d18” }
{ “success”: true, “task_id”: “3fe60d9c-cada-4aab-b1f4-8c0b28247243”, “trace_id”: “4a54cb56-befb-45da-8001-2a20cdb67d18”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “candidate”: { “audio_id”: “b21be571-bfe4-47c1-b59c-2abc55c6f9c3”, “title”: “suno_demo”, “duration”: 41, “audio_url”: “https://cdn.acedata2.cloud/suno/b21be571-bfe4-47c1-b59c-2abc55c6f9c3.m4a” } } }
{ “action”: “add_track”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “8f0c62fb-304f-420e-9707-426e8b64b5e3”, “audio_id”: “b21be571-bfe4-47c1-b59c-2abc55c6f9c3”, “name”: “Source demo”, “start_beats”: 0 }
{ “task_id”: “03f0f74f-c3ed-4d03-896b-74b2a366838b”, “trace_id”: “3442a5b2-7b16-4225-b8af-24eb872d0e07” }
{ “success”: true, “task_id”: “03f0f74f-c3ed-4d03-896b-74b2a366838b”, “trace_id”: “3442a5b2-7b16-4225-b8af-24eb872d0e07”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “cf8a6aa5-0f6d-4da3-844e-cc156aa1b731”, “track”: { “id”: “b7ee9e97-f517-44d7-af4c-e9dad71498c9”, “name”: “Source demo”, “clips”: [ { “clipId”: “b21be571-bfe4-47c1-b59c-2abc55c6f9c3”, “startBeats”: 0, “endBeats”: 82 } ] } } }
{ “id”: “bdec15b5-ce96-43fa-b681-26298e013b06”, “type”: “audio”, “name”: “بيانو مُولَّد”, “clips”: [], “takeLanes”: [], “mute”: false, “solo”: false, “amplitude”: 1, “instrument”: { “type”: “song” }, “color”: “#7251F7” }
{ “success”: true, “task_id”: “783f8d49-cc59-4a65-9f9d-ca00e7d7b8a9”, “trace_id”: “0a9c8f13-7e4f-4915-8a40-010ce4ac61dc”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “cb0a82c9-aa5b-48cc-9395-0528675fc18d” } }
{ “action”: “render”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “cb0a82c9-aa5b-48cc-9395-0528675fc18d”, “title”: “Suno Projects Docs Source Mix”, “lyrics”: “[Instrumental]”, “async”: true }
{ “task_id”: “adc559fa-4a87-4a53-9336-28d4302a151b”, “trace_id”: “165fde93-f34b-4b0b-a7cd-0fba7d7ac154” }
{ “success”: true, “task_id”: “adc559fa-4a87-4a53-9336-28d4302a151b”, “trace_id”: “165fde93-f34b-4b0b-a7cd-0fba7d7ac154”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “cb0a82c9-aa5b-48cc-9395-0528675fc18d”, “render_id”: “41038732-4dc4-40bf-b00d-2728d99bc26e”, “audio_id”: “41038732-4dc4-40bf-b00d-2728d99bc26e”, “duration”: 41, “audio_url”: “https://cdn.acedata2.cloud/suno/41038732-4dc4-40bf-b00d-2728d99bc26e.m4a” } }
{ “action”: “generate_track”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “cb0a82c9-aa5b-48cc-9395-0528675fc18d”, “source_audio_id”: “b21be571-bfe4-47c1-b59c-2abc55c6f9c3”, “render_audio_id”: “41038732-4dc4-40bf-b00d-2728d99bc26e”, “model”: “chirp-v5”, “start_seconds”: 12, “end_seconds”: 20, “stem_control_tags”: “add Piano”, “title”: “Documentation Piano Take”, “tags”: “gentle piano, instrumental”, “async”: true }
{ “task_id”: “66a7356f-3b2a-4472-bdfd-f7b973380644”, “trace_id”: “81a4cf70-d9f6-48b3-a889-b68e74d6307f” }
{ “success”: true, “task_id”: “66a7356f-3b2a-4472-bdfd-f7b973380644”, “trace_id”: “81a4cf70-d9f6-48b3-a889-b68e74d6307f”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “cb0a82c9-aa5b-48cc-9395-0528675fc18d”, “operation_id”: “66a7356f-3b2a-4472-bdfd-f7b973380644”, “candidates”: [ { “id”: “1a4788a8-6f04-47d7-9698-4199b585b9a8”, “title”: “Documentation Piano Take”, “state”: “complete”, “duration”: 41.76, “audio_url”: “https://cdn.acedata2.cloud/suno/20f8ffe5063111b1eb866336242e2c0b2b9b7103a8dc0c0c19106cbf50843f86.mp3” }, { “id”: “18d6e0a4-2d73-43c3-92e9-be87cf11e139”, “title”: “Documentation Piano Take”, “state”: “complete”, “duration”: 40.96, “audio_url”: “https://cdn.acedata2.cloud/suno/c1c50a016333e3a037f18f651c0a88061880b3069aee7c6a258d6c9cdc041a6b.mp3” } ] } }
الثواني 12–20 في الطلب هي نطاق مرجعي للصوت المصدر، والصوت المرشح حوالي 41 ثانية؛ لا يمثل 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 لتسهيل استكشاف الأخطاء وإصلاحها.