الانتقال إلى المحتوى الرئيسي

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 (GET /fish/model)، والتي تتوافق تمامًا مع Fish Audio الرسمية OpenAPI، وتُستخدم للبحث الصفحي عن قائمة نغمات الاستنساخ المرئية للحساب الحالي أو على مستوى المنصة بأكملها.
لإنشاء نغمة، يرجى الرجوع إلى Fish Model Create API، وللبحث عن تفاصيل نغمة واحدة بواسطة _id يرجى الرجوع إلى Fish Model Get API.

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

لاستخدام API، يجب أولاً التقديم للحصول على الخدمة المناسبة من خلال صفحة Fish Model API، بعد الدخول إلى الصفحة اضغط على زر “Acquire”. إذا لم تكن مسجلاً أو مسجلاً دخولًا، سيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لتسجيل حساب جديد أو تسجيل الدخول، وبعد ذلك ستعود تلقائيًا إلى الصفحة الحالية. عند التقديم لأول مرة، ستحصل على حصة مجانية يمكن استخدامها مجانًا مع هذه الواجهة.

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

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

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

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 مباشرة: 
{
  "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 لاستخدام هذه النغمة المستنسخة في توليد الصوت.

​
شرح التسعير

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

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

  • 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 Model Query API قدرة بحث عن النغمات متوافقة تمامًا مع Fish Audio الرسمية، ويمكن استخدامها للحفاظ على مكتبة نغمات استنساخ خاصة بك على هذه المنصة. وبالاشتراك مع Fish Model Get API يمكنك الحصول على تفاصيل كاملة لنغمة واحدة حسب المعرف.