Fish TTS API Integración

Esta interfaz proporciona conversión de texto a voz, llamada de sonidos guardados y clonación de sonido instantáneo, con la dirección POST https://api.acedata.cloud/fish/tts.

Proceso de Solicitud

Para usar la API Fish TTS, primero dirígete a Ace Data Cloud Console 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, se devolverá `400` si se proporciona.
`reference_id`	string \| string[]	No	ID del modelo de sonido guardado o público, que puede ser creado por Fish Model API, o recuperado en Fish Model Query. No se puede usar junto con `references`.
`references`	object[]	No	Clonación de sonido instantáneo, solo se admite una muestra `{audio, text}`: `audio` es una URL pública HTTPS MP3/WAV, `text` es la transcripción exacta del audio. No se puede usar junto con `reference_id`.
`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 MP3, puede ser `64`, `128`, `192`. Solo es efectivo si `format=mp3`.
`prosody`	object	No	Cobertura de prosodia, admite `speed` (velocidad, 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, por defecto determinada por el ascendente.
`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 completará con `normal` (si se pasa una cadena vacía, el ascendente la rechazará).
`normalize`	boolean	No	Si se debe normalizar el texto.
`callback_url`	string	No	Dirección de callback asíncrono, ver más abajo “Callback asíncrono”. Esta es una extensión relativa a la interfaz oficial.

La clonación instantánea solo acepta URL de audio HTTPS, no acepta MessagePack, Base64, data URI o 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 a 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": "Hola mundo.",
    "format": "mp3"
  }'

Respuesta (medida):

{
  "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>. La respuesta final exitosa también devolverá el cost de nivel superior, donde amount es el crédito realmente deducido en esta ocasión; si hay un descuento en la cuenta, list_amount indica el monto antes del descuento. 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 en la plataforma Fish (_id se puede recuperar a través de 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"
  }'

Respuesta (medida):

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

Ejemplo 3: Clonación de sonido instantáneo (`references`)

Coloca el audio de referencia en una dirección HTTPS pública y proporciona el texto exacto que se dice. Este sonido solo se utilizará para esta síntesis y no creará un modelo a largo plazo:

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "Un nuevo viaje comienza en este momento, avancemos juntos.",
    "format": "mp3",
    "references": [{
      "audio": "https://platform2.cdn.acedata.cloud/fish/6220d605-39d0-4d43-9e58-0f12949dc9b9.mp3",
      "text": "En la mañana de primavera, la luz del sol atraviesa las hojas y cae sobre el tranquilo sendero."
    }]
  }'

Respuesta exitosa medida:

{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/995dfe37-b187-474d-8323-b08d6678ed8f.mp3",
  "cost": {"amount": 0.007609319999999999, "currency": "crédito"}
}

方式	生命周期	适用场景
`references`	仅本次 TTS 请求	Uso temporal o cada vez con voz diferente
`reference_id`	可重复使用	Voz pública o voz a largo plazo creada a través de `/fish/model`

示例 3：调节语速 / 音量（`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"
  }'

返回（实测）：

{
  "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úmero positivo aumenta, número negativo disminuye.

示例 5：切换模型 + 控制码率

A través del encabezado HTTP model: s1 cambie a un modelo estable, agregue 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": "mp3 de alta tasa de bits",
    "format": "mp3",
    "mp3_bitrate": 128
  }'

返回（实测）：

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

示例 6：PCM 原始波形

Necesario para la concatenación en tiempo real en el navegador, o para el 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
  }'

返回（实测）：

{
  "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_url`）

La síntesis de texto largo puede tardar de decenas de segundos a varios minutos, si la conexión se interrumpe, es necesario reintentar. Al pasar callback_url en el cuerpo de la solicitud, la interfaz devolverá inmediatamente {task_id, started_at}, y cuando se complete realmente, enviará el resultado completo en formato JSON POST a esa URL, con el mismo task_id y el cost de facturación final de esta vez. La tarea inicial confirmada 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": "Hoy hace buen tiempo, salgamos a dar un paseo.",
    "format": "mp3",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'

立即返回（实测）：

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

稍后 callback_url 会收到形如：

{
  "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 según task_id; el response.cost del estado final coincide con el cost en la devolución, consulte ese documento para más detalles.

错误处理

400 token_mismatched：Faltan o son inválidos los parámetros de solicitud (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.

错误响应示例：

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

参数校验错误会在 message 字段说明不合法的字段，例如：

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

结论

El costo mínimo para integrar Fish TTS es: en el código que ya llama a api.fish.audio/v1/tts, cambie la autenticación por el token de esta plataforma y en el cuerpo de la solicitud específicamente incluya 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 voces clonadas, 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

Coding

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: Clonación de sonido instantáneo (`references`)

示例 3：调节语速 / 音量（`prosody`）

示例 5：切换模型 + 控制码率

示例 6：PCM 原始波形

异步回调（`callback_url`）

错误处理

结论

​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: Clonación de sonido instantáneo (references)

​示例 3：调节语速 / 音量（prosody）

​示例 5：切换模型 + 控制码率

​示例 6：PCM 原始波形

​异步回调（callback_url）

​错误处理

​结论

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: Clonación de sonido instantáneo (`references`)

示例 3：调节语速 / 音量（`prosody`）

示例 5：切换模型 + 控制码率

示例 6：PCM 原始波形

异步回调（`callback_url`）

错误处理

结论