Instrucciones de integración de Fish TTS API

Esta API proporciona conversión de texto a voz, llamadas a voces guardadas y clonación instantánea de voz de un solo uso. La dirección es POST https://api.acedata.cloud/fish/tts.

Proceso de solicitud

Para usar Fish TTS API, primero obtenga su API Token en la consola de Ace Data Cloud y guárdelo como respaldo.

Si aún no ha iniciado sesión o no se ha registrado, será redirigido automáticamente a la página de inicio de sesión para invitarle a registrarse e iniciar sesión; al finalizar, volverá automáticamente a la página actual. Un solo API Token permite llamar a todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio. La primera solicitud incluye crédito gratuito para probar el servicio sin coste; cuando el crédito sea insuficiente, puede recargar saldo general en la consola.

📘 Documentación completa: Fish TTS API →

Encabezados de solicitud

Header	Obligatorio	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`; el valor predeterminado es `s2-pro`. `s2.1-pro` es la generación más reciente, y `s2-pro` tiene gran expresividad; `s1` es más estable y es menos propenso a desviarse con textos largos. Los tres tienen el mismo precio.

Campos del cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
`text`	string	Sí	El texto que se va a sintetizar; una cadena no vacía.
`format`	string	No	Formato de audio de salida; puede ser `mp3` (predeterminado), `wav`, `pcm`. Tanto `wav` como `pcm` devuelven un contenedor WAV. `opus` no es compatible y devolverá directamente `400` si se envía.
`reference_id`	string \| string[]	No	ID del modelo de una voz guardada o pública; puede crearse mediante Fish Model API, o buscarse en Fish Model Query. No puede usarse al mismo tiempo que `references`.
`references`	object[]	No	Clonación instantánea de voz de un solo uso; solo admite una muestra `{audio, text}`: `audio` es una URL pública HTTPS MP3/WAV, y `text` es la transcripción literal precisa del audio. No puede usarse al mismo tiempo que `reference_id`.
`sample_rate`	integer	No	Frecuencia de muestreo; se usan habitualmente `16000`, `22050`, `44100`. El valor predeterminado de `format=mp3` es 44100.
`mp3_bitrate`	integer	No	Tasa de bits de MP3; puede ser `64`, `128`, `192`. Solo tiene efecto con `format=mp3`.
`prosody`	object	No	Anulación de prosodia; admite `speed` (velocidad de 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 ascendente; el valor predeterminado lo determina el servicio ascendente.
`temperature`	number	No	Temperatura de muestreo; rango aproximado de 0.0–1.0.
`top_p`	number	No	Parámetro de muestreo top-p.
`latency`	string	No	`normal` o `balanced`; si se omite, esta API completa automáticamente `normal` (el servicio ascendente rechazará una cadena vacía enviada directamente).
`normalize`	boolean	No	Indica si se normaliza el texto.
`callback_url`	string	No	Dirección de devolución de llamada asíncrona; consulte «Devolución de llamada asíncrona» más abajo. Esta es una extensión respecto a la API oficial.

La clonación de un solo uso solo acepta URL de audio HTTPS; no acepta MessagePack, Base64, URI de datos ni URL con credenciales. Se recomienda que el audio de referencia tenga entre 10 y 270 segundos; Studio utiliza un rango más conservador de 10–60 segundos.

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": "Hello world.",
    "format": "mp3"
  }'

Devuelve (verificado):

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

audio_url apunta al CDN de esta plataforma y puede descargarse directamente mediante GET o reproducirse en <audio>. La respuesta final correcta también devolverá cost en el nivel superior, donde amount son los Credits realmente deducidos en esta ocasión; si hay un descuento de cuenta, list_amount representa el crédito antes del descuento. El enlace permanece disponible a largo plazo, pero aun así se recomienda guardar una copia en su propio almacenamiento.

Ejemplo 2: usar el timbre clonado `reference_id`

A continuación se utiliza un timbre de voz público en español de la plataforma Fish (el _id puede obtenerse mediante una búsqueda en Fish Model Query):

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

Devuelve (verificado):

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

Ejemplo 3: clonación instantánea de voz de un solo uso (`references`)

Coloque el audio de referencia en una dirección HTTPS pública y proporcione el texto original preciso realmente pronunciado en él. Esta voz solo se utiliza para esta síntesis y no creará un modelo permanente:

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "新的旅程从这一刻开始，让我们一起向前。",
    "format": "mp3",
    "references": [{
      "audio": "https://cdn.acedata.cloud/assets/examples/fish/6220d605-39d0-4d43-9e58-0f12949dc9b9-570cfdf96ad9.mp3",
      "text": "春天的清晨，阳光穿过树叶，落在安静的小路上。"
    }]
  }'

Respuesta exitosa verificada:

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/995dfe37-b187-474d-8323-b08d6678ed8f-6359be9f8873.mp3",
  "cost": {"amount": 0.007609319999999999, "currency": "credit"}
}

Método	Ciclo de vida	Escenario aplicable
`references`	Solo para esta solicitud TTS	Uso temporal o un sonido diferente cada vez
`reference_id`	Reutilizable	Sonidos públicos o sonidos a largo plazo creados mediante `/fish/model`

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

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Faster speech with prosody overrides.",
    "prosody": { "speed": 1.2, "volume": 0 },
    "format": "mp3"
  }'

Respuesta (verificada):

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

speed mayor que 1 acelera, menor que 1 ralentiza; la unidad de volume es dB, 0 indica sin cambios, los números positivos aumentan y los negativos atenúan.

Ejemplo 5: Cambiar el modelo + controlar la tasa de bits

Cambie al modelo estable mediante el encabezado HTTP model: s1, y añada 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": "high bitrate mp3",
    "format": "mp3",
    "mp3_bitrate": 128
  }'

Respuesta (verificada):

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

Ejemplo 6: Forma de onda PCM sin procesar

Para escenarios que requieren concatenación en tiempo real en el navegador o 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": "hi",
    "format": "pcm",
    "sample_rate": 16000
  }'

Respuesta (verificada):

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

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

Devolución de llamada asíncrona (`callback_url`)

La síntesis de texto largo de una sola vez puede requerir de decenas de segundos, y si la conexión se interrumpe se debe reintentar. Después de pasar callback_url en el cuerpo de la solicitud, la interfaz devolverá inmediatamente {task_id, started_at}. Cuando el procesamiento ascendente realmente se complete, devolverá el resultado completo a esa URL mediante POST JSON, con el mismo task_id y el cost de nivel superior de la facturación final de esta vez en el cuerpo de la solicitud. La confirmación inicial de la tarea aún no ha completado la síntesis, por lo que no incluye cost.

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。",
    "format": "mp3",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'

Devuelve inmediatamente (verificado):

{
  "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://cdn.acedata.cloud/assets/examples/fish/bd66b8c5-7543-4557-b684-baa72407e336-52f2e79732f2.mp3"
}

También puede usar la API de tareas de Fish para obtener activamente el resultado por task_id; el response.cost del registro en estado terminal es coherente con el cost de la devolución de llamada; consulte ese documento para más detalles.

Manejo de errores

400 token_mismatched: faltan parámetros de la solicitud o no son válidos (lo más común es que text esté vacío, o que format tenga un valor distinto de mp3/wav/pcm).
401 invalid_token: el token de autenticación no existe o no es válido.
429 too_many_requests: se activó 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": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Los errores de validación de parámetros indicarán el campo no válido en el campo message, por ejemplo:

{
  "status": 400,
  "message": "[{\"type\":\"literal_error\",\"loc\":[\"format\"],\"msg\":\"Input should be 'pcm' or 'mp3'\",\"input\":\"wav\"}]"
}

Conclusión

El coste mínimo para integrar Fish TTS es: reemplazar la autenticación por el token de esta plataforma en el código existente que llama a api.fish.audio/v1/tts, y añadir explícitamente format: "mp3" en el cuerpo de la solicitud. Para escenarios de texto largo, se recomienda utilizar la devolución de llamada asíncrona callback_url; para descubrir reference_id de voces clonadas, utilice Consulta de modelo Fish y Obtención de modelo Fish.

Primeros pasos

Chat de IA

Imagen de IA

Video de IA

Audio de IA

Web y datos

CAPTCHA

Identidad

Coding

Más guías

Instrucciones de integración de Fish TTS API

Proceso de solicitud

Encabezados de solicitud

Campos del cuerpo de la solicitud

Ejemplo 1: solicitud mínima (`text` + `format=mp3`)

Ejemplo 2: usar el timbre clonado `reference_id`

Ejemplo 3: clonación instantánea de voz de un solo uso (`references`)

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

Ejemplo 5: Cambiar el modelo + controlar la tasa de bits

Ejemplo 6: Forma de onda PCM sin procesar

Devolución de llamada asíncrona (`callback_url`)

Manejo de errores

Conclusión

​Proceso de solicitud

​Encabezados de solicitud

​Campos del cuerpo de la solicitud

​Ejemplo 1: solicitud mínima (text + format=mp3)

​Ejemplo 2: usar el timbre clonado reference_id

​Ejemplo 3: clonación instantánea de voz de un solo uso (references)

​Ejemplo 3: Ajustar la velocidad / el volumen (prosody)

​Ejemplo 5: Cambiar el modelo + controlar la tasa de bits

​Ejemplo 6: Forma de onda PCM sin procesar

​Devolución de llamada asíncrona (callback_url)

​Manejo de errores

​Conclusión

Proceso de solicitud

Encabezados de solicitud

Campos del cuerpo de la solicitud

Ejemplo 1: solicitud mínima (`text` + `format=mp3`)

Ejemplo 2: usar el timbre clonado `reference_id`

Ejemplo 3: clonación instantánea de voz de un solo uso (`references`)

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

Ejemplo 5: Cambiar el modelo + controlar la tasa de bits

Ejemplo 6: Forma de onda PCM sin procesar

Devolución de llamada asíncrona (`callback_url`)

Manejo de errores

Conclusión