Comment Utiliser l'API Fish Audio S2: Guide Complet avec Apidog

L'API Fish Audio S2 est une API REST de synthèse vocale de qualité production, alimentée par un modèle de 4 milliards de paramètres entraîné sur 10 millions d'heures d'audio. Elle prend en charge le clonage de voix, le streaming et plus de 50 langues. Pour utiliser l'API Fish Audio S2 efficacement, notamment pour envoyer des requêtes, gérer les références et exécuter des tests unitaires, Apidog est le moyen le plus rapide d'explorer, de documenter et de valider chaque point d'accès.

Introduction

La voix générée par l'IA a franchi un seuil. Les modèles TTS modernes ne sonnent plus comme des robots ; ils chuchotent, rient et modulent leur ton au milieu d'une phrase. L'API Fish Audio S2 se trouve à la pointe de cette évolution : un modèle de 4 milliards de paramètres entraîné sur plus de 10 millions d'heures d'audio multilingue, capable de produire une parole indiscernable d'un enregistrement humain.

Que vous construisiez un outil d'automatisation de podcasts, un assistant vocal interactif ou un pipeline de doublage en temps réel, l'intégration de l'API Fish Audio S2 dans votre architecture nécessite plus qu'une simple requête POST. Vous devez comprendre l'authentification, la gestion des références audio, le comportement de streaming et, de manière critique, comment écrire des tests unitaires fiables afin que votre intégration ne tombe pas en panne silencieusement en production.

Qu'est-ce que l'API Fish Audio S2 ?

L'API Fish Audio S2 est l'interface HTTP de Fish Speech S2-Pro, un système TTS open-source construit autour d'une architecture Dual-Autoregressive (Dual-AR). Le modèle sépare la génération sémantique (4 milliards de paramètres, AR lente le long de l'axe temporel) de la génération de codebooks résiduels (400 millions de paramètres, AR rapide le long de l'axe de profondeur), permettant une synthèse de haute qualité avec un facteur temps réel de 0,195 sur une seule NVIDIA H200.

Principales capacités de l'API Fish Audio S2 :

L'URL de base de l'API Fish Audio S2 après déploiement local est http://127.0.0.1:8080. Tous les points d'accès se trouvent sous l'espace de noms /v1/.

Démarrer avec l'API Fish Audio S2 et Apidog

Prérequis pour l'API Fish Audio S2

Avant d'effectuer votre premier appel à l'API Fish Audio S2, vous avez besoin de deux éléments en cours d'exécution : un serveur Fish Speech S2-Pro déployé et un client API capable de gérer les réponses audio binaires.

Démarrez le serveur API Fish Audio S2 :

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

L'indicateur --compile active l'optimisation torch.compile, ce qui réduit la latence d'inférence d'environ 10 fois, mais ajoute un coût d'initialisation unique lors du premier lancement. L'indicateur --half active le FP16 pour une utilisation réduite de la mémoire GPU.

Une fois le serveur démarré, vérifiez-le avec un contrôle de santé :

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

Configuration de l'API Fish Audio S2 dans Apidog

Téléchargez Apidog gratuitement et créez un nouveau projet HTTP. Ajoutez l'URL de base http://127.0.0.1:8080 sous Environnements. Ensuite, définissez un en-tête global :

Authorization: Bearer YOUR_API_KEY

Apidog stocke cela au niveau de l'environnement, de sorte que chaque requête API Fish Audio S2 que vous envoyez hérite automatiquement du jeton, sans collage manuel d'en-tête par requête. Cela est particulièrement utile lorsque vous avez plusieurs environnements API Fish Audio S2 (développement local, staging, production) entre lesquels basculer.

Effectuer votre première requête API Fish Audio S2 dans Apidog

Test du point d'accès de synthèse vocale de l'API Fish Audio S2

Le point d'accès principal de l'API Fish Audio S2 est POST /v1/tts. Dans Apidog, créez une nouvelle requête avec cette URL, définissez la méthode sur POST et utilisez le corps JSON suivant :

{
  "text": "Hello! This is a test of the Fish Audio S2 API.",
  "format": "wav",
  "streaming": false,
  "temperature": 0.8,
  "top_p": 0.8,
  "repetition_penalty": 1.1,
  "max_new_tokens": 1024
}

Schéma complet de la requête TTS de l'API Fish Audio S2 :

Cliquez sur Envoyer dans Apidog. L'API Fish Audio S2 renvoie des octets audio bruts. Apidog détecte automatiquement la réponse audio/wav et affiche un lecteur audio intégré, vous permettant d'écouter la parole générée directement dans l'interface, sans écrire une seule ligne de code client.

Clonage vocal avec l'API Fish Audio S2

Téléchargement d'un audio de référence vers l'API Fish Audio S2 via Apidog

L'API Fish Audio S2 prend en charge le clonage vocal à "zero-shot" via le champ references dans la requête TTS. Vous transmettez un clip audio encodé en base64 avec sa transcription, et le modèle clone cette voix pour la sortie.

Tout d'abord, téléchargez une référence nommée en utilisant POST /v1/references/add :

{
  "id": "my-voice-clone",
  "text": "This is the reference transcription matching the audio.",
  "audio": "<base64-encoded-wav-bytes>"
}

Dans Apidog, utilisez le type de corps Binaire pour télécharger directement le fichier audio, ou passez à Données de formulaire pour transmettre le fichier et les champs de texte ensemble. L'API Fish Audio S2 renvoie :

{
  "success": true,
  "message": "Reference added successfully",
  "reference_id": "my-voice-clone"
}

Référencez-le maintenant dans vos appels TTS en utilisant reference_id :

{
  "text": "This sentence will be spoken in the cloned voice.",
  "reference_id": "my-voice-clone",
  "format": "mp3"
}

Le panneau Gestion des Références d'Apidog (sous Collections) vous permet d'enregistrer cette requête comme un modèle réutilisable, afin que vous puissiez changer de voix en modifiant simplement la valeur reference_id, ce qui est utile lors du test de plusieurs voix clonées avec le même script.

Comment tester les intégrations de l'API Fish Audio S2 ?

Pourquoi les tests unitaires sont importants pour l'API Fish Audio S2

Une intégration de l'API Fish Audio S2 présente plusieurs modes de défaillance invisibles sans tests unitaires automatisés : un ID de référence qui n'existe plus, une valeur de temperature hors de portée, une réponse de streaming consommée incorrectement, ou une incompatibilité de format audio. Les tests unitaires détectent ces régressions avant qu'elles n'atteignent les utilisateurs.

Écrire des tests unitaires pour l'API Fish Audio S2 avec Python

Voici une suite de tests unitaires Python couvrant les flux principaux de l'API Fish Audio S2 à l'aide de pytest et 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": "Unit test: verifying Fish Audio S2 API TTS output.",
            "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": "test", "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": "unit-test-voice",
                "text": "This is a unit test reference audio.",
                "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 "unit-test-voice" in list_response.json()["reference_ids"]

        # Cleanup: delete reference after unit test
        httpx.request(
            "DELETE",
            f"{BASE_URL}/v1/references/delete",
            json={"reference_id": "unit-test-voice"},
            headers=HEADERS,
        )

Exécutez la suite de tests unitaires avec :

pytest test_fish_audio_s2_api.py -v

Exécuter les tests unitaires de l'API Fish Audio S2 avec Apidog

Au-delà des tests unitaires Python, Apidog dispose d'une fonctionnalité intégrée de Scénarios de test (tests automatisés) qui exécute les mêmes vérifications de l'API Fish Audio S2 sans environnement Python local. Dans Apidog :

1. Ouvrez votre collection d'API Fish Audio S2
2. Cliquez sur Scénarios de test → Nouveau scénario
3. Ajoutez des requêtes : contrôle de santé → requête TTS → ajout de référence → liste de références
4. Dans l'onglet Assertions pour la requête TTS, ajoutez :

• Statut de la réponse = 200
• L'en-tête de réponse content-type contient audio
• Temps de réponse < 30000ms

1. Cliquez sur Exécuter pour exécuter la séquence complète des tests unitaires

Apidog génère un rapport de réussite/échec pour chaque assertion de l'API Fish Audio S2, avec les temps de réponse et les vues de différence. Vous pouvez exporter ce rapport ou le programmer pour qu'il s'exécute sur un déclencheur d'intégration continue, faisant d'Apidog l'exécuteur de tests unitaires pour votre API Fish Audio S2 sans écrire de code passe-partout de framework de test.

Fonctionnalités avancées de l'API Fish Audio S2

Streaming audio depuis l'API Fish Audio S2

Pour les applications de lecture en temps réel, l'API Fish Audio S2 prend en charge le streaming par blocs. Définissez "streaming": true dans le corps de votre requête :

import httpx

with httpx.stream(
    "POST",
    "http://127.0.0.1:8080/v1/tts",
    json={
        "text": "Streaming audio from the Fish Audio S2 API in real time.",
        "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)

L'API Fish Audio S2 commence à renvoyer des octets audio avant que la synthèse complète ne soit terminée ; le temps de la première sortie audio est d'environ 100 ms. Cela la rend viable pour les applications vocales en direct où un utilisateur s'attend à un retour immédiat.

Contrôle des émotions en ligne via l'API Fish Audio S2

L'API Fish Audio S2 transmet des balises d'émotion en langage naturel directement dans le champ text :

{
  "text": "[whispers] The secret is hidden here. [super happy] I found it!",
  "format": "wav"
}

Aucun paramètre spécial n'est nécessaire ; le modèle interprète les balises entre crochets comme des instructions de prosodie. Exemples de balises valides tirées de la source Fish Speech : [laugh], [cough], [pitch up], [professional broadcast tone], [whisper in small voice].

Conclusion

L'API Fish Audio S2 expose un moteur TTS véritablement de qualité production via une interface REST propre. De la synthèse de base au clonage vocal à "zero-shot" et au streaming en temps réel, les six points d'accès couvrent toute la gamme des flux de travail de génération vocale dont un développeur a besoin. Les clés d'une intégration fiable sont : la définition des bons paramètres d'échantillonnage (temperature, top_p, repetition_penalty), la gestion correcte du cycle de vie de l'audio de référence, et la maintenance d'une suite de tests unitaires qui valide le contrat de chaque point d'accès.

Apidog réduit considérablement la courbe d'apprentissage. Utilisez-le pour envoyer votre première requête à l'API Fish Audio S2 en moins de deux minutes, écouter les réponses audio binaires en ligne, générer du code client à copier-coller et exécuter des tests unitaires automatisés sur chaque point d'accès de l'API Fish Audio S2 sans configurer de framework de test. Lorsque vous êtes prêt à partager la spécification de l'API avec votre équipe ou à documenter l'intégration de l'API Fish Audio S2 pour les parties prenantes, la documentation auto-générée d'Apidog maintient tout synchronisé.

Téléchargez Apidog gratuitement et importez la collection de l'API Fish Audio S2 pour commencer à tester dès aujourd'hui.

FAQ

Qu'est-ce que l'API Fish Audio S2 ? L'API Fish Audio S2 est l'interface REST de Fish Speech S2-Pro, un modèle de synthèse vocale de 4 milliards de paramètres entraîné sur 10 millions d'heures d'audio. Elle prend en charge le clonage de voix, le streaming, le contrôle des émotions et plus de 50 langues via des points d'accès HTTP sous /v1/.

Comment s'authentifier avec l'API Fish Audio S2 ? Envoyez un token Bearer dans l'en-tête de chaque requête : Authorization: Bearer YOUR_API_KEY. La clé API est configurée au démarrage du serveur via l'indicateur --api-key. Apidog vous permet de stocker ce token au niveau de l'environnement afin qu'il s'applique automatiquement à toutes les requêtes API Fish Audio S2.

Puis-je tester les intégrations de l'API Fish Audio S2 sans écrire de code ? Oui. La fonction Scénarios de test d'Apidog vous permet de créer et d'exécuter des tests unitaires sur n'importe quel point d'accès de l'API Fish Audio S2 via une interface visuelle. Vous définissez des assertions (code de statut, temps de réponse, valeurs d'en-tête) et Apidog les exécute à la demande ou selon un calendrier d'intégration continue, sans aucune configuration de framework de test.

Quels formats audio l'API Fish Audio S2 prend-elle en charge ? L'API Fish Audio S2 renvoie l'audio aux formats WAV, MP3 ou PCM. Spécifiez le format avec le champ "format" dans le corps de votre requête TTS. WAV est le format par défaut.

Comment fonctionne le clonage vocal dans l'API Fish Audio S2 ? Téléchargez un clip audio de référence de 10 à 30 secondes et sa transcription vers POST /v1/references/add. Ensuite, transmettez l'ID de référence à toute requête TTS via "reference_id". L'API Fish Audio S2 clone cette voix sans aucun réglage fin ni entraînement de modèle supplémentaire.

Quel est le facteur temps réel de l'API Fish Audio S2 ? Sur une seule NVIDIA H200, l'API Fish Audio S2 atteint un RTF (facteur temps réel) de 0,195 avec le streaming activé, ce qui signifie qu'elle génère environ 5 secondes d'audio par seconde de calcul. Le temps jusqu'au premier audio est d'environ 100 ms.

Comment tester les réponses de l'API Fish Audio S2 dans Apidog ? Lorsque l'API Fish Audio S2 renvoie de l'audio binaire, Apidog affiche automatiquement un lecteur audio intégré. Vous n'avez pas besoin d'enregistrer le fichier localement pour vérifier la sortie ; vous pouvez écouter, vérifier les en-têtes de réponse et ajouter des assertions, le tout depuis le même panneau de requête Apidog.