> ## 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.

# شرح تكامل واجهة API لتوليد أغاني Suno

> Suno Music Generation API guide - Ace Data Cloud

مع اتساع تطبيقات الذكاء الاصطناعي، أصبحت مختلف برامج الذكاء الاصطناعي منتشرة تدريجيًا. وقد تعمّق الذكاء الاصطناعي تدريجيًا في جميع جوانب عمل الناس وحياتهم. كما تتزايد الصناعات التي يشملها الذكاء الاصطناعي، بدءًا من الكتابة في البداية، مرورًا بالرعاية الطبية والتعليم، وصولًا الآن إلى الموسيقى.

Suno هي منصة احترافية وعالية الجودة لإنشاء الأغاني والموسيقى بالذكاء الاصطناعي، حيث لا يحتاج المستخدم سوى إلى إدخال كلمات توجيه نصية بسيطة لإنشاء أغانٍ تحتوي على أصوات بشرية وفقًا لنمط النوع الموسيقي وكلمات الأغنية. طوّر مولد الموسيقى بالذكاء الاصطناعي هذا أعضاء فريق من شركات تقنية معروفة مثل Meta وTikTok وKensho وغيرها، والهدف هو عدم الحاجة إلى أي أدوات أو آلات موسيقية، بحيث يمكن للجميع إنشاء موسيقى رائعة.

فيما يلي تقدم تحديثات النماذج:

| الإصدار | model | وقت الإطلاق | حد lyric | حد style | أقصى مدة للأغنية |
| - | - | - | - | - | - |
| v6 | chirp-v6 | 2026.09.09 | — | — | — |
| v6 Wild | chirp-v6-wild | 2026.09.09 | — | — | — |
| v6 Mini | chirp-v6-mini | 2026.09.09 | — | — | — |
| v5.5 | chirp-v5-5 | 2026.03.27 | 5000 | 1000 | 8 دقائق |
| v5 | chirp-v5 | 2025.09.23 | 5000 | 1000 | 8 دقائق |
| v4.5+ | chirp-v4-5-plus | 2025.07.17 | 5000 | 1000 | 8 دقائق |
| v4.5 | chirp-v4-5 | 2025.05.03 | 5000 | 1000 | 4 دقائق |
| v4 | chirp-v4 | 2024.12.17 | 3000 | 200 | 150 ثانية |
| v3.5 | chirp-v3-5 | --- | 3000 | 200 | 120 ثانية |

> حدود `lyric` و`style` في الجدول أعلاه هي الحدود القصوى في الوضع المخصص (عندما تكون `custom` بقيمة `true`). أما وضع الإلهام غير المخصص (عندما تكون `custom` بقيمة `false`) فيملأ `prompt` فقط، وحده الأقصى للطول هو 500 حرف (ومتطابق في جميع النماذج).

يدعم Suno الآن `chirp-v6` و`chirp-v6-wild` و`chirp-v6-mini`. يُوصى باستخدام `chirp-v6`؛ وتبقى أسماء النماذج القديمة متوافقة.

ومع ذلك، لا يوفر Suno الرسمي واجهة API، وتوفر AceDataCloud مجموعة من واجهات API لـ Suno، تحاكي التكامل مع Suno الرسمي، ويمكنها إنشاء الموسيقى المطلوبة بسهولة وسرعة.

## التقديم والاستخدام

لاستخدام Suno Audios Generation API، انتقل أولًا إلى [وحدة تحكم Ace Data Cloud](https://platform.acedata.cloud/console/applications) للحصول على API Token الخاص بك، واحتفظ به للاستخدام لاحقًا.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

إذا لم تكن قد سجلت الدخول أو أنشأت حسابًا بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك إلى التسجيل وتسجيل الدخول، وبعد الإكمال ستعود تلقائيًا إلى الصفحة الحالية.

**يمكن لـ API Token واحد استدعاء جميع خدمات المنصة، ولا حاجة للتقديم بشكل منفصل لكل خدمة.** سيُمنح رصيد مجاني عند التقديم للمرة الأولى، ويمكنك التجربة مجانًا؛ وعندما لا يكون الرصيد كافيًا، يمكنك شحن الرصيد العام من [وحدة التحكم](https://platform.acedata.cloud/console/coin).

> 📘 الوثائق الكاملة: [Suno Audios Generation API →](https://platform.acedata.cloud/documents/suno-audios)

## الاستخدام الأساسي

أي نوع من الأغاني تفكر فيه، يمكنك إدخال أي نص، على سبيل المثال إذا أردت إنشاء أغنية عن عيد الميلاد، يمكنك إدخال `a song for Christmas`، كما هو موضح في الصورة:

![](https://cdn.acedata.cloud/2kuuup.png)

يمكن ملاحظة أننا قمنا هنا بتعيين Request Headers، بما في ذلك:

* `accept`: نوع تنسيق نتيجة الاستجابة التي تريد تلقيها، وهنا تم تعبئته بـ `application/json`، أي تنسيق JSON.
* `authorization`: مفتاح استدعاء API، ويمكن اختياره مباشرة من القائمة المنسدلة بعد التقديم.

كما قمنا بتعيين Request Body، بما في ذلك:

* `action`: نوع مهمة الصوت، الافتراضي هو `generate`. يدعم عمليات مثل التوليد، والتمديد، وإعادة الغناء، والدمج، وفصل المسارات، وإضافة المسارات الصوتية، واستخراج مسار صوتي محدد، وتوليد المؤثرات الصوتية، وضبط السرعة، وغيرها، ويتم استدعاؤها جميعًا عبر `POST /suno/audios`.
* `prompt`: نص مطالبة وضع الإلهام الرسمي من Suno (يكون فعالًا عندما تكون `custom` بقيمة `false`)، بحد أقصى 500 حرف.
* `model`: نموذج مهمة توليد الموسيقى هذه. تتضمن سلسلة v6 كلاً من `chirp-v6` و`chirp-v6-wild` و`chirp-v6-mini`؛ وتظل أسماء النماذج القديمة متوافقة.
* `max_mode`: وضع التوليد المحسّن. لا يتم تمكين `generate` إلا عندما تكون كل من `custom` و`max_mode` بقيمة `true`، وتكلفته 1.12 Credits؛ ويمكن تمكين `add_stem` مباشرةً، وتكلفته 1.344 Credits. عند إيقافه أو حذفه، تكون التكلفة 0.56 و0.672 Credits على التوالي.
* `variety`: شدة تنوع النتائج المُولَّدة، والقيم الاختيارية هي `off` و`normal` و`high` و`extra` و`max`. يُستخدم فقط مع `generate` و`add_stem`، وسيؤدي تمريره مع action آخر إلى إرجاع 400.
* `lyric`: محتوى كلمات الأغنية لوضع التخصيص الرسمي من Suno. الحد الأقصى لـ `chirp-v3-5` و`chirp-v4` هو 3000 حرف؛ ولـ `chirp-v4-5` وما بعده (بما في ذلك `chirp-v5` و`chirp-v5-5`) هو 5000 حرف.
* `custom`: ما إذا كان سيتم استخدام وضع التخصيص، والافتراضي هو: `false`.
* `instrumental`: خيار الموسيقى الآلية الخالصة لوضع الإلهام الرسمي من Suno.
* `title`: عنوان الموسيقى لوضع التخصيص الرسمي من Suno. الحد الأقصى لـ `chirp-v3-5` و`chirp-v4` هو 80 حرفًا؛ ولـ `chirp-v4-5` وما بعده هو 100 حرف.
* `style`: نمط الموسيقى لوضع التخصيص الرسمي من Suno. الحد الأقصى لـ `chirp-v3-5` و`chirp-v4` هو 200 حرف؛ ولـ `chirp-v4-5` وما بعده (بما في ذلك `chirp-v5` و`chirp-v5-5`) هو 1000 حرف.
* `negative_tags`: أنماط أو أنواع موسيقية يُراد استبعادها من النتائج المُولَّدة في وضع التخصيص (عندما تكون `custom` بقيمة `true`).
* `audio_weight`: وزن تأثير خصائص الصوت أو الصوت البشري، ضمن النطاق 0-1، وتُعد `0` أيضًا قيمة صالحة. يمكن استخدامه لعمليات مثل التوليد، والتمديد، وإعادة الغناء، وإضافة المسارات الصوتية، واتساق الصوت؛ وعند عدم وجود صوت مرجعي أو خصائص صوتية، قد يُضعف النموذج هذه القيمة أو يتجاهلها.
* `audio_id`: معرّف الموسيقى المرجعية.
* `overpainting_start`/`overpainting_end`: وقتا البدء والانتهاء لإضافة غناء بشري إلى موسيقى آلية موجودة، بوحدة الثواني.
* `underpainting_start`/`underpainting_end`: وقتا البدء والانتهاء لإضافة مرافقة موسيقية إلى غناء دون مرافقة، بوحدة الثواني.
* `persona_id`: معرّف أغنية الفنان.
* `continue_at`: حد التمديد، بوحدة الثواني. على سبيل المثال، يشير 213.5 إلى بدء توليد المقطع اللاحق من الدقيقة الثالثة و33.5 ثانية. لا يوجّه `lyric` و`style` إلا المحتوى الجديد بعد الحد، ولن يستبدلا الكلمات أو الغناء قبل الحد في الصوت المصدر.
* `style_influence`: تأثير النمط في وضع التخصيص، ضمن النطاق 0-1، وكلما زادت القيمة، زادت عادةً مطابقة النمط المحدد؛ ويتم تمرير `0` كقيمة صالحة.
* `replace_section_end`: الوقت النهائي للمقطع المستبدل.
* `replace_section_start`: وقت بدء المقطع المستبدل.
* `vocal_gender`: يتحكم في تفضيل الصوت الأنثوي أو الذكوري، الصوت الأنثوي `f`، والصوت الذكوري `m`، وهو فعّال في نماذج 4.5 وما بعدها؛ وهو عنصر تفضيل ولا يضمن الالتزام الصارم.
* `weirdness`: درجة الغرابة في وضع التخصيص، ضمن النطاق 0-1، وكلما زادت القيمة، كانت النتيجة عادةً أكثر إبداعًا وتجريبية؛ ويتم تمرير `0` كقيمة صالحة.
* `duration`: مدة الأغنية المطلوبة، بوحدة الثواني، ويجب أن تكون عددًا صحيحًا، ضمن النطاق من 10 إلى 360. تُستخدم هذه المعلمة لتوليد الأغاني في وضع التخصيص (عندما تكون `custom` بقيمة `true`). وهي مطالبة توجيهية وليست قيدًا صارمًا: سيأخذها النموذج في الاعتبار، لكنه لا يضمن تحقيقها، وتكون مدة المنتج الفعلية وفقًا لحقل `duration` في الاستجابة، وعادةً ما تكون أقصر من القيمة المطلوبة.

### نطاق تطبيق المعلمات المتقدمة

| المعلمة | القيم | إجراءات action المدعومة | الوصف |
| - | - | - | - |
| `weirdness` | 0-1 | اختياري | يضبط التجريبية، وتُعد `0` قيمة صالحة؛ ويعتمد التأثير على العملية والوضع والنموذج |
| `style_influence` | 0-1 | اختياري | يضبط ميل الالتزام بالنمط، وتُعد `0` قيمة صالحة؛ ويعتمد التأثير على العملية والوضع والنموذج |
| `audio_weight` | 0-1 | اختياري | يضبط تأثير خصائص الصوت أو الصوت البشري؛ وقد يتجاهله النموذج عند عدم وجود معلومات مرجعية |
| `variety` | `off` / `normal` / `high` / `extra` / `max` | `generate`، `add_stem` | يضبط تنوع النمط بين النتائج |
| `max_mode` | boolean | `generate` (يتطلب `custom=true`)، `add_stem` | يعزز الاتساق ويُحاسب وفق وضع التحسين |
| `vocal_gender` | `f` / `m` | عمليات التوليد التي تدعم التحكم بالصوت البشري | عنصر تفضيل ولا يضمن الالتزام الصارم |
| `duration` | عدد صحيح 10-360 | اختياري | المدة المطلوبة؛ قد تتجاهلها العملية أو الوضع أو النموذج المحدد |

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

* `lyric_prompt`: prompt لتوليد الكلمات، ولا يكون فعالًا إلا عندما تكون `custom` بقيمة `true` ولا يتم تمرير `lyric`.
* `callback_url`: عنوان URL الذي يتطلب استدعاءً راجعًا للنتيجة.
* `async`: اختياري، عند ضبطه على `true` تُرجع الواجهة `task_id` فورًا، دون الحاجة إلى تقديم `callback_url`، ثم يتم الحصول على النتيجة عبر الاستعلام الدوري باستخدام واجهة الاستعلام عن المهمة المقابلة.

الكود المُولَّد كما يلي:

![](https://cdn.acedata.cloud/1xehwl.png)

يمكنك النقر على زر «Try» لاختبار API مباشرةً، والانتظار لمدة 1-2 دقيقة، وتكون النتيجة كما يلي:

```json theme={null}
{
  "success": true,
  "task_id": "e72fb249-bd5b-4e2a-b20c-8a06fea5ac14",
  "trace_id": "7dbc5b6a-b2c0-4d85-9d39-fa8a8a785ccf",
  "data": [
    {
      "id": "b481b17a-bf50-4e10-8adc-4d5635050893",
      "title": "Under the Mistletoe",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-001",
      "lyric": "[Verse]\nSnowflakes falling on the ground\nTwinkling lights all around\nThe scent of pine fills the air\nChristmas magic everywhere\n[Chorus]\nUnder the mistletoe tonight\nHearts aglow in the soft moonlight\nLaughter echoes\nSpirits bright\nIt’s Christmas time\nIt feels so right\n[Verse 2]\nStockings hung by the fire’s glow\nWarmth inside while the cold winds blow\nCookies baking\nSweet delight\nA season of joy shining bright\n[Chorus]\nUnder the mistletoe tonight\nHearts aglow in the soft moonlight\nLaughter echoes\nSpirits bright\nIt’s Christmas time\nIt feels so right\n[Bridge]\nCarols sung by candlelight\nStars above make the world feel tight\nPeace and love\nA season’s creed\nFilling hearts with all we need\n[Chorus]\nUnder the mistletoe tonight\nHearts aglow in the soft moonlight\nLaughter echoes\nSpirits bright\nIt’s Christmas time\nIt feels so right",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T15:59:32.468Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "prompt": "A song for Christmas",
      "style": "holiday, cheerful, male vocals",
      "duration": 154.92
    },
    {
      "id": "fbf22dab-5e2b-4e02-84c0-6d7605f14c3d",
      "title": "Under the Mistletoe",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-002",
      "lyric": "[Verse]\nSnowflakes falling on the ground\nTwinkling lights all around\nThe scent of pine fills the air\nChristmas magic everywhere\n[Chorus]\nUnder the mistletoe tonight\nHearts aglow in the soft moonlight\nLaughter echoes\nSpirits bright\nIt’s Christmas time\nIt feels so right\n[Verse 2]\nStockings hung by the fire’s glow\nWarmth inside while the cold winds blow\nCookies baking\nSweet delight\nA season of joy shining bright\n[Chorus]\nUnder the mistletoe tonight\nHearts aglow in the soft moonlight\nLaughter echoes\nSpirits bright\nIt’s Christmas time\nIt feels so right\n[Bridge]\nCarols sung by candlelight\nStars above make the world feel tight\nPeace and love\nA season’s creed\nFilling hearts with all we need\n[Chorus]\nUnder the mistletoe tonight\nHearts aglow in the soft moonlight\nLaughter echoes\nSpirits bright\nIt’s Christmas time\nIt feels so right",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T15:59:32.468Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "prompt": "A song for Christmas",
      "style": "holiday, cheerful, male vocals",
      "duration": 158.48
    }
  ]
}
```

يمكن ملاحظة أننا حصلنا في هذه المرحلة على محتوى أغنيتين، بما في ذلك العنوان، وصورة المعاينة، وكلمات الأغنية، والصوت، والفيديو، وغيرها من المحتويات.

شرح الحقول كما يلي:

* success: ما إذا كان التوليد ناجحًا، فإذا نجح تكون القيمة `true`، وإلا فتكون `false`
* data: هي قائمة تحتوي على المعلومات التفصيلية للأغاني التي تم توليدها.
  * state: حالة توليد الأغنية، وتتضمن بشكل أساسي أربع حالات، كما يلي:
    * succeeded: تم التوليد بنجاح
    * pending: في قائمة الانتظار
    * running: قيد التنفيذ
    * error: فشل
  * id: معرّف الأغنية
  * title: عنوان الأغنية
  * image\_url: صورة غلاف الأغنية
  * lyric: كلمات الأغنية
  * audio\_url: عنوان الصوت النهائي للأغنية. ستُرجع المنصة عنوان Ace Data Cloud CDN بشكلٍ تفضيلي؛ وإذا فشلت الاستمرارية، فقد تُرجع عنوان الوسائط الأصلي، لذا يُرجى التنزيل في الوقت المناسب.
  * video\_url: ملف فيديو الأغنية، وعند فتحه يكون فيديو mp4.
  * created\_at: وقت الإنشاء
  * model: النموذج المستخدم، وعادةً ما يكون أحدث نموذج v3
  * style: النمط

## التوليد المخصص

إذا كنت ترغب في تخصيص توليد كلمات الأغنية، يمكنك إدخال الكلمات:

في هذه المرحلة، يمكن تمرير محتوى مشابه لما يلي في حقل `lyric`:

```
[Verse]\nSnowflakes falling all around\nGlistening white\nCovering the ground\nChildren laughing\nFull of delight\nIn this winter wonderland tonight\nSanta's sleigh\nUp in the sky\nRudolph's nose shining bright\nOh my\nHear the jingle bells\nRinging so clear\nBringing joy and holiday cheer\n[Verse 2]\nRoasting chestnuts by the fire's glow\nChristmas lights\nThey twinkle and show\nFamilies gathering with love and cheer\nSpreading warmth to everyone near
```

> ملاحظة: إن `\n` في كلمات الأغنية هنا هو رمز سطر جديد، وإذا كنت لا تعرف كيفية توليد كلمات الأغنية، يمكنك استخدام واجهة برمجة التطبيقات لتوليد كلمات الأغاني التي توفرها AceDataCloud لتوليد الكلمات عبر prompt، وواجهة البرمجة هي [Suno Lyrics Generation API](https://platform.acedata.cloud/documents/suno-lyrics).

بعد ذلك، لتخصيص توليد الأغنية بناءً على كلمات الأغنية والعنوان والنمط، يمكن تحديد المحتوى التالي:

* lyric: نص كلمات الأغنية
* custom: املأها بـ `true`، وهي تمثل التوليد المخصص، والقيمة الافتراضية لهذه المعلمة هي false، وتمثل استخدام `prompt` للتوليد.
* title: عنوان الأغنية.
* style: نمط الأغنية، اختياري.

مثال على التعبئة كما يلي:

![](https://cdn.acedata.cloud/qp3iba.png)

بعد إتمام التعبئة، يتم توليد الكود التالي تلقائيًا:

![](https://cdn.acedata.cloud/o5haei.png)

الكود المقابل:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/suno/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "prompt": "A song for Christmas",
  "model": "chirp-v4-5",
  "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
  "custom": true
}'
```

يُسمح بالاختبار، ويكون تأثير التوليد مشابهًا.

## ميزة التوليد المخصص لنمط المغني

إذا كنت ترغب في استخدام أسلوب مغنٍّ لتوليد أغنية، فقم أولاً بتوليد أغنية عبر الاستخدام الأساسي أعلاه،
وفي النهاية تحصل على الحاجة إلى تعيين هذه الأغنية كأسلوب مغنٍّ، ثم تحتاج إلى الدخول إلى [Suno Persona API](https://platform.acedata.cloud/documents/suno-persona) لإنشاء معلمة معرف أسلوب مغنٍّ `persona_id` استنادًا إلى معرف الموسيقى الذي تم إنشاؤه رسميًا `audio_id`، والمعلمات المحددة موضحة في الصورة أدناه:

![](https://cdn.acedata.cloud/pmzo3l.png)

بعد إكمال التعبئة، يتم إنشاء الكود تلقائيًا كما يلي:

![](https://cdn.acedata.cloud/a5g0nj.png)

كود Python المقابل:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/persona"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "audio_id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f",
    "name": "test"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

انقر للتشغيل، ويمكنك ملاحظة أنك ستحصل على نتيجة كما يلي:

```json theme={null}
{
  "success": true,
  "task_id": "7628b754-4fe7-4e79-bda4-806d0dd8bf6e",
  "data": {
    "persona_id": "e0d7319e-aa2a-44cb-b00a-916218d7cb0b"
  }
}
```

نستخدم `audio_id` و`persona_id` أعلاه، وهما `97efc9f4-0e8d-4b3e-88df-14568fa1b11f` و`e0d7319e-aa2a-44cb-b00a-916218d7cb0b` على التوالي، كبيانات المثال هذه. ثم يمكن تعيين المعلمة `action` إلى `artist_consistency` (إذا كان أسلوب المغني الجديد Persona-v2-vox، فيجب تعيين `action` إلى `artist_consistency_vox`)، وإدخال معرف الأغنية التي تحتاج إلى مواصلة توليدها، ومعرف أسلوب المغني، ومثال التعبئة كما يلي:

![](https://cdn.acedata.cloud/fukijq.png)

بعد إكمال التعبئة، يتم إنشاء الكود تلقائيًا كما يلي:

![](https://cdn.acedata.cloud/5uzk9d.png)

كود Python المقابل:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "artist_consistency",
    "prompt": "A song for Christmas",
    "model": "chirp-v4-5",
    "persona_id": "e0d7319e-aa2a-44cb-b00a-916218d7cb0b",
    "audio_id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

انقر للتشغيل، ويمكنك ملاحظة أنك ستحصل على نتيجة كما يلي:

```json theme={null}
{
  "success": true,
  "task_id": "9b732b1a-bd67-48bc-95e4-90140e06836f",
  "trace_id": "30fcd88e-7687-4137-92d7-913b58115204",
  "data": [
    {
      "id": "727a36e2-8dce-4df7-99e5-14e44635c80f",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-003",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:27:33.979Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 244.4
    },
    {
      "id": "3b33301a-b17e-4b25-8842-09b46dab1a36",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-004",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:27:33.979Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 229.88
    }
  ]
}
```

يمكن ملاحظة أن محتوى النتيجة يتطابق مع ما ورد أعلاه، وهذا يحقق وظيفة توليد الأغاني باستخدام أسلوب المغني.

## وظيفة مواصلة التوليد

إذا كنت ترغب في مواصلة توليد أغنية Suno تم إنشاؤها بالفعل، فيمكنك تعيين المعلمة `action` إلى `extend`، وإدخال معرف الأغنية التي تحتاج إلى مواصلة توليدها، ويتم الحصول على معرف الأغنية وفقًا للاستخدام الأساسي، ومن خلال ما سبق يمكن معرفة أنه في هذا الوقت يمكن رؤية أن معرف الأغنية هو:

```
"id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f"
```

> ملاحظة، `id` في كلمات الأغنية هنا هو معرف الأغنية بعد التوليد. إذا كنت لا تعرف كيفية توليد أغنية، فيمكنك الرجوع إلى الاستخدام الأساسي أعلاه لتوليد أغنية.

إذا كنت ترغب في مواصلة توليد أغنية رفعتها بنفسك، فيمكنك تعيين المعلمة `action` إلى `upload_extend`، وإدخال معرف الأغنية المرفوعة المخصصة التي تحتاج إلى مواصلة توليدها، ويتم الحصول على معرف الأغنية باستخدام [Suno Upload Generation API](https://platform.acedata.cloud/documents/suno-upload)، كما هو موضح في الصورة أدناه:

![](https://cdn.acedata.cloud/a0mn5e.png)

بعد ذلك، يجب تعبئة كلمات مقطع المتابعة، ويمكن تحديد الأسلوب:

* lyric: يُستخدم فقط لتوجيه كلمات المقطع المُولَّد حديثًا بعد `continue_at`، ولن يستبدل الكلمات الموجودة في الصوت المصدر قبل تلك النقطة الزمنية.
* custom: املأه بـ `true`، وهو ما يعني التوليد المخصص، والقيمة الافتراضية لهذه المعلمة هي false، مما يعني استخدام `prompt` للتوليد.
* style: أسلوب أغنية مقطع المتابعة، اختياري.
* continue\_at: حد المتابعة، بوحدة الثواني. على سبيل المثال، تشير 213.5 إلى بدء توليد المقطع اللاحق من الدقيقة الثالثة و33.5 ثانية.

> يُستخدم `extend` لمواصلة الإبداع إلى الأمام انطلاقًا من أغنية موجودة، وليس لتغيير كلمات الأغنية كاملة. إذا كنت ترغب في استخدام كلمات جديدة للأغنية كاملة من البداية، فيرجى استخدام `generate` لإعادة التوليد؛ وإذا كنت ترغب في إعادة أداء الأغنية بالرجوع إلى أغنية موجودة، فيمكنك استخدام `cover`. عند تمرير كلمات جديدة كاملة، لن يتم استبدال الكلمات الأصلية قبل `continue_at` أيضًا.

مثال التعبئة كما يلي:

![](https://cdn.acedata.cloud/zp9s42.png)

بعد إكمال التعبئة، يتم إنشاء الكود تلقائيًا كما يلي:

![](https://cdn.acedata.cloud/wwpw78.png)

ما تم الاحتفاظ به أدناه هو لقطة لاستدعاء تاريخي حقيقي، حيث إن `continue_at` يساوي ثانيتين، لذلك فإن أول ثانيتين فقط تنتميان إلى المحتوى الأصلي قبل حد الاستكمال. عند الاستكمال فعليًا بالقرب من نهاية الأغنية، يجب ضبط هذه القيمة على عدد الثواني المتوقع بدء الاستكمال عندها، وتوفير المقطع الجديد المراد غناؤه بعد الحد فقط في `lyric`.

كود Python المقابل:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "extend",
    "prompt": "A song for Christmas",
    "model": "chirp-v4-5",
    "audio_id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f",
    "continue_at": 2,
    "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
    "custom": True,
    "instrumental": False
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

انقر للتشغيل، ويمكن ملاحظة أنه سيتم الحصول على نتيجة كما يلي:

```json theme={null}
{
  "success": true,
  "task_id": "75b835d9-30d1-4641-8524-0aeedbdc9e1a",
  "trace_id": "44c41045-a2e1-4d19-aafc-7abd239d0d5c",
  "data": [
    {
      "id": "0a1e1b10-c36a-41c9-9bfb-b26d9d25db98",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-005",
      "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:38:35.509Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 165.92
    },
    {
      "id": "4334c5b4-0a44-4b26-a8f6-66cc4dbb8fc3",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-006",
      "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:38:35.509Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 158.84
    }
  ]
}
```

يمكن ملاحظة أن `lyric` في النتيجة سيُرجع نص كلمات الأغنية المستخدمة في مهمة الاستكمال هذه. هذا الحقل ليس تفريغًا حرفيًا للصوت النهائي الكامل؛ بالنسبة إلى `extend`، يستمر الصوت المصدر قبل `continue_at` في استخدام الكلمات الأصلية، وتُستخدم الكلمات الجديدة فقط لتوجيه مقطع الاستكمال.

## الحصول على الأغنية الكاملة

عادةً ما تتضمن نتيجة `extend` للنموذج الحالي الصوت المصدر قبل `continue_at` والمحتوى الجديد بعد الحد، لذا يُرجى أولًا تحديد ما إذا كانت أغنية كاملة بالفعل بناءً على المدة الفعلية ومحتوى الصوت المُرجع. إذا كان المُرجع مقطع استكمال مستقلًا، أو إذا كان من الضروري دمج سجل عدة عمليات استكمال صراحةً في أغنية واحدة، فاستخدم وظيفة الدمج بعد ذلك:

* action: المحتوى هو `concat`.
* audio\_id: معرّف آخر مقطع استكمال.

مثلًا، إذا كان معرّف الأغنية بعد التوسيع هو: 0a1e1b10-c36a-41c9-9bfb-b26d9d25db98، فيمكن ضبط المعلمات كما يلي:

```json theme={null}
{
  "action": "concat",
  "audio_id": "0a1e1b10-c36a-41c9-9bfb-b26d9d25db98"
}
```

تبقى المعلمات الأخرى دون تغيير، وما يُرجع هو أغنية كاملة، أي نتيجة دمج جميع مقاطع الأغنية، لكن النتيجة تحتوي على أغنية واحدة فقط، والمثال كما يلي:

```json theme={null}
{
  "success": true,
  "task_id": "0f794915-8418-4124-93f5-b7eb3a417167",
  "trace_id": "62afcce0-e7e5-44b8-8c2e-4bba12a4f414",
  "data": [
    {
      "id": "0efec7e0-11bf-4313-9981-2c0e7218d7dd",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-007",
      "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near\n[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:43:06.718Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 167.91997916666668,
      "concat_history": [
        {
          "continue_at": 2,
          "id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f",
          "infill": false,
          "source": "web",
          "type": "gen"
        },
        {
          "id": "0a1e1b10-c36a-41c9-9bfb-b26d9d25db98"
        }
      ]
    }
  ]
}
```

## إعادة إنتاج الموسيقى

عند الاستمرار في إنشاء أغنية بناءً على الأغنية الأصلية، قد لا يكون نمط الأغنية المُعادة مناسبًا تمامًا. إذا أردت إعادة إنتاج الأغنية التي تم إنشاؤها سابقًا (ويُدعم أيضًا إذا كانت موسيقى مرفوعة بشكل مخصص)، فيجب استخدام طريقة إعادة إنتاج الموسيقى، ويمكن عندها تحديد المحتوى التالي:

* action: المحتوى هو `cover`، وعند إجراء عملية إعادة إنتاج لموسيقى مرفوعة بشكل مخصص، يجب تحديد المحتوى على أنه: `upload_cover`.
* audio\_id: معرّف الأغنية التي تم إنشاؤها سابقًا.

على سبيل المثال، إذا كان معرّف الأغنية التي تم إنشاؤها سابقًا هو: 0a1e1b10-c36a-41c9-9bfb-b26d9d25db98، فيمكن تعيين المعلمات كما يلي:

```json theme={null}
{
  "action": "cover",
  "audio_id": "0a1e1b10-c36a-41c9-9bfb-b26d9d25db98",
  "prompt": "A song for Christmas",
  "model": "chirp-v4-5"
}
```

تبقى المعلمات الأخرى دون تغيير، وستكون النتيجة المعادة أغنية بعد إعادة إنتاجها، أي نتيجة إعادة إنتاج الأغنية التي تم إنشاؤها سابقًا، والمثال كما يلي:

```json theme={null}
{
  "success": true,
  "task_id": "b9d43d06-2e0a-4b5e-9e0d-7dfab32e00ab",
  "trace_id": "6c5e567d-0fdc-4c44-9b36-4090d9a75ff5",
  "data": [
    {
      "id": "6988fa57-f810-41cf-afab-7838db2c77dc",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-008",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:44:13.007Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 182.4
    },
    {
      "id": "ce98b991-0258-4f05-8245-e43d4efa8fb8",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-009",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:44:13.007Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 179.72
    }
  ]
}
```

النتيجة المُنشأة مشابهة لما ورد أعلاه، وبهذا تكتمل عملية إنشاء إعادة إنتاج للأغنية التي تم إنشاؤها سابقًا.

## استبدال المقطع

عند الحاجة إلى إجراء إبداع ثانوي من خلال عملية مستقلة لاستبدال مقطع من الأغنية بعد إنشائها، يمكن إجراء عملية استبدال لمقطع معين من الأغنية.

> ⚠️ **ملاحظة**: القيمة الافتراضية لـ `replace_section_result_mode` هي `full_song`: سيقوم النظام بدمج مرشحين تم إنشاؤهما حديثًا بشكل منفصل، وإرجاع أغنيتين كاملتين. إذا كنت تحتاج فقط إلى مرشحي مقاطع الاستبدال غير المدمجين بعد، فعيّنها صراحةً إلى `candidates`، ثم اختر المرشح لاستدعاء [دمج الموسيقى](#音乐拼接).

توضيح المعلمات كما يلي:

* action: المحتوى هو `replace_section`.
* audio\_id: معرّف الأغنية الأصلية (الأغنية المصدر التي سيتم استبدالها).
* model: نموذج إنشاء الأغنية.
* lyric: كلمات الأغنية الكاملة بعد الاستبدال (بما في ذلك المقطع المستبدل وسياقه، مع الحفاظ على الاتساق مع المحتوى في `prompt`).
* prompt: كلمات الأغنية الجديدة للمقطع الذي يجب استبداله.
* style: نمط الأغنية، اختياري.
* replace\_section\_start: وقت بداية المقطع المستبدل في الأغنية الأصلية (بالثواني).
* replace\_section\_end: وقت نهاية المقطع المستبدل في الأغنية الأصلية (بالثواني).
* replace\_section\_result\_mode: وضع الإرجاع، والقيمة الافتراضية هي `full_song`. يقوم `full_song` بدمج المرشحين الاثنين بشكل منفصل وإرجاع أغنيتين كاملتين؛ بينما يُرجع `candidates` مقطعين مرشحين لم يتم دمجهما بعد.

### الخطوة الأولى: بدء مهمة استبدال المقطع

على سبيل المثال، إذا كان معرّف الأغنية التي تم إنشاؤها سابقًا هو: 18db7ed0-2b8a-41db-91c1-b0781dcca0d4 (مدتها 94.12 ثانية)، وتريد استبدال اللازمة الموسيقية من الثانية 30 إلى الثانية 60 بكلمات جديدة، فيمكن تعيين المعلمات كما يلي:

```json theme={null}
{
  "action": "replace_section",
  "audio_id": "18db7ed0-2b8a-41db-91c1-b0781dcca0d4",
  "model": "chirp-v5-5",
  "custom": false,
  "instrumental": false,
  "lyric": "[مقدمة]\nقرع الطبول وصخب الصنوج، والفوانيس الحمراء معلقة عاليًا\n[مقطع 1]\nأصوات المفرقعات تودع العام القديم\nنسيم الربيع الدافئ يدخل إلى آلاف البيوت\nالأظرف الحمراء لهدية رأس السنة ترسم الابتسامة على الوجوه\nالأفعى الذهبية ترقص احتفالًا بالربيع الجديد\n[اللازمة]\nتتفتح أزهار البرقوق، وعبير الربيع يملأ الأرض\nتتفتح أزهار البرقوق، وعبير الربيع يملأ الأرض\nتتفتح أزهار البرقوق، وعبير الربيع يملأ الأرض\nتتفتح أزهار البرقوق، وعبير الربيع يملأ الأرض\n[مقطع 2]\nرائحة الزلابية تفوح في عشاء ليلة رأس السنة\nالفوانيس تتمايل لتنير لمّ الشمل",
  "prompt": "تتفتح أزهار البرقوق، وعبير الربيع يملأ الأرض\nتتفتح أزهار البرقوق، وعبير الربيع يملأ الأرض\nتتفتح أزهار البرقوق، وعبير الربيع يملأ الأرض\nتتفتح أزهار البرقوق، وعبير الربيع يملأ الأرض",
  "replace_section_start": 30.0,
  "replace_section_end": 60.0,
  "replace_section_result_mode": "full_song"
}
```

بشكل افتراضي، يتم إرجاع أغنيتين كاملتين تم وصلهما من مرشحين مختلفين. إذا تم تعيين `replace_section_result_mode` إلى `candidates`، فسيتم إرجاع مقطعي استبدال غير موصولين، ويكون الهيكل متسقًا مع المثال أدناه:

```json theme={null}
{
  "success": true,
  "task_id": "dd067075-a295-4160-8375-d5504327d55b",
  "trace_id": "c34f589b-9195-4d0b-af78-9c890e77609c",
  "data": [
    {
      "id": "364f9d8b-ca25-463b-9a5e-d0b7139e2d6a",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-010",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-011",
      "lyric": "[مقدمة]\nقرع الطبول وصخب الصنوج، والفوانيس الحمراء معلقة عاليًا\n[مقطع 1]\nأصوات المفرقعات تودع العام القديم\nنسيم الربيع الدافئ يدخل إلى آلاف البيوت\nالأظرف الحمراء لهدية رأس السنة ترسم الابتسامة على الوجوه\nالأفعى الذهبية ترقص احتفالًا بالربيع الجديد\n[اللازمة]\nتتفتح أزهار البرقوق، وعبير الربيع يملأ الأرض\nتتفتح أزهار البرقوق، وعبير الربيع يملأ الأرض\nتتفتح أزهار البرقوق، وعبير الربيع يملأ الأرض\nتتفتح أزهار البرقوق، وعبير الربيع يملأ الأرض\n[مقطع 2]\nرائحة الزلابية تفوح في عشاء ليلة رأس السنة\nالفوانيس تتمايل لتنير لمّ الشمل",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-05-06T06:55:00.000Z",
      "model": "chirp-v5-5",
      "state": "succeeded",
      "style": "",
      "duration": 45.16
    },
    {
      "id": "fae966ea-5f7f-4e80-9962-1c57963c7f8a",
      "title": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "model": "chirp-v5-5",
      "state": "succeeded",
      "duration": 33.8
    }
  ]
}
```

في وضع `candidates`، تكون مدة المقطعين الصوتيين المُعادين (45.16 ثانية و33.8 ثانية) أقصر بكثير من الأغنية الأصلية (94.12 ثانية)، وهما مقطعا استبدال يحتويان على قدر قليل من السياق، و**ليسا** الأغنية كاملة. يمكنك اختيار المرشح المُرضي ومتابعة وصله يدويًا. أما وضع `full_song` الافتراضي، فسيُكمل عمليتي الوصل ويُرجع مباشرة أغنيتين كاملتين.

### إرجاع الأغاني الكاملة مباشرة

إذا كنت ترغب في الحصول على الأغاني الكاملة مباشرة، يمكنك في الخطوة الأولى تعيين `replace_section_result_mode` إلى `full_song`. ستقوم الواجهة بوصْل المرشحين على التوالي وإرجاع أغنيتين كاملتين؛ وفي هذه الحالة لا حاجة لاستدعاء `concat` مرة أخرى.

### الخطوة الثانية: وصل مقطع الاستبدال بالأغنية الأصلية

بالنسبة للمقطع المختار أعلاه (مثلًا `364f9d8b-ca25-463b-9a5e-d0b7139e2d6a`)، ابدأ مهمة `concat` وفقًا للطريقة الواردة في قسم [وصل الموسيقى](#音乐拼接):

```json theme={null}
{
  "action": "concat",
  "audio_id": "364f9d8b-ca25-463b-9a5e-d0b7139e2d6a",
  "model": "chirp-v5-5"
}
```

ما يتم إرجاعه هو الأغنية الكاملة بعد الوصل، والمثال كما يلي:

```json theme={null}
{
  "success": true,
  "task_id": "5dbd4a78-0197-4ef3-9c16-8bddaf4f0c94",
  "trace_id": "580bd1da-2ad3-4d75-be1f-6c14bd4b489d",
  "data": [
    {
      "id": "365a9640-0452-4567-80f0-4f5a2a17ddd5",
      "title": "سنة جديدة سعيدة",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-012",
      "lyric": "[مقدمة]\nقرع الطبول وصخب الصنوج، والفوانيس الحمراء معلقة عاليًا\n[مقطع 1]\nأصوات المفرقعات تودع العام القديم\nنسيم الربيع الدافئ يدخل إلى آلاف البيوت\nالأظرف الحمراء لهدية رأس السنة ترسم الابتسامة على الوجوه\nالأفعى الذهبية ترقص احتفالًا بالربيع الجديد\n[اللازمة]\nتتفتح أزهار البرقوق، وعبير الربيع يملأ الأرض\nتتفتح أزهار البرقوق، وعبير الربيع يملأ الأرض\nتتفتح أزهار البرقوق، وعبير الربيع يملأ الأرض\nتتفتح أزهار البرقوق، وعبير الربيع يملأ الأرض\n[مقطع 2]\nرائحة الزلابية تفوح في عشاء ليلة رأس السنة\nالفوانيس تتمايل لتنير لمّ الشمل",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-05-06T06:56:46.057Z",
      "model": "chirp-v5-5",
      "state": "succeeded",
      "style": "رأس السنة الصينية التقليدية، احتفالي، غناء نسائي، مبهج",
      "duration": 105.28
    }
  ]
}
```

في هذه المرحلة، تمّت استعادة `duration` إلى طول الأغنية الكامل (105.28 ثانية، وهو ما يعادل تقريبًا طول الأغنية الأصلية)، ويشير `audio_url` إلى الأغنية الكاملة بعد اكتمال الاستبدال. بهذا تكتمل عملية الإبداع الثانوي: "إنشاء → استبدال مقطع → دمج الأغنية كاملة".

## فصل الغناء والموسيقى

عندما تحتاج، بعد إنشاء الأغنية، إلى إجراء إبداع ثانوي من خلال التعامل بشكل منفصل مع الموسيقى المصاحبة والغناء، يمكنك فصل الموسيقى المصاحبة الخالصة والغناء المنفرد. يمكنك حينها تحديد المحتوى التالي:

* action：القيمة هي `stems`.
* audio\_id：معرّف الأغنية التي تم إنشاؤها سابقًا.

على سبيل المثال، إذا كان معرّف الأغنية بعد إنشائها هو: ec13e502-d043-4eb2-92ee-e900c6da69d1، فيمكنك ضبط المعلمات كما يلي:

```json theme={null}
{
  "action": "stems",
  "audio_id": "ec13e502-d043-4eb2-92ee-e900c6da69d1"
}
```

يمكنك الحصول على نتيجة فصل الغناء والموسيقى عبر المعلمات أعلاه، والنتيجة كما يلي:

```json theme={null}
{
  "success": true,
  "task_id": "4050affc-f8a6-4cba-a86c-bf201eed053d",
  "trace_id": "5107ee58-687d-422f-9195-fa0e82e1fcc8",
  "data": [
    {
      "id": "e3de0928-085a-42c4-b982-3b24738d1989",
      "title": "زيّن السماء - الغناء",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-013",
      "lyric": "[المقطع]\nترقص رقاقات الثلج فوق الأسطح العالية\nيملأ ضحك الأطفال السماء\nترن الترانيم من أجراس الكنائس بصوت عالٍ\nالأعياد حشد مبهج\n[المقطع 2]\nعصي الحلوى والكاكاو الدافئ\nملتفّون بإحكام في عاصفتنا الخاصة\nجوارب معلقة بالأحلام والبهجة\nالسحر ينمو كل عام\n[اللازمة]\nزيّن السماء بالنجوم المتلألئة\nبهجة العيد تبدو لنا ولنا\nغنّ أغاني الحب والنور\nيتوهج عيد الميلاد نقيًا ومشرقًا جدًا\n[المقطع 3]\nحكايات بجانب المدفأة من زمن بعيد\nترقص حيوانات الرنة في التوهج الجليدي\nبريق الأشجار دائمة الخضرة والزينة اللامعة\nوقت عيد الميلاد حلم جميل\n[الجسر]\nالقلوب ممتلئة بالأصدقاء والأقارب\nالهدال كي ينتصر الحب\nنتشارك هدايا الحب والأمل\nروح عيد الميلاد في كل مكان\n[اللازمة]\nزيّن السماء بالنجوم المتلألئة\nبهجة العيد تبدو لنا ولنا\nغنّ أغاني الحب والنور\nيتوهج عيد الميلاد نقيًا ومشرقًا جدًا",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-001",
      "created_at": "2025-01-05T07:49:16.881Z",
      "model": "",
      "state": "succeeded",
      "style": "عطلات، مرح",
      "duration": 174.16
    },
    {
      "id": "ad5d7c89-709c-4eb4-a5a6-72f9f5e57fdb",
      "title": "زيّن السماء - موسيقى مصاحبة",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-014",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-002",
      "created_at": "2025-01-05T07:49:16.892Z",
      "model": "",
      "state": "succeeded",
      "style": "عطلات، مرح",
      "duration": 174.16
    }
  ]
}
```

النتيجة المُنشأة مماثلة لما سبق، وبذلك تكتمل عملية فصل الغناء والموسيقى للأغنية التي تم إنشاؤها سابقًا.

## فصل الغناء والموسيقى لجميع المسارات

عندما تحتاج، بعد إنشاء الأغنية، إلى إجراء عملية فصل الغناء والموسيقى لجميع المسارات، يمكنك تحديد المحتوى التالي:

* action：القيمة هي `all_stems`.
* audio\_id：معرّف الأغنية التي تم إنشاؤها سابقًا.

على سبيل المثال، إذا كان معرّف الأغنية بعد إنشائها هو: bdf23a5a-59f5-4103-b452-054a824a7f9f، فيمكنك ضبط المعلمات كما يلي:

```json theme={null}
{
  "action": "all_stems",
  "audio_id": "bdf23a5a-59f5-4103-b452-054a824a7f9f"
}
```

يمكنك الحصول على نتيجة فصل الغناء والموسيقى لجميع المسارات عبر المعلمات أعلاه، والنتيجة كما يلي:

```json { theme={null}
  "success": true,
  "task_id": "f4b16fb9-8478-4857-88c7-b9a1f0bb9518",
  "trace_id": "9c560ebd-4fc6-4bdb-988a-8890160a92fb",
  "data": [
    {
      "id": "f86ca64a-9519-4ea7-a592-52438e001412",
      "title": "أوتار الأمان (الغناء)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-015",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "99e649a7-a394-47b9-a915-d7f847285a36",
      "title": "أوتار الأمان (الغناء الخلفي)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-016",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "6d710bf7-809f-4fdc-bb63-b8cb3a456d42",
      "title": "أوتار الأمان (الطبول)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-017",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    },
{
      "id": "e05f07e3-7d80-4713-8e51-7f176c733543",
      "title": "وتر الأمان (باس)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-018",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "نجح",
      "duration": 154.92
    }, {
      "id": "93fe7cd8-62fd-4739-b78e-142c7e0b8562",
      "title": "وتر الأمان (غيتار)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-019",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "نجح",
      "duration": 154.92
    }, {
      "id": "8367d71c-fdd3-441c-8ebe-70c33cca821b",
      "title": "وتر الأمان (لوحة مفاتيح)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-020",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "نجح",
      "duration": 154.92
    }, {
      "id": "28c03590-731c-416e-8fd3-95cdb3d75043",
      "title": "وتر الأمان (إيقاع)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-021",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "نجح",
      "duration": 154.92
    }, {
      "id": "3d4c1a28-4e1c-485a-8201-d21bb93aca2f",
      "title": "وتر الأمان (وتريات)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-022",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "نجح",
      "duration": 154.92
    }, {
      "id": "b9db8ded-01ec-4e37-b8a5-64aab3a814c2",
      "title": "وتر الأمان (سينث)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-023",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "نجح",
      "duration": 154.92
    }, {
      "id": "10a5248e-32e6-42b9-8da1-678a8a392aef",
      "title": "وتر الأمان (مؤثرات)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-024",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "نجح",
      "duration": 154.92
    }, {
      "id": "2d272128-111f-4901-8f62-5ae1eb43095a",
      "title": "وتر الأمان (نحاسيات)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-025",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "نجح",
      "duration": 154.92
    }, {
      "id": "4a7c19a5-f8d4-4e4a-add9-aa0bad9307cc",
      "title": "وتر الأمان (آلات نفخ خشبية)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-026",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "نجح",
      "duration": 154.92
    }, {
      "id": "1ca774f9-3e75-48a6-941b-808875eadcd2",
      "title": "وتر الأمان (غناء)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-027",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "نجح",
      "duration": 154.92
    },
{
      "id": "14c5ffc7-addf-4fee-afd2-4b8b3e7ee470",
      "title": "وتر الأمان (غناء داعم)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-028",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "نجح",
      "duration": 154.92
    }, {
      "id": "9d044557-450d-48ab-90dc-8eaf6f1cdb6c",
      "title": "وتر الأمان (طبول)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-029",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "نجح",
      "duration": 154.92
    }, {
      "id": "efd052d0-c12f-47b3-8282-1f3ef7610e1f",
      "title": "وتر الأمان (باس)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-030",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "نجح",
      "duration": 154.92
    }, {
      "id": "5775372b-292e-4420-96ef-60e57a60cc1f",
      "title": "وتر الأمان (غيتار)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-031",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "نجح",
      "duration": 154.92
    }, {
      "id": "dab3f220-19cd-408e-9b96-30ec18f5b049",
      "title": "وتر الأمان (لوحة مفاتيح)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-032",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "نجح",
      "duration": 154.92
    }, {
      "id": "2d0cd6d4-af82-4bb5-86fe-d92bdb367157",
      "title": "وتر الأمان (إيقاع)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-033",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "نجح",
      "duration": 154.92
    }, {
      "id": "f3191a1a-5e8d-4afe-b638-3add222d52cd",
      "title": "وتر الأمان (أوتار)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-034",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "نجح",
      "duration": 154.92
    }, {
      "id": "a8834ea5-200b-4206-a812-9780ef336660",
      "title": "وتر الأمان (سينث)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-035",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "نجح",
      "duration": 154.92
    }, {
      "id": "f50d1a31-ef72-400a-b8ae-0367849d007d",
      "title": "وتر الأمان (مؤثرات)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-036",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "نجح",
      "duration": 154.92
    }, {
      "id": "cb581673-23cc-40d6-9f9b-0f76720f0d18",
      "title": "وتر الأمان (نحاسيات)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-037",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "نجح",
      "duration": 154.92
    },
{
      "id": "d91cfb52-f0a3-4546-bf8a-2ad14c3775a5",
      "title": "安全之弦 (Woodwinds)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-038",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }
  ]
}
```

النتيجة المُولَّدة مشابهة لما ورد أعلاه، وبهذا تكتمل عملية فصل الصوت والموسيقى للأغنية المُولَّدة سابقًا.

## إضافة مسار صوتي

يُنشئ `add_stem` مسار الآلة الموسيقية أو الصوت المستهدف للصوت المحدد، عبر استدعاء `POST /suno/audios`.

* مطلوب: `action`، `audio_id`، `stem_type`.
* اختياري: `model`، `prompt`، `title`، `style`، `negative_tags`، `weirdness`، `style_influence`، `audio_weight`، `max_mode`، `variety`.
* الفوترة: 0.672 Credits في الوضع العادي؛ و1.344 Credits عندما تكون `max_mode` بقيمة `true`.

```json theme={null}
{
  "action": "add_stem",
  "audio_id": "dead4ee5-df4d-417b-8f7e-717722fae51a",
  "stem_type": "bass",
  "model": "chirp-v6",
  "prompt": "Add warm bass guitar",
  "style": "minimal piano pulse with warm bass guitar",
  "negative_tags": "vocals",
  "variety": "normal",
  "max_mode": false,
  "async": true
}
```

استجابة الحالة النهائية:

```json theme={null}
{
  "success": true,
  "task_id": "82851953-9590-4334-8bb8-ae30ccadc815",
  "trace_id": "862bbcce-1678-44ff-982d-8b439c126a5e",
  "data": [
    {
      "id": "0adc26ca-2720-4c69-b237-457a986d70e3",
          "audio_url": "https://cdn.acedata2.cloud/suno/0adc26ca-2720-4c69-b237-457a986d70e3.mp3",
      "model": "chirp-v6",
      "state": "succeeded",
      "duration": 12.8
    },
    {
      "id": "e2d39a6c-1d20-4a40-adaf-b2551815d869",
          "audio_url": "https://cdn.acedata2.cloud/suno/e2d39a6c-1d20-4a40-adaf-b2551815d869.mp3",
      "model": "chirp-v6",
      "state": "succeeded",
      "duration": 12.36
    }
  ],
  "cost": {"amount": 0.6048, "currency": "credit", "list_amount": 0.672}
}
```

## استخراج مسار صوتي

يستخرج `extract_stem` المسار الصوتي المستهدف من الصوت المحدد، ويُرجع في الوقت نفسه النسخة التكميلية بعد إزالة هذا المسار الصوتي، عبر استدعاء `POST /suno/audios`.

* مطلوب: `action`، `audio_id`، `stem_type`.
* اختياري: `audio_format`، يدعم عقد القناة المزدوجة العام الحالي `mp3` فقط.
* الفوترة: 1.12 Credits.

```json theme={null}
{
  "action": "extract_stem",
  "audio_id": "dead4ee5-df4d-417b-8f7e-717722fae51a",
  "stem_type": "bass",
  "audio_format": "mp3",
  "async": true
}
```

تحتفظ `data` في استجابة الحالة النهائية بقائمة صوتية مسطحة، ويمثل `stem_sets` علاقة المطابقة بين المسار الصوتي المستهدف والمسار الصوتي التكميلي:

```json theme={null}
{
  "success": true,
  "task_id": "ae9557d0-4ff7-4a35-bcde-d881e78fbfe5",
  "trace_id": "82c51a55-7627-41a5-b72b-1b9775ca25f2",
  "data": [
    {"id":"3084d7e1-4278-4733-8b56-56f7ecf3f859","title":"(Bass)","audio_url":"https://cdn.acedata2.cloud/suno/3084d7e1-4278-4733-8b56-56f7ecf3f859.mp3","model":"chirp-v6","state":"succeeded","duration":12.8,"stem_set":1},
    {"id":"19b83ca9-a51d-494f-a41d-5b0957f3295e","title":"(Without Bass)","audio_url":"https://cdn.acedata2.cloud/suno/19b83ca9-a51d-494f-a41d-5b0957f3295e.mp3","model":"chirp-v6","state":"succeeded","duration":12.8,"stem_set":1},
    {"id":"7eb431e8-f4db-4915-902e-0e89d2b3185a","title":"(Bass)","audio_url":"https://cdn.acedata2.cloud/suno/7eb431e8-f4db-4915-902e-0e89d2b3185a.mp3","model":"chirp-v6","state":"succeeded","duration":12.8,"stem_set":2},
    {"id":"495d29cc-5790-4d0a-8b95-9551a6127b61","title":"(Without Bass)","audio_url":"https://cdn.acedata2.cloud/suno/495d29cc-5790-4d0a-8b95-9551a6127b61.mp3","model":"chirp-v6","state":"succeeded","duration":12.8,"stem_set":2}
  ],
  "stem_sets": [
    {"stem_type":"bass","isolated":{"id":"3084d7e1-4278-4733-8b56-56f7ecf3f859","state":"succeeded","stem_set":1},"remainder":{"id":"19b83ca9-a51d-494f-a41d-5b0957f3295e","state":"succeeded","stem_set":1}},
    {"stem_type":"bass","isolated":{"id":"7eb431e8-f4db-4915-902e-0e89d2b3185a","state":"succeeded","stem_set":2},"remainder":{"id":"495d29cc-5790-4d0a-8b95-9551a6127b61","state":"succeeded","stem_set":2}}
  ],
  "cost": {"amount": 1.008, "currency": "credit", "list_amount": 1.12}
}
```

## إنشاء مؤثرات صوتية

يُنشئ `sounds` مؤثرات صوتية لمرة واحدة أو قابلة للتكرار بناءً على وصف نصي، عبر استدعاء `POST /suno/audios`.

* مطلوب: `action`، `sound`، `sound_type`.
* اختياري: `model`، `bpm`، `key`، `audio_format`؛ يدعم `audio_format` حاليًا `mp3` فقط.
* `sound_type`: `one-shot` أو `loop`.
* الفوترة: 0.112 Credits.

```json theme={null}
{
  "action": "sounds",
  "sound": "single soft analog synth pluck, no reverb",
  "sound_type": "one-shot",
  "model": "chirp-v6",
  "bpm": 120,
  "key": "C",
  "audio_format": "mp3",
  "async": true
}
```

```json theme={null}
{
  "success": true,
  "task_id": "f6716546-d118-40a0-ad15-09999f9f22ba",
  "trace_id": "da4c7895-e494-4bd8-83bd-132e006c94e3",
  "data": [
    {"id":"b3cd3e7d-96e4-48ef-abde-73c7ddee8b4a","title":"single soft analog synth pluck, no reverb","audio_url":"https://cdn.acedata2.cloud/suno/b3cd3e7d-96e4-48ef-abde-73c7ddee8b4a.mp3","model":"chirp-v6","state":"succeeded","duration":10},
    {"id":"f1517867-b76a-4cdf-b006-9ce6e653e0a5","title":"single soft analog synth pluck, no reverb","audio_url":"https://cdn.acedata2.cloud/suno/f1517867-b76a-4cdf-b006-9ce6e653e0a5.mp3","model":"chirp-v6","state":"succeeded","duration":10}
  ],
  "cost": {"amount": 0.1008, "currency": "credit", "list_amount": 0.112}
}
```

## ضبط سرعة الصوت

يضبط `adjust_speed` سرعة تشغيل الصوت المحدد، من خلال استدعاء `POST /suno/audios`.

* مطلوب: `action`، و`audio_id`، و`speed_multiplier`، و`title`.
* اختياري: `keep_pitch`.
* `speed_multiplier`: النطاق من 0.25 إلى 4.
* الفوترة: 0.28 Credits.

```json theme={null}
{
  "action": "adjust_speed",
  "audio_id": "dead4ee5-df4d-417b-8f7e-717722fae51a",
  "speed_multiplier": 1.1,
  "keep_pitch": true,
  "title": "Suno contract verification speed 1.1x",
  "async": true
}
```

مدة الصوت المصدر هي 9.8 ثانية، ونتيجة السرعة 1.1x هي 8.909090909 ثانية:

```json theme={null}
{
  "success": true,
  "task_id": "c5860fdd-76b1-40a1-b5b5-ec047e471c8a",
  "trace_id": "292ed097-3631-441c-ac80-52f326b62726",
  "data": [
    {
      "id": "02534b52-45a7-4961-834a-f473a407e62c",
      "title": "Suno contract verification speed 1.1x",
      "audio_url": "https://cdn.acedata2.cloud/suno/02534b52-45a7-4961-834a-f473a407e62c.mp3",
      "model": "chirp-v6",
      "state": "succeeded",
      "duration": 8.909090909090908
    }
  ],
  "cost": {"amount": 0.252, "currency": "credit", "list_amount": 0.28}
}
```

يتميز نموذج التوليد بالعشوائية. تضمن الواجهة اتساق دلالات المعلمات وحالة المهمة وبنية الاستجابة، ولا تضمن توليد شكل موجي متطابق تمامًا عبر الطلبات المختلفة.

## المعلمات المتقدمة للتوليد المخصص

يسمح الرسمي باستخدام المعلمات المتقدمة `weirdness`==>`Weirdness`، و`style_influence`==>`Style Influence`، و`audio_weight`==>`Audio Influence` للتوليد في الوضع المخصص، وذلك وفقًا للأمثلة الرسمية التالية:

![](https://cdn.acedata.cloud/1xonxy.png)

تتراوح جميع المعلمات المتقدمة بين 0 و1، والمعلمات المحددة موضحة في الشكل التالي:

![](https://cdn.acedata.cloud/7i94ih.png)

بعد إكمال التعبئة، يتم توليد الكود التالي تلقائيًا:

![](https://cdn.acedata.cloud/2dlbo6.png)

كود Python المقابل:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "generate",
    "model": "chirp-v4-5",
    "lyric": "Hello Hello Hello ",
    "custom": True,
    "weirdness": 0.4,
    "style_influence": 0.4,
    "audio_weight": 0.4
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

انقر للتشغيل، ويمكن ملاحظة أنه سيتم الحصول على نتيجة كما يلي:

```json theme={null}
{
  "success": true,
  "task_id": "2f3aa682-e1a7-43a9-9fbb-ed0ce8668a4b",
  "trace_id": "07408194-7deb-4a52-a36d-9a9a13143b5f",
  "data": [
    {
      "id": "c66e2077-7580-43f2-9937-c67a8afcd8bd",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-039",
      "lyric": "Hello Hello Hello ",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-07-10T12:54:35.199Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 187.92
    },
    {
      "id": "a922f97b-307c-4c4d-aae3-a47ba8202a10",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-040",
      "lyric": "Hello Hello Hello ",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-07-10T12:54:35.199Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 229.64
    }
  ]
}
```

بهذه الطريقة، يتم استخدام المعلمات المتقدمة لتوليد أغنية مخصصة، وتكون النتيجة مشابهة لما سبق.

## التحكم في مدة الأغنية

بشكل افتراضي، يحدد النموذج مدة الأغنية المولدة بنفسه، وعادةً ما تكون بين 30 ثانية و4 دقائق. إذا كانت هناك حاجة إلى منتج نهائي أطول أو أقصر، يمكن تحديد المدة المطلوبة عبر المعلمة `duration`، ووحدتها الثانية، وتكون قيمتها عددًا صحيحًا بين 10 و360.

تُستخدم هذه المعلمة لتوليد الأغاني في الوضع المخصص (`custom` هو `true`). تجدر الإشارة بشكل خاص إلى أن `duration` هو **تلميح توجهي وليس قيدًا صارمًا**: سيشير النموذج إلى هذه القيمة أثناء الإبداع، لكنه لا يضمن تحقيقها. في الاختبارات الفعلية، تكون المدة الفعلية عادةً أقصر بكثير من القيمة المطلوبة، وقد تختلف مدة الأغنيتين المعادتين من الطلب نفسه بعدة أضعاف. حتى مع الطلبات المتطابقة تمامًا، قد تختلف المدة التي يتم الحصول عليها من عمليات الإرسال المتعددة بشكل كبير. لذلك لا تستخدمه كتحكم دقيق في المدة، وإذا كانت هناك حاجة تجاريًا إلى مدة ثابتة، فقم بقص المنتج النهائي بنفسك أو أعد المحاولة بعد الحصول عليه.

كود Python المقابل:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "generate",
    "model": "chirp-v5-5",
    "custom": True,
    "title": "Under the City Lights",
    "style": "lo-fi piano",
    "lyric": "[Verse]\nSunrise creepin\nGold on the floor\n[Chorus]\nUnder the city lights\n",
    "duration": 330
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

ما يجب الانتباه إليه هو أن `duration` في الطلب هي **المدة المتوقعة**، بينما حقل `duration` لكل أغنية في `data` ضمن الاستجابة هو **المدة الفعلية** لتلك الأغنية. الاسمان متماثلان لكن المعنى مختلف، ولا يُضمن أن تساوي المدة الفعلية القيمة المتوقعة. يُعد طول كلمات الأغنية أحد العوامل الرئيسية التي تؤثر في مدة المنتج النهائي؛ وإذا كنت بحاجة إلى منتج نهائي أطول، فمن المستحسن تقديم كلمات أكثر اكتمالًا في الوقت نفسه.

ستتحقق الواجهة من أن `duration` يجب أن تكون عددًا صحيحًا من 10 إلى 360؛ لكنها تظل مجرد هدف للتوليد، وليست ضمانًا لطول المنتج النهائي.

## ميزة Add Insterumental

في أغسطس 2025، أطلقت suno حديثًا ميزة Add Insterumental. تحتاج أولًا إلى رفع أغنية غنائية مجردة دون مرافقة موسيقية، لكي تساعدك suno في إضافة الموسيقى إليها. يمكنك أولًا الذهاب إلى [Suno Upload API](https://platform.acedata.cloud/documents/suno-upload) لرفع أغنية غنائية مجردة دون مرافقة موسيقية، وتكون العملية المقابلة كما هو موضح في الصورة أدناه:

![](https://cdn.acedata.cloud/fxl914.png)

ثم تحتاج إلى تسجيل `audio_id` بعد الرفع، والنتيجة المحددة كما هو موضح في الصورة أدناه:

![](https://cdn.acedata.cloud/47t6wj.png)

وأخيرًا، تم الحصول على `audio_id` وهو: 92254cab-3372-4d9e-bce9-cdcfdbc39070، ثم نحتاج أيضًا إلى تعبئة المعلمات التالية:

* action: المحتوى هو `underpainting`.
* underpainting\_start: وقت البدء لإضافة المرافقة الموسيقية إلى الأغنية المرفوعة، والقيمة الافتراضية هي 0.
* underpainting\_end: وقت الانتهاء لإضافة المرافقة الموسيقية إلى الأغنية المرفوعة، ويجب أن يكون أقل من المدة الإجمالية للأغنية.
* audio\_id: معرّف الأغنية الغنائية المجردة دون مرافقة موسيقية التي تم رفعها.
* style: نمط المرافقة الموسيقية، ومن الأفضل عدم استخدام كلمات لأنها مرافقة موسيقية في النهاية.

بعد إكمال التعبئة، يتم إنشاء الكود تلقائيًا كما يلي:

![](https://cdn.acedata.cloud/8x1ic6.png)

كود Python المقابل:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "underpainting",
    "model": "chirp-v4-5",
    "style": "Pop rap, uplifting, magnetic male vocals, piano, synth, electric guitar, driving bass, clear structure",
    "audio_id": "92254cab-3372-4d9e-bce9-cdcfdbc39070",
    "underpainting_end": 120
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

انقر على التشغيل، ويمكنك ملاحظة أنه سيتم الحصول على نتيجة كما يلي:

```json theme={null}
{
  "success": true,
  "task_id": "822d2e14-c535-4d48-a4e5-1b6ab00b04a7",
  "trace_id": "257eac2c-8e4f-44d0-8454-5e215111eefa",
  "data": [
    {
      "id": "2788cd21-bd84-422d-beb5-859c60fbf5b6",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-041",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-08-27T15:25:42.548Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "Pop rap, uplifting, magnetic male vocals, piano, synth, electric guitar, driving bass, clear structure",
      "duration": 10.16
    },
    {
      "id": "a4bb7220-e971-4cbf-a626-b86c648bcf55",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-042",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-08-27T15:25:42.548Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "Pop rap, uplifting, magnetic male vocals, piano, synth, electric guitar, driving bass, clear structure",
      "duration": 2.52
    }
  ]
}
```

وبهذا تكتمل عملية إضافة المرافقة الموسيقية إلى الأغنية الغنائية المجردة دون مرافقة موسيقية التي تم رفعها، والنتيجة مشابهة لما ورد أعلاه.

## ميزة Add Vocals

في أغسطس 2025، أطلقت suno حديثًا ميزة Add Vocals. تحتاج أولًا إلى رفع مقطوعة موسيقية خالصة، لكي تقوم suno بكتابة الكلمات وإنتاج غناء بشري. يمكنك أولًا الذهاب إلى [Suno Upload API](https://platform.acedata.cloud/documents/suno-upload) لرفع أغنية غنائية مجردة دون مرافقة موسيقية، وتكون العملية المقابلة كما هو موضح في الصورة أدناه:

![](https://cdn.acedata.cloud/fxl914.png)

ثم تحتاج إلى تسجيل `audio_id` بعد الرفع، والنتيجة المحددة كما هو موضح في الصورة أدناه:

![](https://cdn.acedata.cloud/47t6wj.png)

وأخيرًا، تم الحصول على `audio_id` وهو: 92254cab-3372-4d9e-bce9-cdcfdbc39070، ثم نحتاج أيضًا إلى تعبئة المعلمات التالية:

* action: المحتوى هو `overpainting`.
* overpainting\_start: وقت البدء لإضافة الصوت البشري إلى الأغنية المرفوعة، والقيمة الافتراضية هي 0.
* overpainting\_end: وقت الانتهاء لإضافة الصوت البشري إلى الأغنية المرفوعة، ويجب أن يكون أقل من المدة الإجمالية للأغنية.
* audio\_id: معرّف الأغنية الغنائية المجردة دون مرافقة موسيقية التي تم رفعها.
* custom: يجب استخدام الوضع المخصص في هذا الوضع لإدخال كلمات الأغنية.
* lyric: كلمات الأغنية المُدخلة في الوضع المخصص.
* style: نمط المرافقة الموسيقية.

بعد إكمال التعبئة، يتم إنشاء الكود تلقائيًا كما يلي:

![](https://cdn.acedata.cloud/a4pbes.png)

كود Python المقابل:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "overpainting",
    "model": "chirp-v4-5",
    "lyric": "Yea your were the best I could get \\nBut I knew that it couldn’t last \\nStayed down since we were friends \\nHad to leave those thoughts in the past \\nMade like 40k just last week \\nOn top of the 20 with my babe\\ndon’t care for what niggas say",
    "custom": True,
    "audio_id": "92254cab-3372-4d9e-bce9-cdcfdbc39070",
    "overpainting_end": 120
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

انقر للتشغيل، ويمكنك ملاحظة أنك ستحصل على نتيجة، كما يلي:

```json theme={null}
{
  "success": true,
  "task_id": "31bb250e-6614-49ec-ac85-631f224daeba",
  "trace_id": "efe8e7f3-9a65-4f13-a9f8-51e8478899df",
  "data": [
    {
      "id": "a597f945-64df-4722-a631-d436450832bd",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-043",
      "lyric": "Yea your were the best I could get \\nBut I knew that it couldn’t last \\nStayed down since we were friends \\nHad to leave those thoughts in the past \\nMade like 40k just last week \\nOn top of the 20 with my babe\\ndon’t care for what niggas say",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-08-27T15:33:51.550Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "",
      "duration": 105.32
    },
    {
      "id": "b41a8b91-3d88-4ebd-a6cf-732764b24954",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-044",
      "lyric": "Yea your were the best I could get \\nBut I knew that it couldn’t last \\nStayed down since we were friends \\nHad to leave those thoughts in the past \\nMade like 40k just last week \\nOn top of the 20 with my babe\\ndon’t care for what niggas say",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-08-27T15:33:51.550Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "",
      "duration": 148.16
    }
  ]
}
```

بهذه الطريقة تكتمل عملية إضافة صوت بشري إلى أغنية غنائية مرفوعة دون مرافقة صوتية، والنتيجة مشابهة لما سبق.

## وظيفة Remaster

في ديسمبر 2025، أطلق suno وظيفة Remaster جديدة، ويمكن لهذه الوظيفة إعادة إنشاء الأغاني، ولا يمكن استخدامها عبر حسابات مختلفة، ثم نحتاج أيضًا إلى ملء المعلمات التالية:

* action: المحتوى هو `remaster`.
* audio\_id: معرّف الأغنية التي تحتاج إلى إعادة إنشائها.
* model: يدعم فقط v4.5+ وv5.
* variation\_category: مدعوم فقط في إصدارات v5 وما فوق، وله 3 قيم فقط: high وnormal وsubtle.

بعد إكمال الملء، يتم إنشاء الكود تلقائيًا كما يلي:

![](https://cdn.acedata.cloud/7h4zmw.png)

كود Python المقابل:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "remaster",
    "variation_category": "high",
    "audio_id": "21fd46d4-45c3-4826-bec9-3f3df667902e"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

انقر للتشغيل، ويمكنك ملاحظة أنك ستحصل على نتيجة، كما يلي:

```json theme={null}
{
  "success": true,
  "task_id": "791ee74c-9363-4352-afe7-babb19b89899",
  "trace_id": "77acda57-c3d4-4e11-a506-4f50e0609916",
  "data": [
    {
      "id": "b0515cdf-9cb5-46cd-b0fe-10a239dc9274",
      "title": "Navidad en costura  (Remastered)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-045",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-046",
      "lyric": "En Teror las clases siguen,\nni en Navidad hay parón;\ncose el grupo entre villancicos\ny un buen trocito de turrón.\nLa Popular abre sus puertas,\ny el taller suena mejor;\nhilo, aguja y canto alegre\nlo pasaremos mejor\nSeguimos en las costuras,\ncon música y diversión;\nlos alumnos comeremos\nGolosinas un montón ",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-12-04T13:09:59.936Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "Villancico",
      "duration": 32.2
    },
    {
      "id": "06edab94-a4f9-4c0c-abac-a2e8a97c76a8",
      "title": "Navidad en costura  (Remastered)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-047",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-048",
      "lyric": "En Teror las clases siguen,\nni en Navidad hay parón;\ncose el grupo entre villancicos\ny un buen trocito de turrón.\nLa Popular abre sus puertas,\ny el taller suena mejor;\nhilo, aguja y canto alegre\nlo pasaremos mejor\nSeguimos en las costuras,\ncon música y diversión;\nlos alumnos comeremos\nGolosinas un montón ",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-12-04T13:09:59.936Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "Villancico",
      "duration": 32.2
    }
  ]
}
```

بهذه الطريقة تكتمل عملية إعادة إنشاء أغنية تم إنشاؤها بالفعل، والنتيجة مشابهة لما سبق.

## وظيفة إنشاء المزج Mashup

في ديسمبر 2025، أطلق suno وظيفة Mashup جديدة، ويمكن لهذه الوظيفة إنشاء أغنية بناءً على أغنيتين مرجعيتين، ثم نحتاج أيضًا إلى ملء المعلمات التالية:

* action: المحتوى هو `mashup`.
* mashup\_audio\_ids: معرّفا الأغنيتين المرجعيتين.
  填写完毕后，自动生成的代码如下：

![](https://cdn.acedata.cloud/8mo82l.png)

对应的 Python 代码：

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "mashup",
    "lyric": "Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nSambuy come, Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\nSambuy come back",
    "model": "chirp-v4-5",
    "custom": True,
    "instrumental": False,
    "mashup_audio_ids": ["9f102969-0024-479e-b38f-c0c5db21383d","6aebb715-701c-433f-b976-a7ff5cf16255"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

انقر على التشغيل، وستجد أنه سيتم الحصول على نتيجة كما يلي:

```json theme={null}
{
  "success": true,
  "task_id": "3fe070eb-2ab1-4424-909c-acfe3ca761af",
  "trace_id": "2b220382-7a84-4853-ae43-05cdcad233a9",
  "data": [
    {
      "id": "5ff751dc-0e72-4de9-a54b-2cad50984b47",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-049",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-050",
      "lyric": "Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nSambuy come, Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\nSambuy come back",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-01-25T15:13:30.181Z",
      "model": "chirp-v4-5",
      "state": "succeeded",
      "style": "",
      "duration": 219.08
    },
    {
      "id": "19c515c4-d7b3-4a17-8ab0-dd1ebd4861b8",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-051",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-052",
      "lyric": "Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nSambuy come, Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\nSambuy come back",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-01-25T15:13:30.181Z",
      "model": "chirp-v4-5",
      "state": "succeeded",
      "style": "",
      "duration": 163.12
    }
  ]
}
```

بهذا تكتمل عملية إنشاء مزيج من الأغاني المرجعية، وتكون النتيجة مشابهة لما سبق.

## Samples إنشاء أغنية بالعينات

يشير `samples` هنا إلى أخذ عينة من مقطع صوتي واحد: اختيار وقت البداية والنهاية من ملف صوتي موجود، واستخدام هذا المقطع كمادة عيّنة للإبداع. وهو يختلف عن وظيفة الإبداع بالإلهام Inspo التي تستخدم من 1 إلى 4 مقاطع صوتية مرجعية كاملة كما هو موضح أدناه. يجب تعبئة المعلمات التالية:

* action: تكون القيمة `samples`.
* samples\_start: وقت بدء أخذ العينة.
* samples\_end: وقت انتهاء أخذ العينة.
* audio\_id: معرّف الأغنية المرجعية المطلوب أخذ عينة منها.

بعد تعبئة البيانات، يتم إنشاء الكود التالي تلقائيًا:

![](https://cdn.acedata.cloud/vkzumz.png)

كود Python المقابل:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "samples",
    "model": "chirp-v5",
    "lyric": "[Verse 1]\\nPhone lit up\\nHeadline in my hand\\nFeels made up\\nStill says “you won’t understand”\\nYour name\\nMy name\\nSide by side in the scroll\\nCold black text\\nOn a story I used to hold\\n\\n[Chorus]\\nYou’re breaking news\\nAnd I’m just breaking\\nFront-page truth\\nHeart still shaking\\nEverybody reads\\nWhat we already knew\\nYou’re a story now\\nAnd I’m the one you broke it to\\n\\n[Verse 2]\\nNeighbors talk\\nThrough a half-closed door\\nCoffee cools\\nOn a cracked old floor\\nYour suitcase snaps\\nLike a camera flash\\nOne last quote\\nThen you cut to black\\n\\n[Chorus]\\nYou’re breaking news\\nAnd I’m just breaking\\nFront-page truth\\nHeart still shaking\\nEverybody reads\\nWhat we already knew\\nYou’re a story now\\nAnd I’m the one you broke it to\\n\\n[Bridge]\\nIs there a line\\nWhere we rewind\\nOr just a feed\\nThat leaves us behind\\nTell me\\nWho gets\\nThe final view\\nWhen I stop trending\\nWith you\\n\\n[Chorus]\\nYou’re breaking news\\nAnd I’m just breaking\\nFront-page truth\\nHeart still shaking\\nEverybody reads\\nWhat we already knew\\nYou’re a story now\\nAnd I’m the one you broke it to (yeah)",
    "custom": True,
    "instrumental": False,
    "audio_id": "0fa07665-6b8e-4a8b-8bd3-7e0cfcdada88",
    "samples_end": 102.16,
    "samples_start": 59.88
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

انقر على التشغيل، وستجد أنه سيتم الحصول على نتيجة كما يلي:

```json theme={null}
{
  "success": true,
  "task_id": "12135a45-6384-4683-9bb1-64f19933915a",
  "trace_id": "683e559d-340e-4c72-8fae-e683442ac7e9",
  "data": [
    {
      "id": "9a0b680f-a9ea-4a36-8695-8ea777ab6ee7",
      "title": "Whistle in the Wind",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-053",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-054",
      "lyric": "[Verse 1]\nPhone lit up\nHeadline in my hand\nFeels made up\nStill says “you won’t understand”\nYour name\nMy name\nSide by side in the scroll\nCold black text\nOn a story I used to hold\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to\n[Verse 2]\nNeighbors talk\nThrough a half-closed door\nCoffee cools\nOn a cracked old floor\nYour suitcase snaps\nLike a camera flash\nOne last quote\nThen you cut to black\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to\n[Bridge]\nIs there a line\nWhere we rewind\nOr just a feed\nThat leaves us behind\nTell me\nWho gets\nThe final view\nWhen I stop trending\nWith you\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to (yeah)",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-01-31T14:34:45.043Z",
      "model": "chirp-v5",
      "state": "succeeded",
      "style": "acoustic with a hint of optimism,folk-pop,female vocals",
      "duration": 176.92
    },
    {
      "id": "66473dee-3aaf-43b2-80fd-76568b3abbb1",
      "title": "Whistle in the Wind",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-055",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-056",
      "lyric": "[Verse 1]\nPhone lit up\nHeadline in my hand\nFeels made up\nStill says “you won’t understand”\nYour name\nMy name\nSide by side in the scroll\nCold black text\nOn a story I used to hold\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to\n[Verse 2]\nNeighbors talk\nThrough a half-closed door\nCoffee cools\nOn a cracked old floor\nYour suitcase snaps\nLike a camera flash\nOne last quote\nThen you cut to black\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to\n[Bridge]\nIs there a line\nWhere we rewind\nOr just a feed\nThat leaves us behind\nTell me\nWho gets\nThe final view\nWhen I stop trending\nWith you\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to (yeah)",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-01-31T14:34:45.043Z",
      "model": "chirp-v5",
      "state": "succeeded",
      "style": "acoustic with a hint of optimism,folk-pop,female vocals",
      "duration": 177.48
    }
  ]
}
```

وبهذا تكتمل عملية إنشاء الأغنية باستخدام أخذ العيّنات، والنتيجة مماثلة لما سبق.

## ميزة الإبداع بالإلهام Inspo

يمكن لميزة الإبداع بالإلهام Inspo إنشاء موسيقى جديدة استنادًا إلى 1 إلى 4 مقاطع صوتية مرجعية كاملة، وتدعم سحب الصوت أو رفعه كمصدر للإلهام. تستخدم API إجراء `inspo` الحالي: يوفّر العميل عنوان URL صوتي متاحًا للعامة، وتُكمل الخدمة تلقائيًا إعداد الصوت المرجعي والإبداع، دون حاجة إلى أن يقرأ العميل كلمات الأغنية أو النمط أو المدة بشكل منفصل ثم يجمع الطلب. وهي تختلف عن أخذ العيّنات ضمن نطاق المذكور أعلاه، كما تختلف عن Cover الذي يحاكي نمط الأغنية الأصلية. عند الاستخدام، يجب ملء المعلمات التالية:

* action: المحتوى هو `inspo`.
* audio\_urls: قائمة بعناوين URL للصوت المرجعي، ويجب توفير 1 إلى 4 عناوين صوتية متاحة للعامة.
* model: النموذج المستخدم، ويوصى بـ `chirp-v6`.
* prompt: كلمات الأغنية أو نص تلميح إبداعي (اختياري).

> ملاحظة: يجب أن تكون الملفات الصوتية المرجعية متاحة للعامة. إذا تطابق الصوت المرجعي تمامًا مع تسجيل معروف في مكتبة أغاني المنصة، فقد يرفض Suno الإنشاء بسبب التحقق من حقوق النشر، ويوصى باستخدام صوت مملوك لك أو تم إنشاؤه بواسطة Suno كمصدر للإلهام.

كود Python المقابل:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "inspo",
    "model": "chirp-v6",
    "audio_urls": [
        "https://cdn.acedata.cloud/uploads/a0bc051f-42c2-4a46-aeb4-582dcc884ad2"
    ],
    "prompt": "Rework these references as warm acoustic folk with soft vocals"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

فيما يلي نسخة محفوظة من لقطة استجابة تاريخية تم التحقق منها؛ تستخدم اللقطة `chirp-v5` في ذلك الوقت، بينما يوصى في مثال الطلب الحالي بـ `chirp-v6`، وبنية الإرجاع متطابقة:

```json theme={null}
{
  "success": true,
  "task_id": "725e6b41-78d0-4adf-856c-05e81098c029",
  "trace_id": "8c2f0b3e-2f6a-4738-8b1d-c58068ca3dab",
  "data": [
    {
      "id": "20ca5628-86e0-4c32-8ae4-9f0c481e45f3",
      "title": "Inspo Demo",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-057",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-06-18T13:01:53.910Z",
      "model": "chirp-v5",
      "state": "succeeded",
      "style": "acoustic, folk, warm",
      "duration": 36.92
    },
    {
      "id": "8744a796-9961-45af-868d-4f3bc1c44257",
      "title": "Inspo Demo",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-058",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-06-18T13:01:53.910Z",
      "model": "chirp-v5",
      "state": "succeeded",
      "style": "acoustic, folk, warm",
      "duration": 84.16
    }
  ]
}
```

بهذا تكتمل عملية الإبداع بالإلهام، وتكون النتيجة المعادة متسقة مع إنشاء الأغاني العادي.

## الاستدعاء غير المتزامن

نظرًا لأن الوقت الذي يستغرقه Suno لإنشاء الموسيقى طويل نسبيًا، إذ يحتاج تقريبًا إلى 1-2 دقيقة، فإذا لم تستجب واجهة API لفترة طويلة، سيظل طلب HTTP محتفظًا بالاتصال، مما يؤدي إلى استهلاك إضافي لموارد النظام، لذلك توفر واجهة API هذه أيضًا دعمًا للاستدعاء غير المتزامن.

تتمثل العملية الكاملة في: عند قيام العميل بإرسال طلب، يحدد بالإضافة إلى ذلك حقل `callback_url`، وبعد أن يرسل العميل طلب API، ستعيد واجهة API نتيجة فورًا تتضمن معلومات حقل `task_id`، والذي يمثل معرّف المهمة الحالية. عند اكتمال المهمة، سيتم إرسال نتيجة إنشاء الموسيقى بصيغة POST JSON إلى `callback_url` الذي حدده العميل، وتتضمن أيضًا حقل `task_id`، وبهذه الطريقة يمكن ربط نتائج المهمة عبر المعرّف.

فيما يلي سنتعرف من خلال مثال على كيفية التنفيذ تحديدًا.

أولًا، استدعاء Webhook هو خدمة يمكنها استقبال طلبات HTTP، وينبغي للمطور استبداله بعنوان URL لخادم HTTP الذي أنشأه بنفسه. هنا ولأغراض العرض المريح، نستخدم موقع مثال Webhook عام [https://webhook.site/،](https://webhook.site/،) ويمكنك الحصول على عنوان URL لـ Webhook بمجرد فتح هذا الموقع، كما هو موضح في الصورة:

![](https://cdn.acedata.cloud/fwfqin.png)

انسخ عنوان URL هذا، ويمكن استخدامه كـ Webhook، والمثال هنا هو [https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2](https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2).

بعد ذلك، يمكننا تعيين الحقل `callback_url` إلى عنوان URL الخاص بـ Webhook المذكور أعلاه، مع إدخال `prompt` في الوقت نفسه، كما هو موضح في الصورة:

![](https://cdn.acedata.cloud/x8xql1.png)

انقر على تشغيل، وستجد أنه يتم الحصول على نتيجة فورًا، كما يلي:

```
{
  "task_id": "44472ab8-783b-4054-b861-5bf14e462f60"
}
```

بعد الانتظار قليلًا، يمكننا ملاحظة نتيجة إنشاء الأغنية على [https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2،](https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2،) كما هو موضح في الصورة:

![](https://cdn.acedata.cloud/f9kosb.png)

المحتوى كما يلي:

```json theme={null}
{
  "success": true,
  "task_id": "44472ab8-783b-4054-b861-5bf14e462f60",
  "data": [
    {
      "id": "da4324e5-84b2-484b-b0e9-dd261381c594",
      "title": "Winter Whispers",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-059",
      "lyric": "[Verse]\nSnow falling gently from the sky\nChildren giggling as they pass by\nFire crackling\nCozy and warm\nChristmas spirit begins to swarm\n[Verse 2]\nTwinkling lights\nA sight to behold\nStockings hung\nWaiting to be filled with gold\nGifts wrapped with love\nPiled high\nExcitement in the air\nYou can't deny\n[Chorus]\nWinter whispers in the wind\nJoy and love it brings\nLet's celebrate this season\nWith the ones we're missing",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-003",
      "created_at": "2024-05-11T07:33:05.430Z",
      "model": "chirp-v3",
      "prompt": "A song for Christmas",
      "style": "pop"
    },
    {
      "id": "b878a87b-a0db-4046-8ccd-ecd2fb3d4372",
      "title": "Winter Whispers",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-060",
      "lyric": "[Verse]\nSnow falling gently from the sky\nChildren giggling as they pass by\nFire crackling\nCozy and warm\nChristmas spirit begins to swarm\n[Verse 2]\nTwinkling lights\nA sight to behold\nStockings hung\nWaiting to be filled with gold\nGifts wrapped with love\nPiled high\nExcitement in the air\nYou can't deny\n[Chorus]\nWinter whispers in the wind\nJoy and love it brings\nLet's celebrate this season\nWith the ones we're missing",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-004",
      "created_at": "2024-05-11T07:33:05.430Z",
      "model": "chirp-v3",
      "prompt": "A song for Christmas",
      "style": "pop"
    }
  ]
}
```

يمكن ملاحظة وجود حقل `task_id` في النتيجة، أما الحقول الأخرى فهي مشابهة لما ورد أعلاه، ويمكن تحقيق ربط المهام عبر هذا الحقل.

بالطبع، يمكننا أيضًا الحصول على النتيجة من خلال الاستدعاء المتدفق، وكل ما نحتاجه هو تعيين قيمة `accept` في رأس الطلب إلى `application/x-ndjson`، وفيما يلي نستخدم إدخالًا نموذجيًا كمثال:

![](https://cdn.acedata.cloud/vgffvk.png)

أثناء الانتظار، يمكننا الحصول على المخرجات التالية:

```json theme={null}
{"success":true,"task_id":"1af4b454-ce84-4512-a0a2-de3f8574ecd8","data":[{"id":"1f610752-f426-4fd5-89a8-ba2ad0370881","title":"Snowflakes and Mistletoe","lyric":"[Verse]\nLights are tangled on the tree again\nThe cat’s knocked over the wreath\nCookies burning in the oven too\nBut I’m still grinning through my teeth\n[Prechorus]\nSnow is falling like glitter in the sky\nI’ve got a feeling this year’s gonna fly\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe\n[Verse 2]\nGrandma’s singing a little off-key\nThe kids are laughing too loud\nThe dog’s stolen a turkey leg\nChaos is a Christmas crowd\n[Prechorus]\nBut the fire’s crackling\nWarm and bright\nAnd my heart’s a candle tonight\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe","audio_url":"","video_url":"","created_at":"2025-12-13T11:29:25.101Z","model":"chirp-v5","state":"pending","prompt":"A song for Christmas","style":"uplifting, orchestral with bells and acoustic guitar"},{"id":"d1a3109d-799b-401e-b032-4b501bcf26f3","title":"Snowflakes and Mistletoe","lyric":"[Verse]\nLights are tangled on the tree again\nThe cat’s knocked over the wreath\nCookies burning in the oven too\nBut I’m still grinning through my teeth\n[Prechorus]\nSnow is falling like glitter in the sky\nI’ve got a feeling this year’s gonna fly\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe\n[Verse 2]\nGrandma’s singing a little off-key\nThe kids are laughing too loud\nThe dog’s stolen a turkey leg\nChaos is a Christmas crowd\n[Prechorus]\nBut the fire’s crackling\nWarm and bright\nAnd my heart’s a candle tonight\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe","audio_url":"","video_url":"","created_at":"2025-12-13T11:29:25.101Z","model":"chirp-v5","state":"pending","prompt":"A song for Christmas","style":"uplifting, orchestral with bells and acoustic guitar"}]}
{"success":true,"task_id":"1af4b454-ce84-4512-a0a2-de3f8574ecd8","trace_id":"4440342a-41c4-4140-8bb1-3537a598ca2e","data":[{"id":"1f610752-f426-4fd5-89a8-ba2ad0370881","title":"Snowflakes and Mistletoe","image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-073","image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-074","lyric":"[Verse]\nLights are tangled on the tree again\nThe cat’s knocked over the wreath\nCookies burning in the oven too\nBut I’m still grinning through my teeth\n[Prechorus]\nSnow is falling like glitter in the sky\nI’ve got a feeling this year’s gonna fly\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe\n[Verse 2]\nGrandma’s singing a little off-key\nThe kids are laughing too loud\nThe dog’s stolen a turkey leg\nChaos is a Christmas crowd\n[Prechorus]\nBut the fire’s crackling\nWarm and bright\nAnd my heart’s a candle tonight\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe","audio_url":"https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3","video_url":"","created_at":"2025-12-13T11:29:25.101Z","model":"chirp-v5","state":"succeeded","prompt":"A song for Christmas","style":"uplifting, orchestral with bells and acoustic guitar","duration":129.92},{"id":"d1a3109d-799b-401e-b032-4b501bcf26f3","title":"Snowflakes and Mistletoe","image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-075","image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-076","lyric":"[Verse]\nLights are tangled on the tree again\nThe cat’s knocked over the wreath\nCookies burning in the oven too\nBut I’m still grinning through my teeth\n[Prechorus]\nSnow is falling like glitter in the sky\nI’ve got a feeling this year’s gonna fly\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe\n[Verse 2]\nGrandma’s singing a little off-key\nThe kids are laughing too loud\nThe dog’s stolen a turkey leg\nChaos is a Christmas crowd\n[Prechorus]\nBut the fire’s crackling\nWarm and bright\nAnd my heart’s a candle tonight\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe","audio_url":"https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3","video_url":"","created_at":"2025-12-13T11:29:25.101Z","model":"chirp-v5","state":"succeeded","prompt":"A song for Christmas","style":"uplifting, orchestral with bells and acoustic guitar","duration":127.16}]}
```

ستدفع الاستجابة المتدفقة، بالتتابع لنفس `task_id`، حالة المعالجة والنتيجة النهائية؛ وقد احتُفظ أعلاه فقط بالاستجابتين الحقيقيتين الأولية والنهائية، مع حذف التحديثات المتوسطة المتكررة.

## معالجة الأخطاء

إذا حدث خطأ، فستحصل على معلومات خطأ مشابهة لما يلي:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "forbidden",
    "message": "Song Description contained artist name: eminem"
  },
  "trace_id": "9bb7c2f4-3b7b-4965-b50a-f663874b1b6f",
  "task_id": "9bb3a2a6-c438-436d-a9f3-fa466abc077c"
}
```

فيما يلي قائمة بـ HTTP Status Code و`error.code` و`error.message`:

> ملاحظة: قد تختلف الحصص ورسائل الخطأ بين حسابات المنبع المختلفة. عادةً ما تكون قيود `style` في `chirp-v3-5`/`chirp-v4` أقل (200)، بينما يدعم `chirp-v4-5` والإصدارات الأحدث عادةً حتى 1000؛ وعند استخدام منبع قديم، قد تظهر رسائل توافق مثل `Tags too long.` أو `style must be less than or equal 120`.
> \| رمز الحالة | `error.code`  | `error.message`                                                 |
> \| ----------- | ------------- | --------------------------------------------------------------- |
> \| 400         | `bad_request` | `معرّف الأغنية غير موجود أو تم إيقافها.`                        |
> \| 400         | `bad_request` | `المطالبة طويلة جدًا.`                                          |
> \| 400         | `bad_request` | `الوسوم طويلة جدًا.`                                            |
> \| 400         | `bad_request` | `الصوت المرفوع يطابق عملاً فنياً موجوداً.`                      |
> \| 400         | `bad_request` | `يجب أن تكون instrumental قيمة منطقية`                          |
> \| 400         | `bad_request` | `العنوان طويل جدًا.`                                            |
> \| 400         | `bad_request` | `الموضوع طويل جدًا.`                                            |
> \| 400         | `bad_request` | `يجب أن يكون style أقل من أو يساوي 120`                         |
> \| 400         | `bad_request` | `يجب أن تكون custom قيمة منطقية`                                |
> \| 400         | `bad_request` | `audio_id مطلوب عند تمديد الصوت`                                |
> \| 400         | `bad_request` | `continue_at مطلوب عند تمديد الصوت`                             |
> \| 400         | `bad_request` | `يجب أن يكون continue_at رقماً أكبر من 0`                       |
> \| 400         | `bad_request` | `lyric مطلوب عند تمديد الصوت وعندما تكون instrumental خاطئة`    |
> \| 400         | `bad_request` | `prompt مطلوب عند إنشاء الصوت`                                  |
> \| 400         | `bad_request` | `lyric مطلوب عند إنشاء صوت مخصص`                                |
> \| 403         | `forbidden`   | `يبدو أن المطالبة مشوهة`                                        |
> \| 403         | `forbidden`   | `يبدو أن المطالبة محمية بحقوق الطبع والنشر`                     |
> \| 403         | `forbidden`   | `احتوت المطالبة على مادة غير لائقة`                             |
> \| 403         | `forbidden`   | `تم وضع علامة على وصف الأغنية للمراجعة`                         |
> \| 403         | `forbidden`   | `احتوى وصف الأغنية على اسم فنان`                                |
> \| 403         | `forbidden`   | `احتوت الوسوم على اسم فنان`                                    |
> \| 403         | `forbidden`   | `احتوت كلمات الأغنية على مادة محمية بحقوق الطبع والنشر`         |
> \| 403         | `forbidden`   | `احتوى وصف الأغنية على وسم منتج`                                |
> \| 403         | `forbidden`   | `خطأ عام من openAI`                                             |
> \| 403         | `forbidden`   | `تم وضع علامة على المطالبة للمراجعة`                            |
> \| 500         | `api_error`   | `تعذر إنشاء كلمات الأغنية من وصف الأغنية`                       |
> \| 500         | `api_error`   | `فشلت المهمة بسبب خطأ غير معروف`                               |
> \| 500         | `api_error`   | `لا يوجد عامل متاح في النظام`                                  |
> \| 500         | `api_error`   | `الخدمة قيد الصيانة، تم إيقاف الإنشاء مؤقتًا`                   |
> \| 504         | `timeout`     | `انتهت المهلة أثناء انتظار إنشاء الصوت`                         |


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