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

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 Audio الرسمية المفتوحة، وتشمل:
  • POST /fish/model: إنشاء نموذج صوتي مستنسخ جديد بناءً على عينة صوتية.
  • GET /fish/model: استعلام مجزأ لقائمة النماذج الصوتية المتاحة للحساب الحالي أو على مستوى المنصة.

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

لاستخدام API، يجب أولاً التقديم للحصول على الخدمة المناسبة عبر صفحة Fish Model API، وعند الدخول إلى الصفحة، اضغط على زر “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 أو أعلى. 
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: 
{
  "_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)

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
}

​
شرح التسعير

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

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

  • 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 متوافقة تمامًا مع واجهة ModelEntity الرسمية لـ Fish Audio، مما يتيح نقل كود إدارة النماذج الصوتية المستنسخة الحالي بدون تعديل. يمكن استخدام معرف النموذج الصوتي _id الناتج مباشرة كقيمة لحقل reference_id في واجهة برمجة تطبيقات Fish TTS لإجراء التوليد الصوتي.