> ## 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 Model Query API

> Fish music generation 集成指南 - XHuoAPI

تقدم هذه الوثيقة شرحًا لدمج واجهة برمجة التطبيقات Fish Model Query API (`GET /fish/model`)، والتي تتوافق تمامًا مع [Fish Audio الرسمية OpenAPI](https://docs.fish.audio/resources/api-reference/model)، وتُستخدم **للبحث الصفحي** عن قائمة نغمات الاستنساخ المرئية للحساب الحالي أو على مستوى المنصة بأكملها.

> لإنشاء نغمة، يرجى الرجوع إلى [Fish Model Create API](https://api.xhuoapi.ai/documents/62fdf4f1-6a05-4d92-bb15-1bf78b27a14a)، وللبحث عن تفاصيل نغمة واحدة بواسطة `_id` يرجى الرجوع إلى [Fish Model Get API](https://api.xhuoapi.ai/documents/dabdffe7-254b-5a3f-9eca-425d614d82b9).

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

لاستخدام API، يجب أولاً التقديم للحصول على الخدمة المناسبة من خلال صفحة [Fish Model API](https://api.xhuoapi.ai/services/caf99abc-ddcf-4714-b2a5-862d9b469509)، بعد الدخول إلى الصفحة اضغط على زر "Acquire".

إذا لم تكن مسجلاً أو مسجلاً دخولًا، سيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لتسجيل حساب جديد أو تسجيل الدخول، وبعد ذلك ستعود تلقائيًا إلى الصفحة الحالية.

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

## الاختلافات عن API الرسمي

* **طريقة المصادقة**: تستخدم `Authorization: Bearer {token}`، حيث `{token}` هو المفتاح الذي تم الحصول عليه من هذه المنصة.
* **هيكل الاستجابة**: يتم تمرير استجابة الصفحات من Fish مباشرة بدون تغليف (envelope) من المنصة؛ في حالة الخطأ يتم استخدام الهيكل القياسي للمنصة `{success:false, error:{code,message}, trace_id}`.

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

```shell theme={null}
curl -G 'https://api.xhuoapi.ai/v1/fish/model' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'page_size=10' \
  --data-urlencode 'page_number=1' \
  --data-urlencode 'self=true'
```

## معلمات الاستعلام

مطابقة للواجهة الرسمية لـ Fish:

* `page_size`: عدد العناصر في الصفحة، الافتراضي 10.
* `page_number`: رقم الصفحة، يبدأ من 1.
* `title`: بحث نصي غير دقيق حسب العنوان.
* `tag`: تصفية حسب الوسوم.
* `self`: عند تمرير `true` يتم إرجاع النغمات التي أنشأها الحساب الحالي فقط.
* `author_id`: تصفية حسب المنشئ.
* `language`: تصفية حسب لغة النغمة.
* `title_language`: تصفية حسب لغة العنوان.

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

الاستجابة الناجحة تمرر هيكل الصفحات من منصة Fish مباشرة:

```json theme={null}
{
  "items": [
    {
      "_id": "d7900c21663f485ab63ebdb7e5905036",
      "title": "نغمة الاستنساخ الخاصة بي",
      "description": "نغمة استنسخت باستخدام تسجيل بودكاست",
      "cover_image": "https://example.com/cover.png",
      "type": "tts",
      "state": "trained",
      "tags": [],
      "languages": ["zh", "en"],
      "visibility": "private",
      "created_at": "2025-05-09T12:34:56.789Z",
      "updated_at": "2025-05-09T12:34:56.789Z"
    }
  ],
  "total": 1
}
```

القيمة `_id` المعادة يمكن استخدامها كقيمة لحقل `reference_id` في [Fish TTS API](https://api.xhuoapi.ai/documents/77adcb84-d59f-5ef9-b8a0-8b35eb42a71d) لاستخدام هذه النغمة المستنسخة في توليد الصوت.

## شرح التسعير

هذه الواجهة غير خاضعة للتسعير — البحث الصفحي في قائمة النغمات هو عملية مجانية، ويتم احتساب التكلفة فقط عند إنشاء نغمة جديدة عبر `POST /fish/model` مع حقل `voices` في جسم الطلب.

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

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

## الخلاصة

توفر واجهة Fish Model Query API قدرة بحث عن النغمات متوافقة تمامًا مع Fish Audio الرسمية، ويمكن استخدامها للحفاظ على مكتبة نغمات استنساخ خاصة بك على هذه المنصة. وبالاشتراك مع [Fish Model Get API](https://api.xhuoapi.ai/documents/dabdffe7-254b-5a3f-9eca-425d614d82b9) يمكنك الحصول على تفاصيل كاملة لنغمة واحدة حسب المعرف.