> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # تكامل واستخدام Suno Tasks API > Suno Music Generation API guide - Ace Data Cloud تتمثل الوظيفة الرئيسية لـ Suno Tasks API في الاستعلام عن حالة تنفيذ المهمة من خلال إدخال معرّف المهمة الذي تم إنشاؤه بواسطة Suno Audios Generation API أو Suno Lyrics Generation API. سيقدم هذا المستند بالتفصيل إرشادات تكامل Suno Tasks API، لمساعدتك على دمج هذه الواجهة والاستفادة الكاملة من وظائفها القوية بسهولة. من خلال Suno Tasks API، يمكنك بسهولة الاستعلام عن حالة تنفيذ مهام Suno Lyrics Generation API أو Suno Audios Generation API. ## عملية التقديم لاستخدام 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) ## مثال على الطلب يمكن استخدام Suno Tasks API للاستعلام عن نتائج كل من Suno Audios Generation API وSuno Lyrics Generation API. لمعرفة كيفية استخدام Suno Audios Generation API، يُرجى الرجوع إلى وثائق [Suno Audios Generation API](https://platform.acedata.cloud/documents/suno-audios-integration). ولمعرفة كيفية استخدام Suno Lyrics Generation API، يُرجى الرجوع إلى [Suno Lyrics Generation API](https://platform.acedata.cloud/documents/suno-lyrics-generation-integration). سنأخذ معرّف مهمة تم إرجاعه من خدمة Suno Audios Generation API كمثال لعرض كيفية استخدام هذه الواجهة. افترض أن لدينا معرّف مهمة: eae26f89-b64b-404d-a80c-761996660b1c، وسنعرض بعد ذلك كيفية تمرير معرّف مهمة من خلال. ### صورة مثال المهمة ![](https://cdn.acedata.cloud/bc6754.png) ### إعداد رؤوس الطلب وجسم الطلب تتضمن **Request Headers** ما يلي: * `accept`: يحدد استلام نتيجة الاستجابة بتنسيق JSON، ويُملأ هنا بـ `application/json`. * `authorization`: مفتاح استدعاء API، ويمكن اختياره مباشرةً من القائمة المنسدلة بعد التقديم. يتضمن **Request Body** ما يلي: * `id`: معرّف المهمة المرفوع. * `action`: طريقة تنفيذ العملية على المهمة. يتم الإعداد كما هو موضح في الصورة التالية: ![](https://cdn.acedata.cloud/uo7t6n.png) ### مثال على الكود يمكن ملاحظة أنه تم إنشاء أكواد بلغات مختلفة تلقائيًا بالفعل على الجانب الأيمن من الصفحة، كما هو موضح في الصورة: ![](https://cdn.acedata.cloud/p6vi9o.png) بعض أمثلة الأكواد كما يلي: #### CURL ```bash theme={null} curl -X POST 'https://api.acedata.cloud/suno/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "id": "eae26f89-b64b-404d-a80c-761996660b1c", "action": "retrieve" }' ``` #### Python ```python theme={null} import requests url = "https://api.acedata.cloud/suno/tasks" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "id": "eae26f89-b64b-404d-a80c-761996660b1c", "action": "retrieve" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` ### مثال على الاستجابة بعد نجاح الطلب، ستُرجع API معلومات تفصيلية عن مهمة الأغنية هنا. على سبيل المثال: ```json theme={null} { "_id": "66d2add5550a4144a5a88dfe", "id": "eae26f89-b64b-404d-a80c-761996660b1c", "api_id": "09a26295-5972-4392-9318-dcd9b218f90d", "application_id": "ab46a066-ad82-4180-b66b-49dedf8e8a2f", "created_at": 1725083093.077, "started_at": 1725083093.137, "finished_at": 1725083131.537, "elapsed": 38.4, "credential_id": "66614a7e-e624-494e-87a3-387099b8cbb4", "request": { "action": "generate", "prompt": "A song for Christmas" }, "trace_id": "e13d385a-077e-4376-be01-3465b61ca0fd", "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf", "response": { "success": true, "task_id": "eae26f89-b64b-404d-a80c-761996660b1c", "data": [ { "id": "b8a4f691-4b14-4120-a7e1-a54a27a0e57e", "title": "Holiday Wishes", "image_url": "https://cdn.acedata.cloud/e724d7f13d.png", "lyric": "[Verse]\nSnow is falling soft and white\nLights are twinkling oh so bright\nKids are laughing full of cheer\nChristmas time is finally here\n[Verse 2]\nBells are ringing in the night\nFireplace is warm with light\nCarols sung by the tree\nEveryone's together we agree\n[Chorus]\nHoliday wishes come true\nTime to share the joy with you\nSmiles and hugs for everyone\nMerry Christmas let's have fun\n[Verse 3]\nGifts are wrapped with loving care\nMagic's floating in the air\nCookies baking in the oven\nChristmas love to be given\n[Chorus]\nHoliday wishes come true\nTime to share the joy with you\nSmiles and hugs for everyone\nMerry Christmas let's have fun\n[Bridge]\nStars are shining in the sky\nHold your loved ones don't ask why\nHeart to heart we're all united\nOn this night we are delighted", "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", "created_at": "2024-08-31T05:44:54.806Z", "model": "chirp-v3.5", "prompt": "A song for Christmas", "style": "pop", "duration": 154.44 }, { "id": "1a3343b2-2c24-4584-a2a7-687e2f97f09e", "title": "Holiday Wishes", "image_url": "https://cdn.acedata.cloud/e724d7f13d.png", "lyric": "[Verse]\nSnow is falling soft and white\nLights are twinkling oh so bright\nKids are laughing full of cheer\nChristmas time is finally here\n[Verse 2]\nBells are ringing in the night\nFireplace is warm with light\nCarols sung by the tree\nEveryone's together we agree\n[Chorus]\nHoliday wishes come true\nTime to share the joy with you\nSmiles and hugs for everyone\nMerry Christmas let's have fun\n[Verse 3]\nGifts are wrapped with loving care\nMagic's floating in the air\nCookies baking in the oven\nChristmas love to be given\n[Chorus]\nHoliday wishes come true\nTime to share the joy with you\nSmiles and hugs for everyone\nMerry Christmas let's have fun\n[Bridge]\nStars are shining in the sky\nHold your loved ones don't ask why\nHeart to heart we're all united\nOn this night we are delighted", "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", "created_at": "2024-08-31T05:44:54.806Z", "model": "chirp-v3.5", "prompt": "A song for Christmas", "style": "pop", "duration": 147.16 } ] } } ``` تتضمن نتيجة الإرجاع عدة حقول، وحقل `request` هو `request body` عند بدء المهمة، بينما حقل `response` هو `response body` الذي يُرجع بعد اكتمال المهمة. وفيما يلي تعريف الحقول. * `id`، معرّف مهمة إنشاء هذه الأغنية، ويُستخدم لتمييز مهمة إنشاء الأغنية هذه بشكل فريد. * `request`، معلومات الطلب في استعلام مهمة الأغنية. * `response`، معلومات الإرجاع في استعلام مهمة الأغنية. * `created_at`، وقت إنشاء المهمة، طابع زمني Unix (بالثواني، رقم عشري). * `started_at`، وقت بدء تنفيذ المهمة، طابع زمني Unix (بالثواني، رقم عشري). * `finished_at`، وقت اكتمال المهمة، طابع زمني Unix (بالثواني، رقم عشري). لا يُرجع هذا الحقل عندما لا تكون المهمة مكتملة. * `elapsed`، الوقت المستغرق في تنفيذ المهمة، بوحدة الثواني (رقم عشري، مع الاحتفاظ بـ 3 منازل عشرية). لا يُرجع هذا الحقل عندما لا تكون المهمة مكتملة. ## عملية الاستعلام الدفعي هذا مخصص للاستعلام عن تفاصيل مهام الأغاني لعدة معرّفات مهام، والاختلاف عن المذكور أعلاه هو ضرورة تحديد `action` على أنه `retrieve_batch` يتضمن **Request Body** ما يلي: * `ids`: مصفوفة معرّفات المهام المرفوعة. * `action`: طريقة تنفيذ العملية على المهمة. يُضبط كما هو موضح في الصورة التالية: ![](https://cdn.acedata.cloud/dqeknz.png) ### مثال على الكود يمكن ملاحظة أنه تم إنشاء أكواد بلغات مختلفة تلقائيًا في الجانب الأيمن من الصفحة، كما هو موضح في الصورة التالية: ![](https://cdn.acedata.cloud/1yk792.png) بعض أمثلة الأكواد كما يلي: ### مثال على الاستجابة بعد نجاح الطلب، ستُرجع واجهة API معلومات التفاصيل المحددة لجميع مهام الأغاني الدفعية هذه. على سبيل المثال: ```json { theme={null} "items": [ { "_id": "66d2add5550a4144a5a88dfe", "id": "eae26f89-b64b-404d-a80c-761996660b1c", "api_id": "09a26295-5972-4392-9318-dcd9b218f90d", "application_id": "ab46a066-ad82-4180-b66b-49dedf8e8a2f", "created_at": 1725083093.077, "started_at": 1725083093.137, "finished_at": 1725083131.537, "elapsed": 38.4, "credential_id": "66614a7e-e624-494e-87a3-387099b8cbb4", "request": { "action": "generate", "prompt": "A song for Christmas" }, "trace_id": "e13d385a-077e-4376-be01-3465b61ca0fd", "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf", "response": { "success": true, "task_id": "eae26f89-b64b-404d-a80c-761996660b1c", "data": [ { "id": "b8a4f691-4b14-4120-a7e1-a54a27a0e57e", "title": "أمنيات العطلة", "image_url": "https://cdn.acedata.cloud/e724d7f13d.png", "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", "created_at": "2024-08-31T05:44:54.806Z", "model": "chirp-v3.5", "prompt": "أغنية لعيد الميلاد", "style": "بوب", "duration": 154.44 }, { "id": "1a3343b2-2c24-4584-a2a7-687e2f97f09e", "title": "أمنيات العطلة", "image_url": "https://cdn.acedata.cloud/e724d7f13d.png", "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", "created_at": "2024-08-31T05:44:54.806Z", "model": "chirp-v3.5", "prompt": "أغنية لعيد الميلاد", "style": "بوب", "duration": 147.16 } ] } }, { "_id": "66d2b03c550a4144a5a8d93d", "id": "0d3ed03b-912b-4f7d-941b-8441323cb77b", "api_id": "09a26295-5972-4392-9318-dcd9b218f90d", "application_id": "ab46a066-ad82-4180-b66b-49dedf8e8a2f", "created_at": 1725083708.53, "started_at": 1725083708.59, "finished_at": 1725083746.99, "elapsed": 38.4, "credential_id": "66614a7e-e624-494e-87a3-387099b8cbb4", "request": { "action": "إنشاء", "prompt": "لا لا لا" }, "trace_id": "29ebb919-1126-4156-86cc-4ad899432a8c", "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf", "response": { "success": true, "task_id": "0d3ed03b-912b-4f7d-941b-8441323cb77b", "data": [ { "id": "b4f498b2-e86f-4172-926a-39da9df84dd3", "title": "لا لا لا", "image_url": "https://cdn.acedata.cloud/e724d7f13d.png", "lyric": "[مقطع]\nأستيقظ كل صباح\nأنظر عبر النافذة\nضوء الشمس يلمع ساطعًا\nبداية يوم جديد\n[مقطع 2]\nالطيور تغني بفرح\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لا تتوقف\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", "created_at": "2024-08-31T05:55:09.345Z", "model": "chirp-v3.5", "prompt": "لا لا لا", "style": "بوب", "duration": 154.32 }, { "id": "8b44fdf1-3b88-47ac-a351-7c4b4de60549", "title": "لا لا لا", "image_url": "https://cdn.acedata.cloud/e724d7f13d.png", "lyric": "[المقطع]\nأستيقظ كل صباح\nأنظر عبر النافذة\nأشعة الشمس الساطعة المتألقة\nبداية يوم جديد\n[المقطع 2]\nالطيور تغني بفرح\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لا تتوقف\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", "created_at": "2024-08-31T05:55:09.345Z", "model": "chirp-v3.5", "prompt": "لا لا لا", "style": "بوب", "duration": 177.36 } ] } } ], "count": 2 } ``` تتضمن نتيجة الإرجاع عدة حقول إجمالًا، حيث يحتوي `items` على معلومات التفاصيل المحددة لمهام الأغاني المجمّعة، وتكون المعلومات المحددة لكل مهمة أغنية مماثلة للحقول المذكورة أعلاه، ومعلومات الحقول كما يلي. * `items`، جميع معلومات التفاصيل المحددة لمهام الأغاني المجمّعة. وهي مصفوفة، ويكون تنسيق كل عنصر في المصفوفة مطابقًا لتنسيق نتيجة الإرجاع للاستعلام عن مهمة واحدة المذكورة أعلاه. * `count`، عدد مهام الأغاني التي تم الاستعلام عنها دفعةً واحدة هنا. #### CURL ```bash theme={null} curl -X POST 'https://api.acedata.cloud/suno/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "ids": ["eae26f89-b64b-404d-a80c-761996660b1c","0d3ed03b-912b-4f7d-941b-8441323cb77b"], "action": "retrieve_batch" }' ``` #### Python ```python theme={null} import requests url = "https://api.acedata.cloud/suno/tasks" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "ids": ["eae26f89-b64b-404d-a80c-761996660b1c","0d3ed03b-912b-4f7d-941b-8441323cb77b"], "action": "retrieve_batch" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` ## معالجة الأخطاء عند استدعاء واجهة API، إذا واجهت خطأً، فستُرجع واجهة API رمز الخطأ والمعلومات المقابلة. على سبيل المثال: * `400 token_mismatched`：طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صالحة. * `400 api_not_implemented`：طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صالحة. * `401 invalid_token`：غير مُصرّح به، رمز التفويض غير صالح أو مفقود. * `429 too_many_requests`：طلبات كثيرة جدًا، لقد تجاوزت حد المعدل. * `500 api_error`：خطأ داخلي في الخادم، حدث خطأ ما على الخادم. ### مثال على استجابة الخطأ ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## الخلاصة من خلال هذا المستند، تعرفت بالفعل على كيفية استخدام Suno Tasks API للاستعلام عن جميع معلومات التفاصيل المحددة لمهمة أغنية واحدة أو مهام أغاني مجمّعة. نأمل أن يساعدك هذا المستند على التكامل مع واجهة API هذه واستخدامها بشكل أفضل. إذا كانت لديك أي أسئلة، فيرجى التواصل مع فريق الدعم الفني لدينا في أي وقت. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.