> ## 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 Audio الرسمية المفتوحة](https://docs.fish.audio/resources/api-reference/model)، وتشمل:

* `POST /fish/model`: إنشاء نموذج صوتي مستنسخ جديد بناءً على عينة صوتية.
* `GET /fish/model`: استعلام مجزأ لقائمة النماذج الصوتية المتاحة للحساب الحالي أو على مستوى المنصة.

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

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

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

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

## الاختلافات مع واجهة برمجة التطبيقات الرسمية

* **طريقة المصادقة**: تستخدم `Authorization: Bearer {token}` حيث `{token}` هو المفتاح الذي تم الحصول عليه من هذه المنصة.
* **رفع العينات عند إنشاء النموذج**: تدعم هذه الواجهة حاليًا فقط إرسال العينات بصيغة JSON عبر حقل `voices` الذي يحتوي على روابط URL للعينات الصوتية. بينما تدعم Fish الرسمية رفع الملفات الثنائية مباشرة عبر multipart/msgpack، وهذه المنصة لم تنفذ ذلك بعد. شكل URL يغطي حوالي 80% من السيناريوهات الشائعة.
* **هيكل الاستجابة**: كل من `POST /fish/model` و `GET /fish/model` يعيدان استجابة Fish الأصلية مباشرة دون تغليف إضافي من المنصة، وفي حالة الخطأ تستخدم المنصة الهيكل القياسي `{success:false, error:{code,message}, trace_id}`.

## إنشاء نموذج صوتي (POST /fish/model)

الحد الأدنى للطلب يتطلب حقلي `title` و `voices`. حيث `voices` هو قائمة روابط URL للعينات الصوتية، يُنصح بأن يكون كل ملف أكثر من 30 ثانية بمعدل عينة 16k أو أعلى.

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/fish/model' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "title": "نموذجي المستنسخ",
    "description": "نموذج صوت مستنسخ من تسجيل بودكاست",
    "voices": [
      "https://example.com/sample-voice.mp3"
    ],
    "cover_image": "https://example.com/cover.png",
    "visibility": "private"
  }'
```

الاستجابة الناجحة تعيد مباشرة كائن ModelEntity الخاص بمنصة Fish:

```json theme={null}
{
  "_id": "d7900c21663f485ab63ebdb7e5905036",
  "type": "tts",
  "title": "نموذجي المستنسخ",
  "description": "نموذج صوت مستنسخ من تسجيل بودكاست",
  "cover_image": "https://example.com/cover.png",
  "train_mode": "fast",
  "state": "trained",
  "tags": [],
  "samples": [],
  "created_at": "2025-05-09T12:34:56.789Z",
  "updated_at": "2025-05-09T12:34:56.789Z",
  "languages": ["zh", "en"],
  "visibility": "private",
  "lock_visibility": false,
  "like_count": 0,
  "mark_count": 0,
  "shared_count": 0,
  "task_count": 0,
  "author": {
    "_id": "user_id",
    "nickname": "user_nickname",
    "avatar": "user_avatar"
  }
}
```

يمكن استخدام القيمة `_id` المعادة كقيمة لحقل `reference_id` في طلبات `POST /fish/tts` لاحقًا لاستخدام النموذج الصوتي المستنسخ في التوليد الصوتي.

## استعلام قائمة النماذج الصوتية (GET /fish/model)

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

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

يتم احتساب التكلفة فقط عند "إنشاء نموذج صوتي" (`POST /fish/model` مع وجود حقل `voices` في جسم الطلب)، بينما "استعلام قائمة النماذج الصوتية" (`GET /fish/model`) لا يتم تحصيل رسوم عليه.

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

* `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 متوافقة تمامًا مع واجهة ModelEntity الرسمية لـ Fish Audio، مما يتيح نقل كود إدارة النماذج الصوتية المستنسخة الحالي بدون تعديل. يمكن استخدام معرف النموذج الصوتي `_id` الناتج مباشرة كقيمة لحقل `reference_id` في [واجهة برمجة تطبيقات Fish TTS](https://api.xhuoapi.ai/documents/77adcb84-d59f-5ef9-b8a0-8b35eb42a71d) لإجراء التوليد الصوتي.