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

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 TTS API، حيث أن هذه الواجهة متوافقة تمامًا مع Fish Audio OpenAPI الرسمي، ويمكنك ببساطة نقل الأكواد التي كانت تستدعي https://api.fish.audio/v1/tts إلى https://api.xhuoapi.ai/v1/fish/tts مع استبدال معلومات المصادقة فقط، دون الحاجة لتعديل هيكل جسم الطلب.

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

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

​
الفروقات مع API الرسمي

يحافظ هذا API على حقول الطلب والاستجابة الرسمية لـ Fish Audio مع بعض التحسينات الطفيفة لتسهيل التكامل على منصتنا:
  • طريقة المصادقة: تستخدم Authorization: Bearer {token} حيث {token} هو المفتاح الذي تم الحصول عليه من منصتنا وليس مفتاح Fish الرسمي.
  • اختيار نموذج TTS: يتم تحديده عبر رأس HTTP model، والقيم الممكنة هي s1 أو s2-pro، والقيمة الافتراضية هي s2-pro، وهو مطابق لما هو في Fish الرسمي.
  • القيمة الافتراضية لـ latency: في الواجهة الأصلية /fish/v1/tts إذا لم يتم تمرير latency يتم إرجاع خطأ، أما في هذه الواجهة يتم تلقائيًا تعيين latency=normal عند عدم وجوده، وهو سلوك مطابق للواجهة الرسمية.
  • الاستدعاء غير المتزامن (توسعة المنصة): عند تمرير حقل إضافي callback_url في جسم الطلب، ستقوم الواجهة بإرجاع {task_id, started_at} فورًا، وبعد الانتهاء من المعالجة في الخلفية، سيتم إرسال النتيجة الكاملة {audio_url, ...} عبر POST بصيغة JSON إلى عنوان URL المحدد. لا تدعم الواجهة الرسمية هذا الحقل، وتمريره يؤدي فقط إلى تفعيل هذه الخاصية في منصتنا.
بخلاف الفروقات المذكورة، يتم تمرير جميع حقول طلب TTS (text، reference_id، references، prosody، format، sample_rate، mp3_bitrate، chunk_length، temperature، top_p، وغيرها) مباشرة إلى الواجهة الأصلية، مع سلوك مطابق تمامًا للوثائق الرسمية.

​
الاستخدام الأساسي

أصغر طلب يحتاج فقط إلى تمرير حقل text، مثال CURL كالتالي: 
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。"
  }'
مثال على نتيجة الاستجابة: 
{
  "audio_url": "https://platform.r2.fish.audio/task/8a72ff9840234006a9f74cb2fa04f978.mp3"
}
النتيجة تحتوي مباشرة على الحقول الرسمية لـ Fish، بما في ذلك:
  • audio_url: رابط الصوت المُنتج، يمكن تحميله أو تشغيله مباشرة.
  • latency_ms (اختياري): زمن المعالجة في الخلفية بالميلي ثانية.
إذا كنت ترغب في استخدام صوت مستنسخ، يمكنك إضافة reference_id في جسم الطلب: 
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。",
    "reference_id": "d7900c21663f485ab63ebdb7e5905036",
    "format": "mp3",
    "sample_rate": 44100
  }'

​
الاستدعاء غير المتزامن

نظرًا لأن توليد النصوص الطويلة في Fish TTS قد يستغرق وقتًا طويلاً، والحفاظ على اتصال طويل قد يستهلك موارد النظام، يوفر هذا API خاصية الاستدعاء غير المتزامن (وهي توسعة مقارنة بالواجهة الرسمية). العملية هي: عند إرسال الطلب، يتم تمرير حقل callback_url في جسم الطلب، فتقوم الواجهة بإرجاع استجابة فورية تحتوي على task_id، وعند الانتهاء من التوليد فعليًا، يتم إرسال النتيجة النهائية مثل audio_url عبر POST بصيغة JSON إلى callback_url، مع تضمين نفس task_id لربط النتيجة بالمهمة الأصلية. مثال على الطلب: 
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'
الاستجابة الفورية تكون كالتالي: 
{
  "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "started_at": "2025-05-09T12:34:56.789Z"
}
بعد فترة قصيرة، سيصل إلى callback_url النتيجة الكاملة: 
{
  "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "audio_url": "https://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
}
يمكنك أيضًا استخدام Fish Tasks API للاستعلام عن حالة المهمة بشكل نشط عبر task_id.

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

تحتفظ هذه الواجهة برموز حالة HTTP الرسمية لـ Fish، لكن جسم الاستجابة يستخدم تنسيقًا موحدًا للمنصة ليتوافق مع سلسلة /fish/audios و /fish/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 TTS API متوافقة تمامًا مع Fish Audio OpenAPI الرسمي، مما يتيح ترحيل المشاريع الحالية بدون تعديل في الكود، مع الاستفادة من المصادقة الموحدة، تتبع الاستخدام، وقدرات الاستدعاء غير المتزامن التي توفرها المنصة. يُنصح باستخدام الاستدعاء غير المتزامن عند توليد نصوص طويلة لتجنب استهلاك موارد الاتصال الطويلة.