كيفية استخدام Fish Audio S2 API: دليل شامل مع Apidog

تُعد Fish Audio S2 API واجهة برمجة تطبيقات REST لتحويل النص إلى كلام بجودة إنتاجية، مدعومة بنموذج يحتوي على 4 مليارات معلمة وتم تدريبه على 10 ملايين ساعة من الصوت. تدعم استنساخ الصوت، والبث المباشر، وأكثر من 50 لغة. لاستخدام Fish Audio S2 API بكفاءة، بما في ذلك إرسال الطلبات، وإدارة المراجع، وتشغيل اختبارات الوحدة، يُعد Apidog أسرع طريقة لاستكشاف كل نقطة نهاية وتوثيقها والتحقق من صحتها.

مقدمة

لقد تجاوز الصوت الذي تولده الذكاء الاصطناعي عتبة جديدة. لم تعد نماذج تحويل النص إلى كلام الحديثة تبدو مثل الروبوتات؛ بل تهمس، وتضحك، وتغير نبرتها في منتصف الجملة. تقع Fish Audio S2 API في طليعة هذا التحول: نموذج بـ 4 مليارات معلمة تم تدريبه على أكثر من 10 ملايين ساعة من الصوت متعدد اللغات، قادر على إنتاج كلام لا يمكن تمييزه عن التسجيل البشري.

سواء كنت تقوم ببناء أداة لأتمتة البودكاست، أو مساعد صوتي تفاعلي، أو مسار عمل للدبلجة في الوقت الفعلي، فإن دمج Fish Audio S2 API في نظامك يتطلب أكثر من مجرد طلب POST واحد. تحتاج إلى فهم المصادقة، وإدارة الصوت المرجعي، وسلوك البث، والأهم من ذلك كيفية كتابة اختبارات وحدة موثوقة حتى لا يفشل تكاملك بصمت في الإنتاج.

زر

ما هي Fish Audio S2 API؟

تُعد Fish Audio S2 API الواجهة البرمجية HTTP لـ Fish Speech S2-Pro، وهو نظام مفتوح المصدر لتحويل النص إلى كلام (TTS) مبني على بنية Dual-Autoregressive (Dual-AR). يفصل النموذج التوليد الدلالي (4 مليارات معلمة، AR بطيء على طول المحور الزمني) عن توليد دفتر الرموز المتبقي (400 مليون معلمة، AR سريع على طول محور العمق)، مما يتيح توليفًا عالي الجودة بعامل زمني حقيقي قدره 0.195 على NVIDIA H200 واحد.

إمكانيات Fish Audio S2 API الرئيسية:

عنوان URL الأساسي لـ Fish Audio S2 API بعد النشر المحلي هو http://127.0.0.1:8080. تقع جميع نقاط النهاية ضمن مساحة الاسم /v1/.

البدء مع Fish Audio S2 API و Apidog

المتطلبات الأساسية لـ Fish Audio S2 API

قبل إجراء أول مكالمة لـ Fish Audio S2 API، تحتاج إلى تشغيل شيئين: خادم Fish Speech S2-Pro مُنشر وعميل API قادر على التعامل مع استجابات الصوت الثنائية.

ابدأ خادم Fish Audio S2 API:

python tools/api_server.py \
  --llama-checkpoint-path checkpoints/s2-pro \
  --decoder-checkpoint-path checkpoints/s2-pro/codec.pth \
  --listen 0.0.0.0:8080 \
  --compile \
  --half \
  --api-key YOUR_API_KEY \
  --workers 4

تُفعّل علامة --compile تحسين torch.compile وهذا يقلل زمن الاستجابة بحوالي 10 أضعاف ولكنه يضيف تكلفة تشغيل أولية لمرة واحدة عند الإطلاق الأول. تُمكن علامة --half وضع FP16 لتقليل استهلاك ذاكرة وحدة معالجة الرسوميات (GPU).

بمجرد تشغيل الخادم، تحقق منه بفحص صحي:

curl http://127.0.0.1:8080/v1/health
# {"status":"ok"}

إعداد Fish Audio S2 API في Apidog

نزّل Apidog مجانًا وأنشئ مشروع HTTP جديد. أضف عنوان URL الأساسي http://127.0.0.1:8080 تحت Environments. ثم قم بتعيين ترويسة عامة:

Authorization: Bearer YOUR_API_KEY

يخزن Apidog هذا على مستوى البيئة، لذا فإن كل طلب Fish Audio S2 API ترسله يرث الرمز المميز تلقائيًا، دون الحاجة إلى لصق الترويسة يدويًا لكل طلب. هذا مفيد بشكل خاص عندما يكون لديك بيئات Fish Audio S2 API متعددة (تطوير محلي، مرحلة تجريبية، إنتاج) للتبديل بينها.

إجراء طلبك الأول لـ Fish Audio S2 API في Apidog

اختبار نقطة نهاية تحويل النص إلى كلام في Fish Audio S2 API

نقطة نهاية Fish Audio S2 API الأساسية هي POST /v1/tts. في Apidog، أنشئ طلبًا جديدًا بهذا العنوان URL، واضبط الطريقة على POST، واستخدم جسم JSON التالي:

{
  "text": "مرحباً! هذا اختبار لواجهة برمجة تطبيقات Fish Audio S2.",
  "format": "wav",
  "streaming": false,
  "temperature": 0.8,
  "top_p": 0.8,
  "repetition_penalty": 1.1,
  "max_new_tokens": 1024
}

مخطط طلب Fish Audio S2 API TTS الكامل:

اضغط على إرسال في Apidog. تقوم Fish Audio S2 API بإرجاع بايتات صوتية خام. يكتشف Apidog تلقائيًا استجابة audio/wav ويقوم بتشغيل مشغل صوتي مدمج يمكنك الاستماع إلى الكلام المُولد مباشرةً في الواجهة، دون كتابة سطر واحد من رمز العميل.

استنساخ الصوت باستخدام Fish Audio S2 API

رفع صوت مرجعي إلى Fish Audio S2 API عبر Apidog

تدعم Fish Audio S2 API استنساخ الصوت بدون تدريب مسبق من خلال حقل references في طلب TTS. تقوم بتمرير مقطع صوتي مشفر بتقنية base64 مع نصه، ويقوم النموذج باستنساخ هذا الصوت للإخراج.

أولاً، قم بتحميل مرجع مسمى باستخدام POST /v1/references/add:

{
  "id": "نسخة صوتي",
  "text": "هذا هو النص المرجعي الذي يطابق الصوت.",
  "audio": "<base64-encoded-wav-bytes>"
}

في Apidog، استخدم نوع الجسم ثنائي (Binary) لتحميل ملف الصوت مباشرةً، أو قم بالتبديل إلى بيانات النموذج (Form Data) لتمرير حقلي الملف والنص معًا. تُرجع Fish Audio S2 API ما يلي:

{
  "success": true,
  "message": "تمت إضافة المرجع بنجاح",
  "reference_id": "نسخة صوتي"
}

الآن، ارجع إليه في مكالمات TTS الخاصة بك باستخدام reference_id:

{
  "text": "ستُقال هذه الجملة بالصوت المستنسخ.",
  "reference_id": "نسخة صوتي",
  "format": "mp3"
}

تتيح لك لوحة إدارة المراجع في Apidog (تحت مجموعات Collections) حفظ هذا الطلب كقالب قابل لإعادة الاستخدام، بحيث يمكنك تبديل الأصوات ببساطة عن طريق تغيير قيمة reference_id، وهو مفيد عند اختبار أصوات مستنسخة متعددة مقابل نفس النص.

كيفية اختبار وحدة تكاملات Fish Audio S2 API

لماذا تهم اختبارات الوحدة لتكاملات Fish Audio S2 API

يحتوي تكامل Fish Audio S2 API على عدة أنماط فشل غير مرئية بدون اختبارات وحدة آلية: معرف مرجعي لم يعد موجودًا، قيمة temperature خارج النطاق، استجابة تدفق يتم استهلاكها بشكل غير صحيح، أو عدم تطابق في تنسيق الصوت. تلتقط اختبارات الوحدة هذه الأخطاء قبل أن تصل إلى المستخدمين.

كتابة اختبارات الوحدة لـ Fish Audio S2 API باستخدام بايثون

فيما يلي مجموعة اختبارات وحدة بايثون تغطي تدفقات Fish Audio S2 API الأساسية باستخدام pytest و httpx:

import pytest
import httpx
import base64

BASE_URL = "http://127.0.0.1:8080"
API_KEY = "YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


class TestFishAudioS2API:
    """Unit tests for Fish Audio S2 API endpoints."""

    def test_health_check(self):
        """Unit test: Fish Audio S2 API health endpoint returns ok."""
        response = httpx.get(f"{BASE_URL}/v1/health", headers=HEADERS)
        assert response.status_code == 200
        assert response.json()["status"] == "ok"

    def test_tts_basic_request(self):
        """Unit test: Fish Audio S2 API TTS returns binary audio."""
        payload = {
            "text": "اختبار وحدة: التحقق من إخراج Fish Audio S2 API TTS.",
            "format": "wav",
            "seed": 42,  # Fixed seed for deterministic unit test output
        }
        response = httpx.post(
            f"{BASE_URL}/v1/tts",
            json=payload,
            headers=HEADERS,
            timeout=60,
        )
        assert response.status_code == 200
        assert response.headers["content-type"] == "audio/wav"
        assert len(response.content) > 1000  # Minimum viable audio size

    def test_tts_invalid_temperature_raises_error(self):
        """Unit test: Fish Audio S2 API rejects out-of-range temperature."""
        payload = {"text": "اختبار", "temperature": 99.0}
        response = httpx.post(
            f"{BASE_URL}/v1/tts",
            json=payload,
            headers=HEADERS,
            timeout=30,
        )
        assert response.status_code == 422  # Validation error expected

    def test_reference_add_and_list(self):
        """Unit test: Fish Audio S2 API reference management endpoints."""
        # Add a reference
        with open("test_reference.wav", "rb") as f:
            audio_b64 = base64.b64encode(f.read()).decode()

        add_response = httpx.post(
            f"{BASE_URL}/v1/references/add",
            json={
                "id": "صوت-اختبار-وحدة",
                "text": "هذا هو صوت مرجعي لاختبار الوحدة.",
                "audio": audio_b64,
            },
            headers=HEADERS,
        )
        assert add_response.json()["success"] is True

        # Verify reference appears in list
        list_response = httpx.get(
            f"{BASE_URL}/v1/references/list", headers=HEADERS
        )
        assert "صوت-اختبار-وحدة" in list_response.json()["reference_ids"]

        # Cleanup: delete reference after unit test
        httpx.request(
            "DELETE",
            f"{BASE_URL}/v1/references/delete",
            json={"reference_id": "صوت-اختبار-وحدة"},
            headers=HEADERS,
        )

قم بتشغيل مجموعة اختبارات الوحدة باستخدام:

pytest test_fish_audio_s2_api.py -v

تشغيل اختبارات وحدة Fish Audio S2 API باستخدام Apidog

بالإضافة إلى اختبارات وحدة بايثون، يحتوي Apidog على ميزة سيناريوهات الاختبار المدمجة (الاختبار الآلي) التي تقوم بتشغيل نفس فحوصات Fish Audio S2 API بدون بيئة بايثون محلية. في Apidog:

1. افتح مجموعة Fish Audio S2 API الخاصة بك.
2. انقر على سيناريوهات الاختبار (Test Scenarios) ← سيناريو جديد (New Scenario).
3. أضف الطلبات: فحص الصحة ← طلب TTS ← إضافة مرجع ← قائمة المراجع.
4. في علامة التبويب التأكيدات (Assertions) لطلب TTS، أضف:

• حالة الاستجابة = 200
• ترويسة الاستجابة content-type تحتوي على audio
• زمن الاستجابة < 30000ms

1. انقر على تشغيل (Run) لتنفيذ تسلسل اختبار الوحدة الكامل.

يُنشئ Apidog تقرير نجاح/فشل لكل تأكيد من Fish Audio S2 API، مع توقيتات الاستجابة وعروض الفروقات. يمكنك تصدير هذا التقرير أو جدولته للتشغيل عند تشغيل CI، مما يجعل Apidog هو مشغل اختبار الوحدة لـ Fish Audio S2 API الخاص بك دون كتابة أي قالب إطار عمل للاختبار.

ميزات Fish Audio S2 API المتقدمة

بث الصوت من Fish Audio S2 API

لتطبيقات التشغيل في الوقت الفعلي، تدعم Fish Audio S2 API البث المجزأ. اضبط "streaming": true في نص طلبك:

import httpx

with httpx.stream(
    "POST",
    "http://127.0.0.1:8080/v1/tts",
    json={
        "text": "بث الصوت من Fish Audio S2 API في الوقت الفعلي.",
        "format": "wav",
        "streaming": True,
    },
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=None,
) as response:
    with open("streamed_output.wav", "wb") as audio_file:
        for chunk in response.iter_bytes(chunk_size=4096):
            audio_file.write(chunk)

تبدأ Fish Audio S2 API بإرجاع بايتات الصوت قبل اكتمال التوليف بالكامل، حيث يكون الوقت اللازم لأول صوت حوالي 100 مللي ثانية. وهذا يجعلها قابلة للاستخدام لتطبيقات الصوت المباشر حيث يتوقع المستخدم استجابة فورية.

التحكم في المشاعر داخل النص عبر Fish Audio S2 API

تمرر Fish Audio S2 API علامات المشاعر باللغة الطبيعية مباشرة في حقل text:

{
  "text": "[همسات] السر مخبأ هنا. [سعيد جداً] لقد وجدته!",
  "format": "wav"
}

لا يلزم أي معلمة خاصة، فالنموذج يفسر العلامات الموضوعة بين قوسين كتعليمات نبرة. أمثلة على العلامات الصالحة من مصدر Fish Speech: [ضحك]، [سعال]، [رفع طبقة الصوت]، [نبرة بث احترافية]، [همس بصوت خافت].

الخلاصة

تُقدم Fish Audio S2 API محركًا لتحويل النص إلى كلام (TTS) بجودة إنتاجية حقيقية عبر واجهة REST نظيفة. من التوليف الأساسي إلى استنساخ الصوت بدون تدريب مسبق والبث في الوقت الفعلي، تغطي نقاط النهاية الست المجموعة الكاملة من مهام سير عمل توليد الصوت التي يحتاجها المطور. مفاتيح التكامل الموثوق هي: تعيين معلمات العينات الصحيحة (temperature، top_p، repetition_penalty)، وإدارة دورة حياة الصوت المرجعي بشكل صحيح، والحفاظ على مجموعة اختبارات وحدة تتحقق من عقد كل نقطة نهاية.

يُقلل Apidog منحنى التعلم بشكل كبير. استخدمه لإرسال أول طلب Fish Audio S2 API في أقل من دقيقتين، والاستماع إلى استجابات الصوت الثنائية مباشرةً، وتوليد رمز عميل قابل للنسخ واللصق، وتشغيل اختبارات وحدة آلية مقابل كل نقطة نهاية Fish Audio S2 API دون الحاجة إلى تكوين إطار عمل للاختبار. عندما تكون مستعدًا لمشاركة مواصفات API مع فريقك أو توثيق تكامل Fish Audio S2 API لأصحاب المصلحة، فإن وثائق Apidog التي تُنشأ تلقائيًا تحافظ على كل شيء متزامنًا.

قم بتنزيل Apidog مجانًا واستورد مجموعة Fish Audio S2 API للبدء في الاختبار اليوم.

زر

الأسئلة الشائعة

ما هي Fish Audio S2 API؟ تُعد Fish Audio S2 API واجهة REST لـ Fish Speech S2-Pro، وهو نموذج لتحويل النص إلى كلام (text-to-speech) بـ 4 مليارات معلمة تم تدريبه على 10 ملايين ساعة من الصوت. تدعم استنساخ الصوت، والبث المباشر، والتحكم في المشاعر، وأكثر من 50 لغة عبر نقاط نهاية HTTP تحت /v1/.

كيف أقوم بالمصادقة مع Fish Audio S2 API؟ أرسل رمز Bearer في ترويسة كل طلب: Authorization: Bearer YOUR_API_KEY. يتم تكوين مفتاح API عند بدء تشغيل الخادم عبر علامة --api-key. يتيح لك Apidog تخزين هذا الرمز المميز على مستوى البيئة بحيث ينطبق تلقائيًا على جميع طلبات Fish Audio S2 API.

هل يمكنني اختبار وحدة تكاملات Fish Audio S2 API بدون كتابة رمز؟ نعم. تتيح لك ميزة سيناريوهات الاختبار في Apidog بناء وتشغيل اختبارات وحدة مقابل أي نقطة نهاية Fish Audio S2 API من خلال واجهة بصرية. تقوم بتعريف التأكيدات (رمز الحالة، وقت الاستجابة، قيم الترويسة) ويقوم Apidog بتنفيذها عند الطلب أو وفقًا لجدول CI - لا يلزم إعداد إطار عمل للاختبار.

ما هي تنسيقات الصوت التي تدعمها Fish Audio S2 API؟ تُرجع Fish Audio S2 API الصوت بتنسيقات WAV أو MP3 أو PCM. حدد التنسيق باستخدام حقل "format" في نص طلب TTS الخاص بك. WAV هو الافتراضي.

كيف يعمل استنساخ الصوت في Fish Audio S2 API؟ قم بتحميل مقطع صوتي مرجعي يتراوح طوله بين 10 و 30 ثانية ونصه إلى POST /v1/references/add. ثم مرر معرف المرجع إلى أي طلب TTS عبر "reference_id". تقوم Fish Audio S2 API باستنساخ هذا الصوت دون أي ضبط دقيق أو تدريب إضافي للنموذج.

ما هو عامل الوقت الفعلي لـ Fish Audio S2 API؟ على NVIDIA H200 واحد، تحقق Fish Audio S2 API عامل RTF (عامل الوقت الفعلي) يبلغ 0.195 مع تمكين البث، مما يعني أنها تُولد حوالي 5 ثوانٍ من الصوت لكل ثانية من الحساب. يبلغ الوقت اللازم لأول صوت حوالي 100 مللي ثانية.

كيف أقوم باختبار استجابات Fish Audio S2 API في Apidog؟ عندما تُرجع Fish Audio S2 API صوتًا ثنائيًا، يقوم Apidog تلقائيًا بتشغيل مشغل صوتي مدمج. لست بحاجة إلى حفظ الملف محليًا للتحقق من الإخراج، يمكنك الاستماع، والتحقق من ترويسات الاستجابة، وإضافة التأكيدات، كل ذلك من نفس لوحة طلب Apidog.