Fish TTS API Integración

Esta interfaz se basa en la API oficial de TTS de Fish Audio, con diferencias únicamente en el método de autenticación (uso del token de esta plataforma) y la devolución asíncrona (extensión de callback_url), la estructura del cuerpo de la solicitud es la misma que la del upstream. La dirección es POST https://api.acedata.cloud/fish/tts.

Proceso de Solicitud

Para usar la API de Fish TTS, primero dirígete a la consola de Ace Data Cloud para obtener tu API Token, guárdalo para uso futuro.

Si aún no has iniciado sesión o registrado, serás redirigido automáticamente a la página de inicio de sesión que te invitará a registrarte e iniciar sesión, y una vez completado, volverás automáticamente a la página actual. Un API Token es suficiente para acceder a todos los servicios de la plataforma, no es necesario solicitar uno por cada servicio. La primera solicitud incluirá un crédito gratuito para que puedas probarlo; si el crédito es insuficiente, puedes recargar el saldo general en la consola.

📘 Documentación completa: Fish TTS API →

Encabezados de Solicitud

Header	Requerido	Descripción
`authorization`	Sí	`Bearer {token}`, donde `{token}` es la clave solicitada en esta plataforma.
`content-type`	Sí	`application/json`.
`accept`	No	`application/json`.
`model`	No	Modelo TTS, puede ser `s1`, `s2-pro` o `s2.1-pro`, por defecto `s2-pro`. `s2.1-pro` es la última generación, `s2-pro` tiene una gran expresividad; `s1` es más estable y menos propenso a desviaciones en textos largos. Los tres tienen el mismo precio.

Campos del Cuerpo de Solicitud

Campo	Tipo	Requerido	Descripción
`text`	string	Sí	Texto a sintetizar, cadena no vacía.
`format`	string	No	Formato de audio de salida, puede ser `mp3` (por defecto), `wav`, `pcm`. Tanto `wav` como `pcm` devuelven contenedores WAV. `opus` no es compatible, si se envía, se devolverá `400`.
`reference_id`	string \| string[]	No	ID de tono de voz clonado (puede ser creado por la API de Modelos de Fish o recuperado en Consulta de Modelos de Fish).
`references`	object[]	No	Muestras de referencia en línea, la estructura es la misma que la del upstream, cada elemento contiene `audio` y `text`. Uno de los dos, `reference_id` o `references`, debe ser proporcionado.
`sample_rate`	integer	No	Tasa de muestreo, comúnmente `16000`, `22050`, `44100`. `format=mp3` por defecto es `44100`.
`mp3_bitrate`	integer	No	Tasa de bits de MP3, puede ser `64`, `128`, `192`. Solo es efectivo si `format=mp3`.
`prosody`	object	No	Cobertura de prosodia, soporta `speed` (velocidad del habla, 1.0 es la velocidad original) y `volume` (ganancia de volumen en dB). Por ejemplo `{"speed":1.2,"volume":0}`.
`chunk_length`	integer	No	Longitud de fragmento del upstream, por defecto es decidida por el upstream.
`temperature`	number	No	Temperatura de muestreo, rango aproximadamente de 0.0 a 1.0.
`top_p`	number	No	Parámetro de muestreo top-p.
`latency`	string	No	`normal` o `balanced`, por defecto este interfaz automáticamente completa con `normal` (si se envía una cadena vacía, el upstream rechazará la solicitud).
`normalize`	boolean	No	Si se debe normalizar el texto.
`callback_url`	string	No	Dirección de devolución asíncrona, ver más abajo en “Devolución asíncrona”. Esta es una extensión en relación a la interfaz oficial.

La nomenclatura de los campos es completamente consistente con el upstream. A excepción de callback_url, los demás campos tienen el mismo significado y valores que se pueden consultar en la documentación oficial de TTS de Fish.

Ejemplo 1: Solicitud Mínima (`text` + `format=mp3`)

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Hola mundo.",
    "format": "mp3"
  }'

Respuesta (medido):

{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/e2ffcc06-18da-4a8c-b9aa-9337d0f9ec1d.mp3"
}

audio_url apunta al CDN de esta plataforma, se puede descargar directamente con GET o reproducir en <audio>. El enlace es de uso prolongado, pero se recomienda mantener una copia en tu propio almacenamiento.

Ejemplo 2: Usando el tono de voz clonado `reference_id`

A continuación, se utiliza un tono de voz en español público de la plataforma Fish (_id se puede recuperar a través de Consulta de Modelos de Fish):

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Hermanos míos, hoy es un buen día.",
    "reference_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
    "format": "mp3"
  }'

Respuesta (medido):

{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/b6f161f2-a100-4818-add2-47694f234659.mp3"
}

Ejemplo 3: Ajustar velocidad / volumen (`prosody`)

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Discurso más rápido con sobrescrituras de prosodia.",
    "prosody": { "speed": 1.2, "volume": 0 },
    "format": "mp3"
  }'

Respuesta (medido):

{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3"
}

speed mayor que 1 acelera, menor que 1 desacelera; volume en dB, 0 significa sin cambio, números positivos son ganancia, negativos son atenuación.

Ejemplo 4: Cambiar modelo + controlar tasa de bits

A través del encabezado HTTP model: s1 se cambia al modelo estable, añadiendo mp3_bitrate: 128 en el cuerpo de la solicitud para controlar la tasa de bits de MP3:

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s1' \
  -d '{
    "text": "alta tasa de bits mp3",
    "format": "mp3",
    "mp3_bitrate": 128
  }'

respuesta (medido):

{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/7e7abf3d-3d72-4c9f-8eb6-8af932d7c96e.mp3"
}

Ejemplo 5: Forma de onda PCM cruda

Para escenarios donde se necesita hacer una concatenación en tiempo real en el navegador, o realizar un procesamiento posterior en el cliente (mezcla, cambio de velocidad), se recomienda usar pcm:

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "hola",
    "format": "pcm",
    "sample_rate": 16000
  }'

respuesta (medido):

{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/64adc04b-c196-4a0f-9070-222ba101ce6c.wav"
}

La extensión del enlace sigue el format de la solicitud: mp3 obtiene .mp3, wav y pcm obtienen .wav (contenedor WAV, PCM de 16 bits).

Callback asíncrono (`callback_url`)

La síntesis de texto largo puede tardar de varios segundos a decenas de segundos, si la conexión se interrumpe, es necesario reintentar. Al enviar callback_url en el cuerpo de la solicitud, la interfaz devolverá inmediatamente {task_id, started_at}, y cuando se complete realmente, el resultado completo se enviará como un JSON POST a esa URL, incluyendo el mismo task_id en el cuerpo de la solicitud.

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Hoy el clima es muy bueno, salgamos a dar un paseo.",
    "format": "mp3",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'

respuesta inmediata (medido):

{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "started_at": 1778462584.742
}

Más tarde, callback_url recibirá algo como:

{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/bd66b8c5-7543-4557-b684-baa72407e336.mp3"
}

También se puede usar Fish Tasks API para obtener resultados activamente por task_id, consulte ese documento para más detalles.

Manejo de errores

400 token_mismatched: Parámetros de solicitud faltantes o no válidos (lo más común es que text esté vacío, o que format tenga un valor diferente a mp3/wav/pcm).
401 invalid_token: El token de autenticación no existe o es inválido.
429 too_many_requests: Se ha activado el límite de velocidad de la cuenta.
500 api_error: Error interno del servidor.

Ejemplo de respuesta de error:

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "la recuperación falló"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Los errores de validación de parámetros incluirán el mensaje de error original de pydantic en el campo message, facilitando la identificación de qué campo es inválido, por ejemplo:

{
  "status": 400,
  "message": "[{\"type\":\"literal_error\",\"loc\":[\"format\"],\"msg\":\"La entrada debe ser 'pcm' o 'mp3'\",\"input\":\"wav\"}]"
}

Conclusión

El costo mínimo para integrar Fish TTS es: en el código que ya llama a api.fish.audio/v1/tts, cambiar la autenticación por el token de esta plataforma y en el cuerpo de la solicitud incluir explícitamente format: "mp3". Para escenarios de texto largo, se recomienda usar callback_url para la devolución asíncrona; para el descubrimiento de reference_id de la clonación de voces, consulte Fish Model Query y Fish Model Get.

Primeros pasos

Chat de IA

Imagen de IA

Video de IA

Audio de IA

Web y datos

CAPTCHA

Identidad

Proxy

Avanzado

Proceso de Solicitud

Encabezados de Solicitud

Campos del Cuerpo de Solicitud

Ejemplo 1: Solicitud Mínima (`text` + `format=mp3`)

Ejemplo 2: Usando el tono de voz clonado `reference_id`

Ejemplo 3: Ajustar velocidad / volumen (`prosody`)

Ejemplo 4: Cambiar modelo + controlar tasa de bits

Ejemplo 5: Forma de onda PCM cruda

Callback asíncrono (`callback_url`)

Manejo de errores

Conclusión

​Proceso de Solicitud

​Encabezados de Solicitud

​Campos del Cuerpo de Solicitud

​Ejemplo 1: Solicitud Mínima (text + format=mp3)

​Ejemplo 2: Usando el tono de voz clonado reference_id

​Ejemplo 3: Ajustar velocidad / volumen (prosody)

​Ejemplo 4: Cambiar modelo + controlar tasa de bits

​Ejemplo 5: Forma de onda PCM cruda

​Callback asíncrono (callback_url)

​Manejo de errores

​Conclusión

Proceso de Solicitud

Encabezados de Solicitud

Campos del Cuerpo de Solicitud

Ejemplo 1: Solicitud Mínima (`text` + `format=mp3`)

Ejemplo 2: Usando el tono de voz clonado `reference_id`

Ejemplo 3: Ajustar velocidad / volumen (`prosody`)

Ejemplo 4: Cambiar modelo + controlar tasa de bits

Ejemplo 5: Forma de onda PCM cruda

Callback asíncrono (`callback_url`)

Manejo de errores

Conclusión