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

​
عملية التقديم

لاستخدام واجهة برمجة التطبيقات، يجب أولاً زيارة صفحة واجهة برمجة تطبيقات توليد الصوتيات للمنتج للتقدم للحصول على الخدمة المناسبة، بعد دخول الصفحة، انقر على زر “Acquire”، كما هو موضح في الصورة: إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، بعد تسجيل الدخول أو التسجيل، سيتم إرجاعك تلقائيًا إلى الصفحة الحالية. عند التقديم لأول مرة، سيكون هناك حد مجاني متاح، يمكنك استخدام واجهة برمجة التطبيقات مجانًا.

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

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

يمكنك أن ترى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:
  • accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
  • authorization: مفتاح الوصول إلى واجهة برمجة التطبيقات، يمكنك اختياره مباشرة بعد التقديم.
بالإضافة إلى ذلك، تشمل معلمات جسم الطلب:
  • action: سلوك مهمة توليد الموسيقى هذه، لتوليد الأغاني هو generate.
  • model: النموذج المستخدم لإنشاء الأغاني، حاليًا هناك: FUZZ-2.0 Pro، FUZZ-2.0، FUZZ-2.0 Raw، FUZZ-1.1 Pro، FUZZ-1.0 Pro، FUZZ-1.0، FUZZ-1.1، FUZZ-0.8.
  • lyric: محتوى كلمات الأغنية.
  • custom: ما إذا كان سيتم استخدام طريقة مخصصة لتوليد الأغنية.
  • prompt: الكلمات الدلالية في وضع الإلهام.
  • title: معلومات عنوان الأغنية.
  • audio_id: معرف الأغنية المرجعية، لاستخدامه في الاستمرار أو النسخ.
  • continue_at: بدء كتابة الأغنية من عدد ثوانٍ محدد.
  • replace_section_start/replace_section_end: توقيت بداية ونهاية الجزء المراد استبداله، بوحدة الثواني.
  • lyrics_strength: قوة الكلمات، تشير إلى مدى تأثير الكلمات في توليد الصوت، يمكن أن تكون بين 0-1، الافتراضي هو 0.7.
  • sound_strength: قوة الكلمات الدلالية للصوت، يمكن أن تكون بين 0.2-1، الافتراضي هو 0.7.
  • cover_strength: قوة التغطية بين 0.2-1، الافتراضي هو 1.
  • weirdness: درجة غرابة النمط، يمكن أن تكون بين 0-1، الافتراضي هو 0.5.
  • callback_url: URL الذي يحتاج إلى استدعاء النتائج.
  • instrumental: ما إذا كانت الأغنية بدون كلمات.
بعد الاختيار، يمكنك أن ترى أن الكود المقابل تم توليده على الجانب الأيمن، كما هو موضح في الصورة:

انقر على زر “Try” لإجراء الاختبار، كما هو موضح في الصورة أعلاه، هنا حصلنا على النتيجة التالية: 
{
  "success": true,
  "task_id": "82fd443a-903a-4f18-8028-12d2f8a0a4be",
  "trace_id": "d85839fa-0bb1-42da-a9fc-cd582c29027d",
  "data": [
    {
      "id": "6c947f13-a3c5-4b9c-8609-5639c37cdc2d",
      "title": "Untitled",
      "image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/a853673e-615c-42ae-bdff-16b1add94861/image/6c947f13-a3c5-4b9c-8609-5639c37cdc2d.jpg",
      "lyric": "[Instrumental]",
      "audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/a853673e-615c-42ae-bdff-16b1add94861/audio/6c947f13-a3c5-4b9c-8609-5639c37cdc2d.m4a",
      "video_url": null,
      "image_id": "6c947f13-a3c5-4b9c-8609-5639c37cdc2d",
      "topic": null,
      "seed": "2450882164",
      "sound": "A song for Christmas",
      "created_at": "2025-12-30T17:18:23.232911Z",
      "model": "FUZZ-2.0 Pro",
      "progress": "100%",
      "state": "succeeded",
      "duration": "181.3014058956916"
    }
  ]
}
تتضمن النتيجة العائدة عدة حقول، كما يلي:
  • success: حالة مهمة توليد الموسيقى في ذلك الوقت.
    • data: نتيجة مهمة الموسيقى هذه
      • id: معرف مهمة توليد الموسيقى في ذلك الوقت.
      • sound: الكلمات الدلالية لمهمة توليد الموسيقى في ذلك الوقت.
      • seed: قيمة البذور لمهمة توليد الموسيقى في ذلك الوقت.
      • audio_url: رابط الصوت لمهمة توليد الموسيقى في ذلك الوقت.
      • image_url: رابط الغلاف لمهمة توليد الموسيقى في ذلك الوقت.
      • image_id: معرف الغلاف لمهمة توليد الموسيقى في ذلك الوقت.
      • state: حالة مهمة توليد الموسيقى في ذلك الوقت.
      • duration: معلومات مدة الموسيقى في ذلك الوقت.
      • progress: قيمة تقدم مهمة الموسيقى في ذلك الوقت.
      • model: معلومات النموذج المستخدم في مهمة توليد الموسيقى في ذلك الوقت.
      • lyric: معلومات كلمات الأغاني لمهمة توليد الموسيقى في ذلك الوقت.
يمكنك أن ترى أننا حصلنا على معلومات الموسيقى التي نرغب في توليدها، كل ما علينا هو الحصول على رابط الموسيقى من data للحصول على موسيقى المنتج المولدة. بالإضافة إلى ذلك، إذا كنت ترغب في توليد كود الدمج المقابل، يمكنك نسخه مباشرة، على سبيل المثال، كود CURL كما يلي: 
curl -X POST 'https://api.acedata.cloud/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "FUZZ-2.0 Pro",
  "prompt": "A song for Christmas"
}'

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

إذا كنت ترغب في توليد كلمات مخصصة، يمكنك إدخال الكلمات: في هذه الحالة، يمكن تمرير محتوى مشابه في حقل lyric: 
[Verse]Woke up with the sun in my eyesNo clouds above just blue in the skiesShoes on my feet I’m ready to runEvery step feels like a loaded gun[Chorus]Happy days are rolling inLet the joy beneath my skinNo more shadows no more liesJust the truth that lifts me high[Verse 2]Dancing through the city streetsA rhythm pounding in my heartbeatStrangers smile it’s catching onThis world’s a stage we’re all a song[Chorus]Happy days are rolling inLet the joy beneath my skinNo more shadows no more liesJust the truth that lifts me high[Bridge]Throw your worries out the doorLet them sink to the ocean floorWe’re alive and it’s enoughLife is messy but it’s love[Chorus]Happy days are rolling inLet the joy beneath my skinNo more shadows no more liesJust the truth that lifts me high
بعد ذلك، نحتاج إلى تخصيص الأغنية بناءً على الكلمات والعنوان والأسلوب، يمكننا تحديد المحتويات التالية:
  • lyric: نص الكلمات
  • custom: املأها بـ true، مما يعني التوليد المخصص، هذه المعلمة افتراضيًا تكون false، مما يعني استخدام prompt للتوليد.
  • title: عنوان الأغنية. 填写样例如下：

填写完毕之后自动生成了代码如下：

对应的代码： 
curl -X POST 'https://api.acedata.cloud/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "FUZZ-2.0 Pro",
  "instrumental": false,
  "lyric": "[Verse]\nاستيقظت مع الشمس في عيني\nلا سحب فوقي فقط زرقة في السماء\nالأحذية على قدمي أنا مستعد للجري\nكل خطوة تشعر وكأنها مسدس محشو\n[Chorus]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[Verse 2]\nأرقص في شوارع المدينة\nإيقاع يدق في نبض قلبي\nالغرباء يبتسمون إنه معدي\nهذا العالم مسرح ونحن جميعاً أغنية\n[Chorus]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[Bridge]\nألقِ همومك خارج الباب\nدعها تغرق في قاع المحيط\nنحن أحياء وهذا يكفي\nالحياة فوضوية لكنها حب\n[Chorus]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً",
  "custom": true
}'
اختبار مسموح، التأثير الناتج مشابه. 
{
  "success": true,
  "task_id": "9f58bbd4-855a-4233-ac45-b63bf9168e02",
  "trace_id": "145ad117-6ce7-42dd-af12-70751c5284fc",
  "data": [
    {
      "id": "38d3b9e2-0dfb-4338-b2a7-15e45656ed32",
      "title": "استيقظت مع الشمس في عيني",
      "image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/image/38d3b9e2-0dfb-4338-b2a7-15e45656ed32.jpg",
      "lyric": "[Verse]\nاستيقظت مع الشمس في عيني\nلا سحب فوقي فقط زرقة في السماء\nالأحذية على قدمي أنا مستعد للجري\nكل خطوة تشعر وكأنها مسدس محشو\n[Chorus]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[Verse 2]\nأرقص في شوارع المدينة\nإيقاع يدق في نبض قلبي\nالغرباء يبتسمون إنه معدي\nهذا العالم مسرح ونحن جميعاً أغنية\n[Chorus]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[Bridge]\nألقِ همومك خارج الباب\nدعها تغرق في قاع المحيط\nنحن أحياء وهذا يكفي\nالحياة فوضوية لكنها حب\n[Chorus]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً",
      "audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/audio/38d3b9e2-0dfb-4338-b2a7-15e45656ed32.m4a",
      "video_url": null,
      "image_id": "38d3b9e2-0dfb-4338-b2a7-15e45656ed32",
      "topic": null,
      "seed": "3789209121",
      "sound": "",
      "created_at": "2025-12-30T17:26:46.357055Z",
      "model": "FUZZ-2.0 Pro",
      "progress": "100%",
      "state": "succeeded",
      "duration": "153.80897959183673"
    }
  ]
}

​
ترجمة الأغاني

إذا كنت ترغب في إجراء عملية ترجمة على الأغاني التي تم إنشاؤها بالفعل، يمكنك إدخال الأغاني التي تم إنشاؤها أعلاه للترجمة، بعد ذلك سنقوم بتخصيص الأغاني بناءً على الكلمات، العنوان. إذا كنت ترغب في الاستمرار في ترجمة الأغاني التي قمت بتحميلها، يمكنك تعيين المعامل action إلى upload_cover، وإدخال ID الأغنية التي تحتاج إلى الاستمرار في ترجمتها، يمكن الحصول على ID الأغنية باستخدام Producer Upload API كما هو موضح في الصورة أدناه:

يمكنك تحديد المحتوى كما يلي:
  • action: سلوك مهمة الأغنية هذه، حالياً تدعم: generate، cover، extend، upload_cover، upload_extend، replace_section، swap_vocals، swap_instrumentals، variation، هذه الترجمة تستخدم معامل cover.
  • lyric: نص الكلمات
  • title: عنوان الأغنية.
  • custom: هل يتم استخدام وضع مخصص للتوليد، الافتراضي هو false.
  • audio_id: ID الأغنية التي تحتاج إلى ترجمتها.
填写样例如下：

填写完毕之后自动生成了代码如下：

对应的代码： 
curl -X POST 'https://api.acedata.cloud/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "cover",
  "model": "FUZZ-2.0 Pro",
  "lyric": "[Verse]\nاستيقظت مع الشمس في عيني\nلا سحب فوقي فقط زرقة في السماء\nالأحذية على قدمي أنا مستعد للجري\nكل خطوة تشعر وكأنها مسدس محشو\n[Chorus]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[Verse 2]\nأرقص في شوارع المدينة\nإيقاع يدق في نبض قلبي\nالغرباء يبتسمون إنه معدي\nهذا العالم مسرح ونحن جميعاً أغنية\n[Chorus]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[Bridge]\nألقِ همومك خارج الباب\nدعها تغرق في قاع المحيط\nنحن أحياء وهذا يكفي\nالحياة فوضوية لكنها حب\n[Chorus]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً",
  "audio_id": "38d3b9e2-0dfb-4338-b2a7-15e45656ed32",
  "instrumental": false,
  "custom": true,
  "title": "Cover"
}'
اختبار مسموح، التأثير الناتج مشابه. 
{
  "success": true,
  "task_id": "dbca350e-6fb9-46ca-9c7e-4c1a9080806f",
  "trace_id": "a39e0fff-ced8-4b31-ae23-aef3badd90fa",
  "data": [
    {
      "id": "e52dd729-38b4-4c2f-9031-59eb7953c593",
      "title": "غلاف",
      "image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/image/e52dd729-38b4-4c2f-9031-59eb7953c593.jpg",
      "lyric": "[المقطع]\nاستيقظت مع الشمس في عيني\nلا سحب فوقي فقط زرقاء في السماء\nالأحذية على قدمي أنا مستعد للجري\nكل خطوة تشعر وكأنها مسدس محشو\n[الكورس]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[المقطع 2]\nأرقص في شوارع المدينة\nإيقاع يدق في نبض قلبي\nالغرباء يبتسمون إنه ينتشر\nهذا العالم مسرح ونحن جميعاً أغنية\n[الكورس]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[الجسر]\nألقِ همومك خارج الباب\nدعها تغرق في قاع المحيط\nنحن أحياء وهذا يكفي\nالحياة فوضوية لكنها حب\n[الكورس]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً",
      "audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/audio/e52dd729-38b4-4c2f-9031-59eb7953c593.m4a",
      "video_url": null,
      "image_id": "e52dd729-38b4-4c2f-9031-59eb7953c593",
      "topic": null,
      "seed": "358803418",
      "sound": "",
      "created_at": "2025-12-30T17:32:32.951948Z",
      "model": "FUZZ-2.0 Pro",
      "progress": "100%",
      "state": "succeeded",
      "duration": "153.0659410430839"
    }
  ]
}

​
متابعة كتابة الأغاني

إذا كنت ترغب في متابعة كتابة الأغاني، نحتاج إلى تمرير قيمة action كالتالي: extend، بعد ذلك يجب علينا تخصيص إنشاء الأغنية بناءً على الكلمات، العنوان، والأسلوب. إذا كنت ترغب في متابعة كتابة الأغاني التي قمت بتحميلها، يمكنك تعيين المعامل action إلى upload_extend، وإدخال معرف الأغنية التي تحتاج إلى متابعة كتابتها، يمكن الحصول على معرف الأغنية باستخدام Producer Upload API كما هو موضح في الصورة أدناه:

نموذج الإدخال كما يلي:

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

الكود المقابل: 
curl -X POST 'https://api.acedata.cloud/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "extend",
  "model": "FUZZ-2.0 Pro",
  "instrumental": false,
  "lyric": "[المقطع]\nاستيقظت مع الشمس في عيني\nلا سحب فوقي فقط زرقاء في السماء\nالأحذية على قدمي أنا مستعد للجري\nكل خطوة تشعر وكأنها مسدس محشو\n[الكورس]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[المقطع 2]\nأرقص في شوارع المدينة\nإيقاع يدق في نبض قلبي\nالغرباء يبتسمون إنه ينتشر\nهذا العالم مسرح ونحن جميعاً أغنية\n[الكورس]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[الجسر]\nألقِ همومك خارج الباب\nدعها تغرق في قاع المحيط\nنحن أحياء وهذا يكفي\nالحياة فوضوية لكنها حب\n[الكورس]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً",
  "continue_at": 3,
  "audio_id": "38d3b9e2-0dfb-4338-b2a7-15e45656ed32",
  "custom": true,
  "title": "امتداد",
  "weirdness": 0.3,
  "sound_strength": 0.3,
  "lyrics_strength": 0.6
}'
اختبار مسموح، التأثير الناتج مشابه. 
{
  "success": true,
  "task_id": "834983cb-d62d-4750-b1aa-461da137e51f",
  "trace_id": "6923eee2-7403-432c-8bd1-e471086385b0",
  "data": [
    {
      "id": "d9ebc609-fb65-4a23-b914-c074747af6a4",
      "title": "امتداد",
      "image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/image/d9ebc609-fb65-4a23-b914-c074747af6a4.jpg",
      "lyric": "[المقطع]\n[المقطع]\nاستيقظت مع الشمس في عيني\nلا سحب فوقي فقط زرقاء في السماء\nالأحذية على قدمي أنا مستعد للجري\nكل خطوة تشعر وكأنها مسدس محشو\n[الكورس]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[المقطع 2]\nأرقص في شوارع المدينة\nإيقاع يدق في نبض قلبي\nالغرباء يبتسمون إنه ينتشر\nهذا العالم مسرح ونحن جميعاً أغنية\n[الكورس]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[الجسر]\nألقِ همومك خارج الباب\nدعها تغرق في قاع المحيط\nنحن أحياء وهذا يكفي\nالحياة فوضوية لكنها حب\n[الكورس]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً",
      "audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/audio/d9ebc609-fb65-4a23-b914-c074747af6a4.m4a",
      "video_url": null,
      "image_id": "d9ebc609-fb65-4a23-b914-c074747af6a4",
      "topic": null,
      "seed": "4294469624",
      "sound": "",
      "created_at": "2025-12-30T17:36:14.520928Z",
      "model": "FUZZ-2.0 Pro",
      "progress": "100%",
      "state": "succeeded",
      "duration": "173.87102040816328"
    }
  ]
}

​
تحويل الموسيقى

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

填写完毕之后自动生成了代码如下：

对应的代码： 
curl -X POST 'https://api.acedata.cloud/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "variation",
  "audio_id": "d9ebc609-fb65-4a23-b914-c074747af6a4",
  "model": "FUZZ-2.0 Pro",
  "instrumental": false,
  "lyric": "[Verse]\nاستيقظت مع الشمس في عيني\nلا سحب فوقي فقط زرقة في السماء\nالأحذية على قدمي أنا مستعد للجري\nكل خطوة تشعر وكأنها مسدس محشو\n[Chorus]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[Verse 2]\nأرقص في شوارع المدينة\nإيقاع يدق في نبض قلبي\nالغرباء يبتسمون إنه معدٍ\nهذا العالم مسرح ونحن جميعاً أغنية\n[Chorus]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[Bridge]\nألقِ همومك خارج الباب\nدعها تغوص في قاع المحيط\nنحن أحياء وهذا يكفي\nالحياة فوضوية لكنها حب\n[Chorus]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً",
  "custom": true
}'
测试允许،生成的效果是类似的。 
{
    "success": true,
    "task_id": "3a74da6d-a37d-4b5d-b116-821f455bce39",
    "trace_id": "8e28cce0-0400-4bfd-83db-6d27f97422c7",
    "data": [
        {
            "id": "c14ca458-cd5a-4700-83d4-5249e15f2707",
            "title": "استيقظت مع الشمس في عيني",
            "image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/image/c14ca458-cd5a-4700-83d4-5249e15f2707.jpg",
            "lyric": "[Verse]\nاستيقظت مع الشمس في عيني\nلا سحب فوقي فقط زرقة في السماء\nالأحذية على قدمي أنا مستعد للجري\nكل خطوة تشعر وكأنها مسدس محشو\n[Chorus]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[Verse 2]\nأرقص في شوارع المدينة\nإيقاع يدق في نبض قلبي\nالغرباء يبتسمون إنه معدٍ\nهذا العالم مسرح ونحن جميعاً أغنية\n[Chorus]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[Bridge]\nألقِ همومك خارج الباب\nدعها تغوص في قاع المحيط\nنحن أحياء وهذا يكفي\nالحياة فوضوية لكنها حب\n[Chorus]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً",
            "audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/audio/c14ca458-cd5a-4700-83d4-5249e15f2707.m4a",
            "video_url": null,
            "image_id": "c14ca458-cd5a-4700-83d4-5249e15f2707",
            "topic": null,
            "seed": "2082104582",
            "sound": "",
            "created_at": "2025-12-30T17:48:40.135187Z",
            "model": "FUZZ-2.0",
            "progress": "100%",
            "state": "succeeded",
            "duration": "173.12798185941043"
        }
    ]
}

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

إذا كنت ترغب في استبدال مقطع من الأغنية، نحتاج إلى تمرير قيمة معلمة action كالتالي: replace_section، بعد ذلك يجب علينا تخصيص الأغنية بناءً على الكلمات، العنوان. إذا كنت ترغب في الاستمرار في استبدال مقطع من الأغاني التي قمت بتحميلها، يمكنك تعيين معلمة action إلى upload_replace_section، وإدخال ID الأغنية التي تحتاج إلى الاستمرار في كتابتها، يمكن الحصول على ID الأغنية باستخدام Producer Upload API كما هو موضح في الصورة أدناه:

نموذج التعبئة كما يلي:

填写完毕之后自动生成了代码如下：

对应的代码： 
curl -X POST 'https://api.acedata.cloud/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "replace_section",
  "model": "FUZZ-2.0 Pro",
  "instrumental": false,
  "lyric": "[Verse]\\nاستيقظت مع الشمس في عيني\\nلا سحب فوقي فقط زرقة في السماء\\nالأحذية على قدمي أنا مستعد للجري\\nكل خطوة تشعر وكأنها مسدس محشو\\n[Chorus]\\nأيام سعيدة تتدحرج\\nدع الفرح تحت جلدي\\nلا مزيد من الظلال لا مزيد من الأكاذيب\\nفقط الحقيقة التي ترفعني عالياً\\n[Verse 2]\\nأرقص في شوارع المدينة\\nإيقاع يدق في نبض قلبي\\nالغرباء يبتسمون إنه معدٍ\\nهذا العالم مسرح ونحن جميعاً أغنية\\n[Chorus]\\nأيام سعيدة تتدحرج\\nدع الفرح تحت جلدي\\nلا مزيد من الظلال لا مزيد من الأكاذيب\\nفقط الحقيقة التي ترفعني عالياً\\n[Bridge]\\nألقِ همومك خارج الباب\\nدعها تغوص في قاع المحيط\\nنحن أحياء وهذا يكفي\\nالحياة فوضوية لكنها حب\\n[Chorus]\\nأيام سعيدة تتدحرج\\nدع الفرح تحت جلدي\\nلا مزيد من الظلال لا مزيد من الأكاذيب\\nفقط الحقيقة التي ترفعني عالياً",
  "audio_id": "d9ebc609-fb65-4a23-b914-c074747af6a4",
  "replace_section_start": 3,
  "replace_section_end": 70,
  "custom": true
}'
测试允许，生成的效果是类似的。 
{
    "success": true,
    "task_id": "3cb5ae96-01b0-4a37-afb0-e582608af56f",
    "trace_id": "3ebc6f63-5093-4499-bf9b-95c239e0da4f",
    "data": [
        {
            "id": "a54609c6-13e2-4176-be0f-4d7eebc68e1f",
            "title": "استيقظت مع الشمس في عيني",
            "image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/image/a54609c6-13e2-4176-be0f-4d7eebc68e1f.jpg",
            "lyric": "[المقطع]\\nاستيقظت مع الشمس في عيني\\nلا سحب فوقي فقط زرقة في السماء\\nالأحذية على قدمي أنا مستعد للجري\\nكل خطوة تشعر وكأنها مسدس محشو\\n[الكورس]\\nأيام سعيدة تتدحرج\\nدع الفرح تحت جلدي\\nلا مزيد من الظلال لا مزيد من الأكاذيب\\nفقط الحقيقة التي ترفعني عالياً\\n[المقطع 2]\\nأرقص في شوارع المدينة\\nإيقاع يدق في نبض قلبي\\nالغرباء يبتسمون إنه ينتشر\\nهذا العالم مسرح ونحن جميعاً أغنية\\n[الكورس]\\nأيام سعيدة تتدحرج\\nدع الفرح تحت جلدي\\nلا مزيد من الظلال لا مزيد من الأكاذيب\\nفقط الحقيقة التي ترفعني عالياً\\n[الجسر]\\nألقِ همومك خارج الباب\\nدعها تغوص في قاع المحيط\\nنحن أحياء وهذا يكفي\\nالحياة فوضوية لكنها حب\\n[الكورس]\\nأيام سعيدة تتدحرج\\nدع الفرح تحت جلدي\\nلا مزيد من الظلال لا مزيد من الأكاذيب\\nفقط الحقيقة التي ترفعني عالياً",
            "audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/audio/a54609c6-13e2-4176-be0f-4d7eebc68e1f.m4a",
            "video_url": null,
            "image_id": "a54609c6-13e2-4176-be0f-4d7eebc68e1f",
            "topic": null,
            "seed": "14887454",
            "sound": "",
            "created_at": "2025-12-30T18:01:19.907443Z",
            "model": "FUZZ-2.0 Pro",
            "progress": "100%",
            "state": "succeeded",
            "duration": "174.6140589569161"
        }
    ]
}

​
نسخة مرافقة

إذا كنت ترغب في استخدام النسخة الرسمية من المرافقة، يمكنك تعيين قيمة معلمة action إلى: swap_instrumentals، بعد ذلك سنقوم بتخصيص إنشاء الأغنية بناءً على الكلمات، العنوان. نموذج التعبئة كما يلي:

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

الكود المقابل: 
curl -X POST 'https://api.acedata.cloud/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "swap_instrumentals",
  "model": "FUZZ-2.0 Pro",
  "weirdness": 0.6,
  "prompt": "سعيد",
  "audio_id": "d9ebc609-fb65-4a23-b914-c074747af6a4"
}'
اختبار مسموح، التأثير الناتج مشابه. 
{
  "success": true,
  "task_id": "d17d8376-3a58-451d-a976-404719bac11d",
  "trace_id": "ab596807-910a-4e30-bae2-4647895f7d0b",
  "data": [
    {
      "id": "22d7d75c-9e0a-47a8-b22b-eea55eaa0c4b",
      "title": "تمديد (تبديل الصوت)",
      "image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/image/22d7d75c-9e0a-47a8-b22b-eea55eaa0c4b.jpg",
      "lyric": "[المقطع]\nاستيقظت مع الشمس في عيني\nلا سحب فوقي فقط زرقة في السماء\nالأحذية على قدمي أنا مستعد للجري\nكل خطوة تشعر وكأنها مسدس محشو\n[الكورس]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[المقطع 2]\nأرقص في شوارع المدينة\nإيقاع يدق في نبض قلبي\nالغرباء يبتسمون إنه ينتشر\nهذا العالم مسرح ونحن جميعاً أغنية\n[الكورس]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[الجسر]\nألقِ همومك خارج الباب\nدعها تغوص في قاع المحيط\nنحن أحياء وهذا يكفي\nالحياة فوضوية لكنها حب\n[الكورس]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً",
      "audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/audio/22d7d75c-9e0a-47a8-b22b-eea55eaa0c4b.m4a",
      "video_url": null,
      "image_id": "22d7d75c-9e0a-47a8-b22b-eea55eaa0c4b",
      "topic": null,
      "seed": "2157878068",
      "sound": "سعيد",
      "created_at": "2025-12-30T18:09:49.594800Z",
      "model": "FUZZ-2.0 Pro",
      "progress": "100%",
      "state": "succeeded",
      "duration": "172.3849433106576"
    }
  ]
}

​
نسخة صوتية

إذا كنت ترغب في استخدام النسخة الرسمية من الصوت، يمكنك تعيين قيمة معلمة action إلى: swap_vocals، بعد ذلك سنقوم بتخصيص إنشاء الأغنية بناءً على الكلمات، العنوان، الأسلوب. نموذج التعبئة كما يلي:

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

الكود المقابل: 
curl -X POST 'https://api.acedata.cloud/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "swap_vocals",
  "model": "FUZZ-2.0 Pro",
  "instrumental": false,
  "lyric": "[Verse]\nاستيقظت مع الشمس في عيني\nلا سحب فوقي فقط زرقة في السماء\nالأحذية على قدمي أنا مستعد للجري\nكل خطوة تشعر وكأنها مسدس محشو\n[Chorus]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[Verse 2]\nأرقص في شوارع المدينة\nإيقاع يدق في نبض قلبي\nالغرباء يبتسمون إنه ينتشر\nهذا العالم مسرح ونحن جميعاً أغنية\n[Chorus]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[Bridge]\nألقِ همومك خارج الباب\nدعها تغوص في قاع المحيط\nنحن أحياء وهذا يكفي\nالحياة فوضوية لكنها حب\n[Chorus]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً",
  "weirdness": 0.6,
  "lyrics_strength": 0.8,
  "audio_id": "d9ebc609-fb65-4a23-b914-c074747af6a4",
  "custom": true
}'
اختبار مسموح، التأثير الناتج مشابه. 
{
  "success": true,
  "task_id": "a903ac38-f129-4f85-9181-b1dc5579bd32",
  "trace_id": "9953af52-45e0-4808-bf13-88f0b21262c1",
  "data": [
    {
      "id": "7b2d653b-aaaa-41b0-b737-aee4c4c5693b",
      "title": "استيقظت مع الشمس في عيني",
      "image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/image/7b2d653b-aaaa-41b0-b737-aee4c4c5693b.jpg",
      "lyric": "[Verse]\nاستيقظت مع الشمس في عيني\nلا سحب فوقي فقط زرقة في السماء\nالأحذية على قدمي أنا مستعد للجري\nكل خطوة تشعر وكأنها مسدس محشو\n[Chorus]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[Verse 2]\nأرقص في شوارع المدينة\nإيقاع يدق في نبض قلبي\nالغرباء يبتسمون إنه ينتشر\nهذا العالم مسرح ونحن جميعاً أغنية\n[Chorus]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[Bridge]\nألقِ همومك خارج الباب\nدعها تغوص في قاع المحيط\nنحن أحياء وهذا يكفي\nالحياة فوضوية لكنها حب\n[Chorus]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً",
      "audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/audio/7b2d653b-aaaa-41b0-b737-aee4c4c5693b.m4a",
      "video_url": null,
      "image_id": "7b2d653b-aaaa-41b0-b737-aee4c4c5693b",
      "topic": null,
      "seed": "2484735707",
      "sound": "",
      "created_at": "2025-12-30T18:13:01.349875Z",
      "model": "FUZZ-2.0 Pro",
      "progress": "100%",
      "state": "succeeded",
      "duration": "173.12798185941043"
    }
  ]
}

​
فصل الكلمات والألحان

إذا كنت ترغب في استخدام عملية فصل الكلمات والألحان الرسمية، يمكنك تعيين قيمة معلمة action إلى: stems، بعد ذلك نحتاج إلى فصل الكلمات والألحان بناءً على معرف الأغنية. نموذج التعبئة كما يلي:

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

الكود المقابل: 
curl -X POST 'https://api.acedata.cloud/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "stems",
  "audio_id": "a54609c6-13e2-4176-be0f-4d7eebc68e1f"
}'
اختبار مسموح، التأثير الناتج مشابه. 
{
    "success": true,
    "task_id": "561ac695-b4aa-47cf-978d-fb7be2b9ebfc",
    "trace_id": "66d0d397-2987-4bde-84fb-a60d0023b217",
    "data": [
        {
            "title": "استيقظت مع الشمس في عيني",
            "lyric": "",
            "stems_url": "https://platform.cdn.acedata.cloud/producer/561ac695-b4aa-47cf-978d-fb7be2b9ebfc.zip",
            "model": "",
            "progress": "100%",
            "state": "succeeded"
        }
    ]
}

​
ردود غير متزامنة

نظرًا لأن وقت توليد واجهة برمجة التطبيقات لإنتاج الصوتيات قد يكون طويلًا نسبيًا في بعض الأحيان، إذا لم تستجب واجهة برمجة التطبيقات لفترة طويلة، ستظل طلبات HTTP متصلة، مما يؤدي إلى استهلاك موارد النظام الإضافية، لذا توفر هذه الواجهة أيضًا دعمًا للردود غير المتزامنة. تتكون العملية العامة من: عندما يقوم العميل بإرسال الطلب، يحدد حقل callback_url إضافي، بعد أن يقوم العميل بإرسال طلب واجهة برمجة التطبيقات، ستقوم الواجهة على الفور بإرجاع نتيجة تحتوي على معلومات حقل task_id، تمثل معرف المهمة الحالية. عندما تكتمل المهمة، سيتم إرسال نتيجة المهمة الناتجة إلى callback_url المحدد من قبل العميل بشكل POST JSON، والتي تتضمن أيضًا حقل task_id، بحيث يمكن ربط نتيجة المهمة من خلال المعرف. دعونا نفهم كيفية القيام بذلك من خلال مثال. أولاً، ردود Webhook هي خدمة يمكنها استقبال طلبات HTTP، يجب على المطورين استبدالها بعنوان URL الخاص بالخادم HTTP الذي قاموا بإنشائه. هنا، لتسهيل العرض، نستخدم موقع Webhook عينة عام https://webhook.site/، افتح هذا الموقع للحصول على عنوان URL Webhook، كما هو موضح في الصورة: انسخ هذا العنوان URL، يمكنك استخدامه كـ Webhook، والعينة هنا هي https://webhook.site/#!/view/0d73431d-f833-4be4-9276-b6e1690d55c1. بعد ذلك، يمكننا تعيين حقل callback_url إلى عنوان URL Webhook المذكور أعلاه، مع ملء المعلمات المناسبة، كما هو موضح في الصورة:

عند النقر على تشغيل، يمكنك أن تجد أنك ستحصل على نتيجة على الفور، كما يلي: 
{
  "task_id": "1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad"
}
稍等片刻，我们可以在 https://webhook.site/#!/view/0d73431d-f833-4be4-9276-b6e1690d55c1 上观察到生成任务的结果，如图所示： 内容如下： 
{
    "success": true,
    "task_id": "1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad",
    "trace_id": "1da03537-4eb8-410d-b849-43f03085a3bb",
    "data": [
        {
            "id": "1dd08826-478e-43a6-868f-aff5ababac2c",
            "title": "استيقظت مع الشمس في عيني",
            "image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/3bff6223-fe13-4bef-973e-2cbaef430d5d/image/1dd08826-478e-43a6-868f-aff5ababac2c.jpg",
            "lyric": "[المقطع]\nاستيقظت مع الشمس في عيني\nلا سحب فوقي فقط زرقة في السماء\nالأحذية على قدمي أنا مستعد للجري\nكل خطوة تشعر وكأنها مسدس محشو\n[الكورس]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[المقطع 2]\nأرقص في شوارع المدينة\nإيقاع يدق في نبض قلبي\nالغرباء يبتسمون، إنه معدٍ\nهذا العالم مسرح، نحن جميعاً أغنية\n[الكورس]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً\n[الجسر]\nألقِ همومك خارج الباب\nدعها تغوص في قاع المحيط\nنحن أحياء وهذا يكفي\nالحياة فوضوية لكنها حب\n[الكورس]\nأيام سعيدة تتدحرج\nدع الفرح تحت جلدي\nلا مزيد من الظلال لا مزيد من الأكاذيب\nفقط الحقيقة التي ترفعني عالياً",
            "audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/3bff6223-fe13-4bef-973e-2cbaef430d5d/audio/1dd08826-478e-43a6-868f-aff5ababac2c.m4a",
            "video_url": null,
            "image_id": "1dd08826-478e-43a6-868f-aff5ababac2c",
            "topic": null,
            "seed": "1490770667",
            "sound": "",
            "created_at": "2025-12-30T18:36:00.994141Z",
            "model": "FUZZ-2.0 Pro",
            "progress": "100%",
            "state": "succeeded",
            "duration": "135.2330158730159"
        }
    ]
}
可以看到结果中有一个 task_id 字段，其他的字段都和上文类似，通过该字段即可实现任务的关联。

​
错误处理

在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：
  • 400 token_mismatched：طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
  • 400 api_not_implemented：طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
  • 401 invalid_token：غير مصرح، توكن التفويض غير صالح أو مفقود.
  • 429 too_many_requests：طلبات كثيرة جداً، لقد تجاوزت الحد الأقصى للطلبات.
  • 500 api_error：خطأ في الخادم الداخلي، حدث خطأ ما في الخادم.

​
错误响应示例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "فشل في الاسترجاع"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
结论

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