> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Fish TTS API Integración

> Fish voice generation API guide - Ace Data Cloud

Esta interfaz se basa en la [API oficial de TTS de Fish Audio](https://docs.fish.audio/text-to-speech/text-to-speech), 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](https://platform.acedata.cloud/console/applications) para obtener tu API Token, guárdalo para uso futuro.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

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](https://platform.acedata.cloud/console/coin).

> 📘 Documentación completa: [Fish TTS API →](https://platform.acedata.cloud/services/fish)

## 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](https://platform.acedata.cloud/documents/fish-model) o recuperado en [Consulta de Modelos de Fish](https://platform.acedata.cloud/documents/fish-model-query)). |
| `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](https://docs.fish.audio/text-to-speech/text-to-speech).

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

```shell theme={null}
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):

```json theme={null}
{
  "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](https://platform.acedata.cloud/documents/fish-model-query)):

```shell theme={null}
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):

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

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

```shell theme={null}
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):

```json theme={null}
{
  "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:

```shell theme={null}
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):

```json theme={null}
{
  "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`:

```shell theme={null}
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):

```json theme={null}
{
  "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.

```shell theme={null}
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):

```json theme={null}
{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "started_at": 1778462584.742
}
```

Más tarde, `callback_url` recibirá algo como:

```json theme={null}
{
  "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](https://platform.acedata.cloud/documents/fish-tasks) 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](https://platform.acedata.cloud/documents/fish-model-query) y [Fish Model Get](https://platform.acedata.cloud/documents/fish-model-get).