> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# دليل تكامل مشروع Suno Studio

> Suno Music Generation API guide - Ace Data Cloud

تدير واجهة API لمشروع Suno Studio مشاريع الموسيقى متعددة المسارات عبر نقطة دخول واحدة:

```http theme={null}
POST /suno/projects
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

يحدد `action` في الطلب نوع العملية. يستخدم المفتاح الأساسي للمشروع `id` بشكل موحد؛ ويمثل `version_id` إصدار المشروع الحالي، ويجب أن تقدم جميع عمليات التعديل والتصدير أحدث إصدار لتجنب الكتابة فوق التغييرات المتزامنة.

## نظرة عامة على العمليات

| action | النمط | الغرض |
| - | - | - |
| `create` | متزامن | إنشاء مشروع فارغ |
| `retrieve` | متزامن | قراءة المشروع و`state` الكامل القابل للتحرير |
| `save` | متزامن | حفظ حالة المشروع الكاملة |
| `upload` | غير متزامن | تهيئة مادة قابلة للإضافة إلى المشروع من عنوان صوت HTTPS |
| `add_track` | غير متزامن | إضافة صوت موجود إلى المشروع |
| `generate_track` | غير متزامن | إنشاء مرشحي مسار صوتي جديدين لفترة محددة |
| `replace_section` | غير متزامن | إنشاء مرشحي استبدال موضعي |
| `commit_candidate` | غير متزامن | إرسال المرشح المحدد إلى المشروع |
| `remove_track` | متزامن | حذف المسار المحدد |
| `render` | غير متزامن | تصدير الإصدار المحفوظ كأغنية كاملة |

تعيد العمليات غير المتزامنة `task_id` فورًا. استخدم واجهة `/suno/tasks` المجانية للاستعلام الدوري، أو مرر `callback_url` لتلقي نتيجة الحالة النهائية.

## الإنشاء والقراءة

```json theme={null}
{"action":"create","title":"My Studio Project"}
```

يجب أن ترسل جميع عمليات التعديل ترويسة `Idempotency-Key` فريدة. بعد نجاح الإنشاء، يكون `data.id` في الاستجابة هو معرّف المشروع. قد لا يحتوي المشروع الفارغ الجديد على `version_id` قبل الحفظ الأول.

```json theme={null}
{"action":"retrieve","id":"PROJECT_ID"}
```

تتضمن استجابة القراءة `state` كاملة. يعيد المشروع الفارغ الجديد `{"tracks":[],"timing":{"bps":2}}`، ويمكن استخدامه مباشرةً للحفظ الأول. يمثل `timing.bps` عدد النبضات في الثانية، والقيمة الافتراضية هي 2 (120 BPM)، ويجب أن تكون رقمًا موجبًا؛ تستخدم `startBeats` و`endBeats` و`readStartBeats` للمقاطع وحدة نبضات المشروع، ولا يمكن اعتبار مواضع المقاييس في تحليل الصوت إحداثيات للخط الزمني مباشرةً.

## حفظ الحالة الكاملة

```json theme={null}
{
  "action":"save",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "title":"Edited Project",
  "state":{"tracks":[],"timing":{"bps":2}}
}
```

يمكن حذف `version_id` عند الحفظ الأول لمشروع فارغ جديد؛ بعد إنشاء إصدار عند الحفظ الأول، يجب تقديم أحدث قيمة في عمليات الحفظ اللاحقة. إذا تغير الإصدار، تعيد الواجهة HTTP 409. عندئذٍ أعد `retrieve`، وادمج التعديلات ثم أرسلها بمفتاح تكرار جديد؛ لا تعاود محاولة الطلب القديم بشكل أعمى.

## رفع المسارات وإضافتها

```json theme={null}
{
  "action":"upload",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "audio_url":"https://cdn.example.com/reference.mp3",
  "async":true
}
```

بعد نجاح الرفع، اقرأ معرّف الصوت من `response.data.candidate.audio_id`. ثم أضفه إلى المشروع:

```json theme={null}
{
  "action": "add_track",
  "id": "PROJECT_ID",
  "version_id": "CURRENT_VERSION_ID",
  "audio_id": "AUDIO_ID",
  "name": "Backing Vocals"
}
```

تحافظ إضافة المسار افتراضيًا على سرعة تشغيل الصوت، وتحول مدة الصوت إلى عدد نبضات وفقًا لـ `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 قبل الإرسال. لن يتم التحويل تلقائيًا إلى نموذج آخر.

```json theme={null}
{
  "action":"replace_section",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "source_audio_id":"AUDIO_ID",
  "start_seconds":35.12,
  "end_seconds":48.76,
  "model":"chirp-v6",
  "replacement_lyrics":"新的歌词片段",
  "async":true
}
```

يجب أن يوفر `generate_track` أيضًا `render_audio_id` (صوت تصدير مكتمل للمشروع)، و`stem_control_tags`، و`source_audio_id` للصوت المصدر. تتراوح `batch_size` من 1 إلى 4، والقيمة الافتراضية هي 2؛ و`start_seconds` و`end_seconds` هما ثواني الصوت المصدر. يجب أن تكون فترة الاستبدال ذات `fixed=true` أقصر من 26 ثانية.

بعد اختيار المرشح، أرسله:

```json theme={null}
{
  "action":"commit_candidate",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "operation_id":"OPERATION_ID",
  "candidate_id":"CANDIDATE_ID",
  "track_id":"TRACK_ID"
}
```

يرتبط المرشح بإصدار المشروع وقت التوليد. عندما يكون المشروع قد تغير، لا يمكن إرسال المرشح القديم مباشرةً.

يُرسل مرشح الاستبدال الموضعي إلى المسار الأصلي الذي يتضمن المقطع المصدر الفريد، ويحافظ مرشح الـ take الكامل على الموضع الأصلي ويستبدل المقطع الأصلي؛ ويستبدل مرشح الفترة فترة الطلب فقط، مع الاحتفاظ بالمقاطع السابقة واللاحقة. عند تعذر مطابقة المدة بشكل موثوق، يعيد 400 ويحتفظ بالمشروع الأصلي؛ عندئذٍ لا تمرر `start_beats` أو `end_beats`. يجب إرسال مرشح المسار الجديد إلى مسار فارغ محفوظ مسبقًا، ويعتمد افتراضيًا نقطة بداية المقطع المصدر، أو مرر صراحةً نطاقًا غير متداخل؛ ويعيد وجود مقاطع متداخلة مسبقًا على المسار نفسه 400. لا تنشئ مسارًا جديدًا بعد التوليد، وإلا فإن تغير الإصدار سيجعل المرشح منتهي الصلاحية.

## تصدير الأغنية الكاملة

```json theme={null}
{
  "action":"render",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "title":"Final Mix",
  "lyrics":"[Instrumental]",
  "async":true,
  "callback_url":"https://example.com/webhooks/suno"
}
```

يقرأ الخادم حالة المشروع المرجعية للإصدار المحدد ويجمع معلمات التصدير. عند حذف `start_beats` و`end_beats`، يُصدّر افتراضيًا من أقرب نقطة بداية إلى أحدث نقطة نهاية لجميع المقاطع المسموعة؛ ولا تشارك المسارات/المقاطع الصامتة، وعند وجود مسارات solo يتم اختيار مسارات solo فقط. يعيد المشروع الفارغ أو الذي لا يحتوي على مسارات مسموعة صالحة 400. تتضمن نتيجة الحالة النهائية `render_id` و`audio_id` و`audio_url` والمدة. يرتبط المشروع ببيئة التنفيذ عند الإنشاء، ولا يمكن ترحيله بين البيئات أو تحويله تلقائيًا عند الفشل.

> لا يجوز رفع أو معالجة سوى الصوت الذي تمتلك حقًا قانونيًا لاستخدامه. واجهة API للمشاريع حاليًا في Beta؛ يرجى حفظ عناوين URL النهائية للصوت في النتائج المهمة بشكل دائم.

## الاستعلام الدوري واستعادة الفشل

```json theme={null}
{"action":"retrieve","id":"TASK_ID"}
```

أرسل الطلب أعلاه إلى `/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` لأغراض التحقيق.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.