Cómo Usar la API de Fish Audio S2: Guía Completa con Apidog

La API Fish Audio S2 es una API REST de texto a voz de nivel de producción impulsada por un modelo de 4 mil millones de parámetros entrenado con 10 millones de horas de audio. Soporta clonación de voz, transmisión (streaming) y más de 50 idiomas. Para usar la API Fish Audio S2 de manera eficiente, incluyendo el envío de solicitudes, la gestión de referencias y la ejecución de pruebas unitarias, Apidog es la forma más rápida de explorar, documentar y validar cada endpoint.

Introducción

La voz generada por IA ha cruzado un umbral. Los modelos TTS modernos ya no suenan como robots, susurran, ríen y cambian el tono a mitad de frase. La API Fish Audio S2 se encuentra a la vanguardia de este cambio: un modelo de 4 mil millones de parámetros entrenado con más de 10 millones de horas de audio multilingüe, capaz de producir un discurso indistinguible de una grabación humana.

Ya sea que esté construyendo una herramienta de automatización de podcasts, un asistente de voz interactivo o un sistema de doblaje en tiempo real, integrar la API Fish Audio S2 en su stack requiere más que una simple solicitud POST. Necesita comprender la autenticación, la gestión de audio de referencia, el comportamiento de la transmisión (streaming) y, fundamentalmente, cómo escribir pruebas unitarias fiables para que su integración no falle silenciosamente en producción.

¿Qué es la API Fish Audio S2?

La API Fish Audio S2 es la interfaz HTTP de Fish Speech S2-Pro, un sistema TTS de código abierto construido alrededor de una arquitectura Dual-Autoregresiva (Dual-AR). El modelo separa la generación semántica (4 mil millones de parámetros, AR lenta a lo largo del eje del tiempo) de la generación de codebook residual (400 millones de parámetros, AR rápida a lo largo del eje de profundidad), lo que permite una síntesis de alta calidad con un factor en tiempo real de 0.195 en una sola NVIDIA H200.

Capacidades clave de la API Fish Audio S2:

La URL base de la API Fish Audio S2 después de la implementación local es http://127.0.0.1:8080. Todos los endpoints se encuentran bajo el espacio de nombres /v1/.

Primeros pasos con la API Fish Audio S2 y Apidog

Requisitos previos para la API Fish Audio S2

Antes de realizar su primera llamada a la API Fish Audio S2, necesita que se ejecuten dos cosas: un servidor Fish Speech S2-Pro desplegado y un cliente API capaz de manejar respuestas de audio binarias.

Inicie el servidor de la 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

El flag --compile activa la optimización torch.compile, lo que reduce la latencia de inferencia aproximadamente 10 veces, pero añade un coste de calentamiento único en el primer lanzamiento. El flag --half habilita FP16 para reducir el uso de memoria de la GPU.

Una vez que el servidor esté activo, verifíquelo con una comprobación de estado:

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

Configuración de la API Fish Audio S2 en Apidog

Descargue Apidog gratis y cree un nuevo proyecto HTTP. Añada la URL base http://127.0.0.1:8080 en Entornos. Luego, establezca un encabezado global:

Authorization: Bearer YOUR_API_KEY

Apidog almacena esto a nivel de entorno, por lo que cada solicitud de la API Fish Audio S2 que envíe heredará el token automáticamente, sin necesidad de pegar el encabezado manualmente en cada solicitud. Esto es especialmente útil cuando tiene múltiples entornos de la API Fish Audio S2 (desarrollo local, staging, producción) entre los que cambiar.

Realizando su primera solicitud a la API Fish Audio S2 en Apidog

Probando el endpoint de texto a voz de la API Fish Audio S2

El endpoint principal de la API Fish Audio S2 es POST /v1/tts. En Apidog, cree una nueva solicitud con esta URL, establezca el método en POST y use el siguiente cuerpo JSON:

{
  "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
}

Esquema completo de la solicitud TTS de la API Fish Audio S2:

Haga clic en Enviar en Apidog. La API Fish Audio S2 devuelve bytes de audio sin procesar. Apidog detecta automáticamente la respuesta audio/wav y muestra un reproductor de audio en línea para que pueda escuchar el discurso generado directamente en la interfaz, sin escribir una sola línea de código de cliente.

Clonación de voz con la API Fish Audio S2

Subiendo un audio de referencia a la API Fish Audio S2 a través de Apidog

La API Fish Audio S2 soporta la clonación de voz de un solo intento (zero-shot) a través del campo references en la solicitud TTS. Se pasa un clip de audio codificado en base64 junto con su transcripción, y el modelo clona esa voz para la salida.

Primero, suba una referencia con nombre usando POST /v1/references/add:

{
  "id": "my-voice-clone",
  "text": "Esta es la transcripción de referencia que coincide con el audio.",
  "audio": "<base64-encoded-wav-bytes>"
}

En Apidog, use el tipo de cuerpo Binary para subir el archivo de audio directamente, o cambie a Form Data para pasar el archivo y los campos de texto juntos. La API Fish Audio S2 devuelve:

{
  "success": true,
  "message": "Referencia añadida exitosamente",
  "reference_id": "my-voice-clone"
}

Ahora, haga referencia a ella en sus llamadas TTS usando reference_id:

{
  "text": "Esta frase será pronunciada con la voz clonada.",
  "reference_id": "my-voice-clone",
  "format": "mp3"
}

El panel de Gestión de referencias de Apidog (en Colecciones) le permite guardar esta solicitud como una plantilla reutilizable, para que pueda cambiar de voz simplemente cambiando el valor de reference_id, lo cual es útil al probar múltiples voces clonadas con el mismo script.

Cómo realizar pruebas unitarias de integraciones de la API Fish Audio S2

Por qué las pruebas unitarias son importantes para la API Fish Audio S2

Una integración de la API Fish Audio S2 tiene varios modos de fallo que son invisibles sin pruebas unitarias automatizadas: un ID de referencia que ya no existe, un valor de temperature fuera de rango, una respuesta de streaming que se consume incorrectamente o una falta de coincidencia en el formato de audio. Las pruebas unitarias detectan estas regresiones antes de que lleguen a los usuarios.

Escribiendo pruebas unitarias para la API Fish Audio S2 con Python

Aquí hay una suite de pruebas unitarias en Python que cubre los flujos principales de la API Fish Audio S2 usando pytest y 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,
        )

Ejecute la suite de pruebas unitarias con:

pytest test_fish_audio_s2_api.py -v

Ejecutando pruebas unitarias de la API Fish Audio S2 con Apidog

Más allá de las pruebas unitarias de Python, Apidog tiene una función incorporada de Escenarios de prueba (pruebas automatizadas) que ejecuta las mismas comprobaciones de la API Fish Audio S2 sin un entorno Python local. En Apidog:

1. Abra su colección de la API Fish Audio S2
2. Haga clic en Escenarios de prueba → Nuevo escenario
3. Añada solicitudes: comprobación de estado → solicitud TTS → añadir referencia → lista de referencias
4. En la pestaña Asertos para la solicitud TTS, añada:

• Estado de la respuesta = 200
• El encabezado de respuesta content-type contiene audio
• Tiempo de respuesta < 30000ms

1. Haga clic en Ejecutar para ejecutar la secuencia completa de pruebas unitarias

Apidog genera un informe de aprobación/fallo para cada aserción de la API Fish Audio S2, con tiempos de respuesta y vistas de diferencias. Puede exportar este informe o programarlo para que se ejecute con un activador de CI, convirtiendo a Apidog en el ejecutor de pruebas unitarias para su API Fish Audio S2 sin necesidad de escribir ningún código repetitivo de framework de pruebas.

Características avanzadas de la API Fish Audio S2

Transmisión (Streaming) de audio desde la API Fish Audio S2

Para aplicaciones de reproducción en tiempo real, la API Fish Audio S2 soporta transmisión por bloques. Establezca "streaming": true en el cuerpo de su solicitud:

import httpx

with httpx.stream(
    "POST",
    "http://127.0.0.1:8080/v1/tts",
    json={
        "text": "Streaming de audio desde la API Fish Audio S2 en tiempo real.",
        "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)

La API Fish Audio S2 comienza a devolver bytes de audio antes de que la síntesis completa termine; el tiempo hasta el primer audio es aproximadamente de 100 ms. Esto la hace viable para aplicaciones de voz en vivo donde un usuario espera una respuesta inmediata.

Control de emoción en línea a través de la API Fish Audio S2

La API Fish Audio S2 pasa etiquetas de emoción en lenguaje natural directamente en el campo text:

{
  "text": "[whispers] El secreto está escondido aquí. [super happy] ¡Lo encontré!",
  "format": "wav"
}

No se necesita ningún parámetro especial; el modelo interpreta las etiquetas entre corchetes como instrucciones de prosodia. Ejemplos de etiquetas válidas de la fuente de Fish Speech: [laugh] (risa), [cough] (tos), [pitch up] (subir tono), [professional broadcast tone] (tono de locutor profesional), [whisper in small voice] (susurrar con voz pequeña).

Conclusión

La API Fish Audio S2 expone un motor TTS genuinamente de grado de producción a través de una interfaz REST limpia. Desde la síntesis básica hasta la clonación de voz de un solo intento (zero-shot) y la transmisión en tiempo real, los seis endpoints cubren toda la gama de flujos de trabajo de generación de voz que un desarrollador necesita. Las claves para una integración fiable son: establecer los parámetros de muestreo correctos (temperature, top_p, repetition_penalty), gestionar correctamente el ciclo de vida del audio de referencia y mantener una suite de pruebas unitarias que valide el contrato de cada endpoint.

Apidog comprime la curva de aprendizaje drásticamente. Úselo para enviar su primera solicitud a la API Fish Audio S2 en menos de dos minutos, escuchar respuestas de audio binarias en línea, generar código de cliente para copiar y pegar, y ejecutar pruebas unitarias automatizadas contra cada endpoint de la API Fish Audio S2 sin configurar un framework de pruebas. Cuando esté listo para compartir la especificación de la API con su equipo o documentar la integración de la API Fish Audio S2 para las partes interesadas, la documentación autogenerada de Apidog mantiene todo sincronizado.

Descargue Apidog gratis e importe la colección de la API Fish Audio S2 para comenzar a probar hoy mismo.

Preguntas frecuentes

¿Qué es la API Fish Audio S2? La API Fish Audio S2 es la interfaz REST de Fish Speech S2-Pro, un modelo de texto a voz de 4 mil millones de parámetros entrenado con 10 millones de horas de audio. Soporta clonación de voz, transmisión, control de emociones y más de 50 idiomas a través de endpoints HTTP bajo /v1/.

¿Cómo me autentico con la API Fish Audio S2? Envíe un token Bearer en cada encabezado de solicitud: Authorization: Bearer YOUR_API_KEY. La clave API se configura al iniciar el servidor a través del flag --api-key. Apidog le permite almacenar este token a nivel de entorno para que se aplique automáticamente a todas las solicitudes de la API Fish Audio S2.

¿Puedo realizar pruebas unitarias de integraciones de la API Fish Audio S2 sin escribir código? Sí. La función de Escenarios de prueba de Apidog le permite construir y ejecutar pruebas unitarias contra cualquier endpoint de la API Fish Audio S2 a través de una interfaz visual. Usted define las aserciones (código de estado, tiempo de respuesta, valores de encabezado) y Apidog las ejecuta bajo demanda o en una programación CI, sin necesidad de configurar un framework de pruebas.

¿Qué formatos de audio soporta la API Fish Audio S2? La API Fish Audio S2 devuelve audio en formatos WAV, MP3 o PCM. Especifique el formato con el campo "format" en el cuerpo de su solicitud TTS. WAV es el predeterminado.

¿Cómo funciona la clonación de voz en la API Fish Audio S2? Suba un clip de audio de referencia de 10 a 30 segundos y su transcripción a POST /v1/references/add. Luego, pase el ID de referencia a cualquier solicitud TTS a través de "reference_id". La API Fish Audio S2 clona esa voz sin necesidad de ajuste fino ni entrenamiento adicional del modelo.

¿Cuál es el factor en tiempo real de la API Fish Audio S2? En una única NVIDIA H200, la API Fish Audio S2 logra un RTF (factor en tiempo real) de 0.195 con la transmisión habilitada, lo que significa que genera aproximadamente 5 segundos de audio por cada segundo de cómputo. El tiempo hasta el primer audio es de aproximadamente 100 ms.

¿Cómo pruebo las respuestas de la API Fish Audio S2 en Apidog? Cuando la API Fish Audio S2 devuelve audio binario, Apidog renderiza automáticamente un reproductor de audio en línea. No necesita guardar el archivo localmente para verificar la salida; puede escuchar, verificar los encabezados de respuesta y añadir aserciones, todo desde el mismo panel de solicitud de Apidog.