> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# واجهة برمجة تطبيقات مهام Fish والتكامل والاستخدام

> Fish music generation 集成指南 - XHuoAPI

الوظيفة الرئيسية لواجهة برمجة تطبيقات مهام Fish هي استعلام حالة تنفيذ المهمة من خلال إدخال معرف المهمة الذي تم إنشاؤه بواسطة واجهة برمجة تطبيقات توليد الصوتيات Fish.

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

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

لاستخدام واجهة برمجة تطبيقات مهام Fish، يجب أولاً الذهاب إلى صفحة التقديم [واجهة برمجة تطبيقات توليد الصوتيات Fish](https://api.xhuoapi.ai/documents/e681b715-54fd-4464-a59a-d7f14500e095) لتقديم الطلب للخدمة المناسبة، ثم نسخ معرف المهمة من واجهة برمجة تطبيقات توليد الصوتيات Fish، كما هو موضح في الصورة:

<p>
  <img src="https://cdn.xhuoapi.ai/jxvue8.png" width="500" className="m-auto" />
</p>

أخيرًا، انتقل إلى صفحة واجهة برمجة تطبيقات المهام [واجهة برمجة تطبيقات مهام Fish](https://api.xhuoapi.ai/documents/44c93949-1419-4a45-8db5-8a8335de7151) لتقديم الطلب للخدمة المناسبة، بعد دخول الصفحة، انقر على زر "Acquire"، كما هو موضح في الصورة:

![صفحة التقديم](https://cdn.xhuoapi.ai/rci31i.png)

إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى [صفحة تسجيل الدخول](https://api.xhuoapi.ai) لدعوتك للتسجيل وتسجيل الدخول، بعد تسجيل الدخول أو التسجيل، سيتم العودة تلقائيًا إلى الصفحة الحالية.

عند التقديم لأول مرة، سيكون هناك حد مجاني متاح، يمكنك استخدام هذه الواجهة مجانًا.

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

يمكن استخدام واجهة برمجة تطبيقات مهام Fish لاستعلام نتائج واجهة برمجة تطبيقات توليد الصوتيات Fish. لمزيد من المعلومات حول كيفية استخدام واجهة برمجة تطبيقات توليد الصوتيات Fish، يرجى الرجوع إلى الوثيقة [واجهة برمجة تطبيقات توليد الفيديوهات Fish](https://api.xhuoapi.ai/documents/fish-audios-integration).

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

### مثال على المهمة

<p>
  <img src="https://cdn.xhuoapi.ai/jxvue8.png" width="500" className="m-auto" />
</p>

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

**رؤوس الطلب** تشمل:

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

**جسم الطلب** يشمل:

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

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

<p>
  <img src="https://cdn.xhuoapi.ai/xc5ejq.png" width="500" className="m-auto" />
</p>

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

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

<p>
  <img src="https://cdn.xhuoapi.ai/851zv2.png" width="500" className="m-auto" />
</p>

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

#### CURL

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "action": "retrieve"
}'
```

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

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

```json theme={null}
{
  "_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,
  "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://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
      }
    ]
  }
}
```

تتضمن النتيجة عدة حقول، حيث يمثل حقل request جسم الطلب عند بدء المهمة، بينما يمثل حقل response جسم الاستجابة الذي يتم إرجاعه بعد إكمال المهمة. توضيح الحقول كما يلي.

* `id`: معرف هذه المهمة، يستخدم لتحديد هذه المهمة بشكل فريد.
* `request`: معلومات الطلب في المهمة.
* `response`: معلومات الاستجابة في المهمة.

## عمليات الاستعلام الجماعي

هذا مخصص لاستعلام تفاصيل المهام لعدة معرفات، وما يميزها عن السابقة هو أنه يجب اختيار action كـ retrieve\_batch.

**جسم الطلب** يشمل:

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

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

<p>
  <img src="https://cdn.xhuoapi.ai/64lid9.png" width="500" className="m-auto" />
</p>

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

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

<p>
  <img src="https://cdn.xhuoapi.ai/ezkzmw.png" width="500" className="m-auto" />
</p>

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

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

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

```json theme={null}
{
  "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,
      "credential_id": "881ad87d-8ba7-40b7-ac45-d19e41ae6e3a",
      "request": {
        "action": "speech",
        "prompt": "قط سيامي أبيض",
        "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://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.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,
      "credential_id": "881ad87d-8ba7-40b7-ac45-d19e41ae6e3a",
      "request": {
        "action": "speech",
        "prompt": "قط سيامي أبيض",
        "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://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
          }
        ]
      }
    }
  ],
  "count": 2
}
```

#### CURL

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/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"
}'
```

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

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

* `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": "فشل في الاسترجاع"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## الاستنتاج

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