واجهة برمجة تطبيقات توليد الصوتيات للمنتج - تعليمات الدمج

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

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

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

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

📘 الوثائق الكاملة: واجهة برمجة تطبيقات توليد الصوتيات للمنتج →

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

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

يمكنك أن ترى أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:

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

بالإضافة إلى ذلك، تشمل معلمات جسم الطلب:

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 الذي يحتاج إلى استدعاء النتائج.
async: اختياري، عند تعيينه إلى true، ستعيد الواجهة على الفور task_id، دون الحاجة لتقديم callback_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://cdn.acedata.cloud/e724d7f13d.png",
      "lyric": "[Instrumental]",
      "audio_url": "https://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3",
      "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://cdn.acedata.cloud/e724d7f13d.png",
      "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://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3",
      "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://cdn.acedata.cloud/e724d7f13d.png",
      "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://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3",
      "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، وإدخال 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": "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://cdn.acedata.cloud/e724d7f13d.png",
      "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://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3",
      "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",
  "model": "FUZZ-2.0 Pro",
  "seed": "358803418",
  "custom": true
}'

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://cdn.acedata.cloud/e724d7f13d.png",
            "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://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3",
            "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://cdn.acedata.cloud/e724d7f13d.png",
            "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://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3",
            "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://cdn.acedata.cloud/e724d7f13d.png",
      "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://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3",
      "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": "[المقطع]\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فقط الحقيقة التي ترفعني عالياً",
  "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://cdn.acedata.cloud/e724d7f13d.png",
      "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://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3",
      "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://cdn.acedata.cloud/e724d7f13d.png",
            "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://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3",
            "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 في النتيجة، بينما الحقول الأخرى مشابهة لما سبق، من خلال هذا الحقل يمكن تحقيق ارتباط المهام.

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

عند استدعاء واجهة برمجة التطبيقات، إذا واجهت خطأ، ستقوم واجهة برمجة التطبيقات بإرجاع رمز الخطأ والمعلومات ذات الصلة. على سبيل المثال:

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"
}

الاستنتاج

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

البداية

دردشة الذكاء الاصطناعي

صورة الذكاء الاصطناعي

فيديو الذكاء الاصطناعي

الصوت الذكي

الويب والبيانات

CAPTCHA

الهوية

وكيل

متقدم

Coding

واجهة برمجة تطبيقات توليد الصوتيات للمنتج - تعليمات الدمج

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

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

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

إعادة غناء الأغاني

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

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

استبدال مقطع

نسخة مرافقة

نسخة الصوت البشري

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

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

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

مثال على استجابة الخطأ

الاستنتاج

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

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

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

​إعادة غناء الأغاني

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

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

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

​نسخة مرافقة

​نسخة الصوت البشري

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

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

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

​مثال على استجابة الخطأ

​الاستنتاج

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

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

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

إعادة غناء الأغاني

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

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

استبدال مقطع

نسخة مرافقة

نسخة الصوت البشري

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

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

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

مثال على استجابة الخطأ

الاستنتاج