تكامل واستخدام Producer Tasks API

تتمثل الوظيفة الرئيسية لـ Producer Tasks API في الاستعلام عن حالة تنفيذ المهمة عبر إدخال معرّف المهمة الذي تم إنشاؤه بواسطة Producer Audios Generation API. سيقدّم هذا المستند بالتفصيل شرح تكامل Producer Tasks API، لمساعدتك على دمج واستخدام الوظائف القوية لهذه API بسهولة وبشكل كامل. من خلال Producer Tasks API، يمكنك بسهولة الاستعلام عن حالة تنفيذ مهام Producer Audios Generation API.

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

لاستخدام Producer Audios Generation API، انتقل أولاً إلى وحدة تحكم Ace Data Cloud للحصول على API Token الخاص بك، واحتفظ به لاستخدامه لاحقاً.

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

📘 الوثائق الكاملة: Producer Audios Generation API →

مثال على الطلب

يمكن استخدام Producer Tasks API للاستعلام عن نتائج Producer Audios Generation API. لمعرفة كيفية استخدام Producer Audios Generation API، يرجى الرجوع إلى وثائق Producer Audios Generation API . سنأخذ معرّف مهمة واحداً تم إرجاعه من خدمة Producer Audios Generation API كمثال، لعرض كيفية استخدام هذه API. لنفترض أن لدينا معرّف مهمة: 1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad، وسنوضّح بعد ذلك كيفية تمرير معرّف مهمة واحد من خلاله.

صورة مثال للمهمة

إعداد رؤوس الطلب ونص الطلب

يتضمن Request Headers:

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

يتضمن Request Body:

id: معرّف المهمة المرفوعة.
action: طريقة العملية على المهمة.

يتم الإعداد كما هو موضح في الصورة التالية:

مثال على الكود

يمكن ملاحظة أنه تم إنشاء أكواد بلغات مختلفة تلقائياً بالفعل في الجانب الأيمن من الصفحة، كما هو موضح في الصورة:

بعض أمثلة الأكواد كما يلي:

CURL

curl -X POST 'https://api.acedata.cloud/producer/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad",
  "action": "retrieve"
}'

مثال على الاستجابة

بعد نجاح الطلب، ستعيد API معلومات تفصيلية حول المهمة هنا. على سبيل المثال:

{
  "_id": "69541b81ff2676299ccc3b29",
  "id": "1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad",
  "api_id": "01d96900-9f8c-41d7-814c-95c7a885ba61",
  "application_id": "920ba772-867a-48ae-8efa-9b9f94136199",
  "created_at": 1767119745.524,
  "started_at": 1767119745.584,
  "finished_at": 1767119785.589,
  "elapsed": 40.005,
  "credential_id": "eeae817d-d6ff-493e-8f88-6c62391da7c6",
  "request": {
    "action": "generate",
    "model": "FUZZ-2.0 Pro",
    "instrumental": false,
    "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high",
    "custom": true,
    "callback_url": "https://webhook.site/0d73431d-f833-4be4-9276-b6e1690d55c1"
  },
  "trace_id": "1da03537-4eb8-410d-b849-43f03085a3bb",
  "type": "audios",
  "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
  "response": {
    "task_id": "1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad",
    "data": [
      {
        "id": "1dd08826-478e-43a6-868f-aff5ababac2c",
        "title": "Woke up with the sun in my eyes",
        "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
        "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high",
        "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.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"
      }
    ]
  }
}

تتضمن النتيجة المُعادة عدة حقول، وحقل 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: طريقة إجراء العملية على المهمة.

الإعداد كما هو موضح في الشكل أدناه:

مثال على الكود

يمكن ملاحظة أنه تم بالفعل إنشاء كود بلغات مختلفة تلقائيًا في الجانب الأيمن من الصفحة، كما هو موضح في الشكل:

بعض أمثلة الكود كما يلي:

مثال على الاستجابة

بعد نجاح الطلب، ستُرجع API معلومات التفاصيل المحددة لجميع المهام الدفعية هذه. على سبيل المثال:

  "items": [
    {
      "_id": "69541b81ff2676299ccc3b29",
      "id": "1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad",
      "api_id": "01d96900-9f8c-41d7-814c-95c7a885ba61",
      "application_id": "920ba772-867a-48ae-8efa-9b9f94136199",
      "created_at": 1767119745.524,
      "started_at": 1767119745.584,
      "finished_at": 1767119785.589,
      "elapsed": 40.005,
      "credential_id": "eeae817d-d6ff-493e-8f88-6c62391da7c6",
      "request": {
        "action": "generate",
        "model": "FUZZ-2.0 Pro",
        "instrumental": false,
        "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high",
        "custom": true,
        "callback_url": "https://webhook.site/0d73431d-f833-4be4-9276-b6e1690d55c1"
      },
      "trace_id": "1da03537-4eb8-410d-b849-43f03085a3bb",
      "type": "audios",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "task_id": "1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad",
        "data": [
          {
            "id": "1dd08826-478e-43a6-868f-aff5ababac2c",
            "title": "Woke up with the sun in my eyes",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
            "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high",
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.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"
          }
        ]
      }
    }, {
      "_id": "69541b81ff2676299ccc3b29",
      "id": "1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad",
      "api_id": "01d96900-9f8c-41d7-814c-95c7a885ba61",
      "application_id": "920ba772-867a-48ae-8efa-9b9f94136199",
      "created_at": 1767119745.524,
      "started_at": 1767119745.584,
      "finished_at": 1767119785.589,
      "elapsed": 40.005,
      "credential_id": "eeae817d-d6ff-493e-8f88-6c62391da7c6",
      "request": {
        "action": "generate",
        "model": "FUZZ-2.0 Pro",
        "instrumental": false,
        "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high",
        "custom": true,
        "callback_url": "https://webhook.site/0d73431d-f833-4be4-9276-b6e1690d55c1"
      },
      "trace_id": "1da03537-4eb8-410d-b849-43f03085a3bb",
      "type": "audios",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response":
{
        "task_id": "1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad",
        "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://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.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": "نجح",
            "duration": "135.2330158730159"
          }
        ]
      }
    }
  ],
  "count": 2
}

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

items، جميع معلومات التفاصيل المحددة للمهام المجمعة. وهي مصفوفة، ويكون تنسيق كل عنصر في المصفوفة مماثلًا لتنسيق نتيجة الإرجاع للاستعلام عن مهمة واحدة المذكور أعلاه.
count، عدد المهام في هذا الاستعلام المجمع.

CURL

curl -X POST 'https://api.acedata.cloud/producer/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad","1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad"],
  "action": "retrieve_batch"
}'

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

عند استدعاء 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": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

الخلاصة

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

البداية

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

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

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

الصوت الذكي

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

CAPTCHA

الهوية

Coding

المزيد من الأدلة

تكامل واستخدام Producer Tasks API

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

مثال على الطلب

صورة مثال للمهمة

إعداد رؤوس الطلب ونص الطلب

مثال على الكود

CURL

مثال على الاستجابة

عملية الاستعلام الدفعي

مثال على الكود

مثال على الاستجابة

CURL

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

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

الخلاصة

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

​مثال على الطلب

​صورة مثال للمهمة

​إعداد رؤوس الطلب ونص الطلب

​مثال على الكود

​CURL

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

​عملية الاستعلام الدفعي

​مثال على الكود

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

​CURL

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

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

​الخلاصة

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

مثال على الطلب

صورة مثال للمهمة

إعداد رؤوس الطلب ونص الطلب

مثال على الكود

CURL

مثال على الاستجابة

عملية الاستعلام الدفعي

مثال على الكود

مثال على الاستجابة

CURL

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

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

الخلاصة