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

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

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

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

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

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

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

يمكن استخدام Fish Tasks API للاستعلام عن نتائج Fish Audios Generation API. حول كيفية استخدام Fish Audios Generation API، يرجى الرجوع إلى الوثائق Fish Videos Generation API . سنأخذ معرّف مهمة واحدًا تم إرجاعه بواسطة خدمة Fish Audios Generation API كمثال، لعرض كيفية استخدام هذه الواجهة. افترض أن لدينا معرّف مهمة: 2725a2d3-f87e-4905-9c53-9988d5a7b2f5، وسنعرض بعد ذلك كيفية القيام بذلك عبر تمرير معرّف مهمة.

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

إعداد رؤوس الطلب وجسم الطلب

يتضمن Request Headers:

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

يتضمن Request Body:

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

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

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

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

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

CURL

curl -X POST 'https://api.acedata.cloud/fish/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "action": "retrieve"
}'

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

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

{
  "_id": "68cfad98550a4144a5476a92",
  "id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "api_id": "8e6f8083-4683-45fe-a993-3e1d993fc999",
  "application_id": "3559d836-2505-46be-96ea-ea72bcb7c080",
  "created_at": 1758440856.34,
  "started_at": 1758440856.4,
  "finished_at": 1758440869.2,
  "elapsed": 12.8,
  "credential_id": "881ad87d-8ba7-40b7-ac45-d19e41ae6e3a",
  "request": {
    "action": "speech",
    "prompt": "a white siamese cat",
    "model": "fish-tts",
    "voice_id": "d7900c21663f485ab63ebdb7e5905036",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  },
  "trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
  "type": "audios",
  "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
  "response": {
    "success": true,
    "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
    "trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
    "data": [
      {
        "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3"
      }
    ]
  }
}

تحتوي النتيجة المُرجعة على عدة حقول، وحقل request هو request body عند إنشاء المهمة، بينما حقل response هو response body المُرجع بعد اكتمال المهمة. تعريف الحقول كما يلي.

id، معرّف إنشاء هذه المهمة، ويُستخدم لتمييز مهمة الإنشاء هذه بشكل فريد.
request، معلومات الطلب في مهمة الاستعلام.
response، معلومات الإرجاع في مهمة الاستعلام؛ وعند النجاح النهائي، فإن cost.amount بداخله هو Credits التي تم خصمها فعليًا لهذه المرة من التركيب.
created_at، وقت إنشاء المهمة، طابع زمني Unix (بالثواني، عدد عشري).
started_at، وقت بدء تنفيذ المهمة، طابع زمني Unix (بالثواني، عدد عشري).
finished_at، وقت اكتمال المهمة، طابع زمني Unix (بالثواني، عدد عشري). لا يتم إرجاع هذا الحقل عندما لا تكتمل المهمة.
elapsed، الوقت المستغرق في تنفيذ المهمة، بوحدة الثواني (عدد عشري، مع الاحتفاظ بـ 3 منازل عشرية). لا يتم إرجاع هذا الحقل عندما لا تكتمل المهمة.

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

هذا مخصص للاستعلام عن تفاصيل المهام لعدة معرّفات مهام، والاختلاف عن أعلاه هو ضرورة تحديد action على أنه retrieve_batch يتضمن Request Body:

ids: مصفوفة معرّفات المهام المرفوعة.
action: طريقة تنفيذ العملية على المهمة.

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

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

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

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

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

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

{
  "items": [
    {
      "_id": "68cfad98550a4144a5476a92",
      "id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
      "api_id": "8e6f8083-4683-45fe-a993-3e1d993fc999",
      "application_id": "3559d836-2505-46be-96ea-ea72bcb7c080",
      "created_at": 1758440856.34,
      "started_at": 1758440856.4,
      "finished_at": 1758440869.2,
      "elapsed": 12.8,
      "credential_id": "881ad87d-8ba7-40b7-ac45-d19e41ae6e3a",
      "request": {
        "action": "speech",
        "prompt": "a white siamese cat",
        "model": "fish-tts",
        "voice_id": "d7900c21663f485ab63ebdb7e5905036",
        "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
      },
      "trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
      "type": "audios",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
        "trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
        "data": [
          {
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3"
          }
        ]
      }
    },
    {
      "_id": "68cfad98550a4144a5476a92",
      "id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
      "api_id": "8e6f8083-4683-45fe-a993-3e1d993fc999",
      "application_id": "3559d836-2505-46be-96ea-ea72bcb7c080",
      "created_at": 1758440856.34,
      "started_at": 1758440856.4,
      "finished_at": 1758440869.2,
      "elapsed": 12.8,
      "credential_id": "881ad87d-8ba7-40b7-ac45-d19e41ae6e3a",
      "request": {
        "action": "speech",
        "prompt": "a white siamese cat",
        "model": "fish-tts",
        "voice_id": "d7900c21663f485ab63ebdb7e5905036",
        "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
      },
      "trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
      "type": "audios",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
        "trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
        "data": [
          {
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3"
          }
        ]
      }
    }
  ],
  "count": 2
}

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

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

CURL

curl -X POST 'https://api.acedata.cloud/fish/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["2725a2d3-f87e-4905-9c53-9988d5a7b2f5","2725a2d3-f87e-4905-9c53-9988d5a7b2f5"],
  "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"
}

الخلاصة

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

البداية

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

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

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

الصوت الذكي

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

CAPTCHA

الهوية

Coding

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

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

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

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

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

إعداد رؤوس الطلب وجسم الطلب

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

CURL

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

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

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

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

CURL

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

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

الخلاصة

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

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

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

​إعداد رؤوس الطلب وجسم الطلب

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

​CURL

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

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

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

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

​CURL

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

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

​الخلاصة

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

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

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

إعداد رؤوس الطلب وجسم الطلب

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

CURL

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

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

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

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

CURL

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

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

الخلاصة