> ## 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 Integrazione Istruzioni

> Fish voice generation API guide - Ace Data Cloud

Questo API si basa su [Fish Audio Official TTS API](https://docs.fish.audio/text-to-speech/text-to-speech), con differenze solo nel metodo di autenticazione (utilizzando il token di questa piattaforma) e nel callback asincrono (estensione `callback_url`), la struttura del corpo della richiesta è la stessa dell'upstream. L'indirizzo è `POST https://api.acedata.cloud/fish/tts`.

## Processo di Richiesta

Per utilizzare Fish TTS API, prima vai al [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token, da tenere come riserva.

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

Se non hai ancora effettuato il login o registrato, verrai automaticamente reindirizzato alla pagina di login che ti invita a registrarti e accedere, una volta completato verrai riportato automaticamente alla pagina corrente.

**Un API Token è sufficiente per accedere a tutti i servizi della piattaforma, non è necessario richiederne uno separato per ogni servizio.** La prima richiesta ti darà un credito gratuito, per un'esperienza gratuita; se il credito è insufficiente, puoi ricaricare il saldo generale nella [console](https://platform.acedata.cloud/console/coin).

> 📘 Documentazione Completa: [Fish TTS API →](https://platform.acedata.cloud/services/fish)

## Intestazione della Richiesta

| Header          | Obbligatorio | Descrizione                                                                                                                                                                                                                                  |
| --------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `authorization` | Sì           | `Bearer {token}`, `{token}` è la chiave richiesta su questa piattaforma.                                                                                                                                                                     |
| `content-type`  | Sì           | `application/json`.                                                                                                                                                                                                                          |
| `accept`        | No           | `application/json`.                                                                                                                                                                                                                          |
| `model`         | No           | Modello TTS, opzioni `s1`, `s2-pro` o `s2.1-pro`, predefinito `s2-pro`. `s2.1-pro` è l'ultima generazione, `s2-pro` ha una forte espressività; `s1` è più stabile, i testi lunghi non tendono a deviare. Tutti e tre hanno lo stesso prezzo. |

## Campi del Corpo della Richiesta

| Campo          | Tipo                | Obbligatorio | Descrizione                                                                                                                                                                                                                 |
| -------------- | ------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`         | string              | Sì           | Testo da sintetizzare, stringa non vuota.                                                                                                                                                                                   |
| `format`       | string              | No           | Formato audio in uscita, opzioni `mp3` (predefinito), `wav`, `pcm`. `wav` e `pcm` restituiscono entrambi un contenitore WAV. `opus` non è supportato, l'invio restituirà direttamente `400`.                                |
| `reference_id` | string \| string\[] | No           | ID del timbro vocale clone (può essere creato tramite [Fish Model API](https://platform.acedata.cloud/documents/fish-model) o recuperato in [Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query)). |
| `references`   | object\[]           | No           | Campioni di riferimento in linea, struttura identica all'upstream, ogni voce contiene `audio` e `text`. Uno dei due con `reference_id`.                                                                                     |
| `sample_rate`  | integer             | No           | Frequenza di campionamento, comunemente `16000`, `22050`, `44100`. `format=mp3` predefinito a 44100.                                                                                                                        |
| `mp3_bitrate`  | integer             | No           | Bitrate MP3, opzioni `64`, `128`, `192`. Solo `format=mp3` è valido.                                                                                                                                                        |
| `prosody`      | object              | No           | Copertura prosodica, supporta `speed` (velocità di parola, 1.0 è la velocità originale) e `volume` (guadagno in dB). Ad esempio `{"speed":1.2,"volume":0}`.                                                                 |
| `chunk_length` | integer             | No           | Lunghezza del frammento upstream, predefinita decisa dall'upstream.                                                                                                                                                         |
| `temperature`  | number              | No           | Temperatura di campionamento, intervallo circa 0.0–1.0.                                                                                                                                                                     |
| `top_p`        | number              | No           | Parametro di campionamento top-p.                                                                                                                                                                                           |
| `latency`      | string              | No           | `normal` o `balanced`, di default questo API completa automaticamente con `normal` (l'invio di una stringa vuota verrà rifiutato dall'upstream).                                                                            |
| `normalize`    | boolean             | No           | Se normalizzare il testo.                                                                                                                                                                                                   |
| `callback_url` | string              | No           | Indirizzo di callback asincrono, vedere sotto "Callback Asincrono". **Questa è un'estensione rispetto all'interfaccia ufficiale**.                                                                                          |

> La denominazione dei campi è completamente identica all'upstream. Ad eccezione di `callback_url`, gli altri campi hanno significato e valori come indicato nella [documentazione ufficiale TTS di Fish](https://docs.fish.audio/text-to-speech/text-to-speech).

## Esempio 1: Richiesta Minima (`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": "Hello world.",
    "format": "mp3"
  }'
```

Risposta (testata):

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

`audio_url` punta al CDN di questa piattaforma, può essere scaricato direttamente con GET o riprodotto in `<audio>`. Il link è disponibile a lungo termine, ma si consiglia comunque di conservarne una copia nel proprio storage.

## Esempio 2: Utilizzo del timbro vocale clone `reference_id`

Di seguito viene utilizzato un timbro vocale spagnolo pubblico sulla piattaforma Fish (`_id` può essere recuperato tramite [Fish Model Query](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"
  }'
```

Risposta (testata):

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

## Esempio 3: Regolazione della Velocità / Volume (`prosody`)

```shell theme={null}
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"
  }'
```

Risposta (testata):

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

`speed` maggiore di 1 accelera, minore di 1 rallenta; `volume` in dB, 0 indica nessuna variazione, numeri positivi guadagno, numeri negativi attenuazione.

## Esempio 4: Cambio Modello + Controllo Bitrate

Attraverso l'intestazione HTTP `model: s1` si passa al modello stabile, aggiungendo `mp3_bitrate: 128` nel corpo della richiesta per controllare il bitrate 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 bitrate mp3",
    "format": "mp3",
    "mp3_bitrate": 128
  }'
```

Risposta (testata):

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

## Esempio 5: Forma d'onda PCM grezza

Per scenari in cui è necessario effettuare un'unione in tempo reale nel browser, o per elaborazioni successive (mixaggio, variazione della velocità) sul client, si consiglia di utilizzare `pcm`:

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

Risposta (testata):

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

> L'estensione del link segue il `format` nella richiesta: `mp3` ottiene `.mp3`, `wav` e `pcm` ottengono `.wav` (contenitore WAV, PCM a 16 bit).

## Callback asincrono (`callback_url`)

La sintesi di testi lunghi può richiedere da alcuni secondi a decine di secondi, se la connessione si interrompe è necessario riprovare. Dopo aver passato `callback_url` nel corpo della richiesta, l'API restituirà immediatamente `{task_id, started_at}`, e quando il processo è completato, il risultato completo verrà richiamato a quell'URL in formato JSON POST, includendo lo stesso `task_id`.

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Oggi il tempo è davvero bello, usciamo a fare una passeggiata.",
    "format": "mp3",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'
```

Restituzione immediata (testata):

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

Successivamente, `callback_url` riceverà un messaggio simile a:

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

È anche possibile utilizzare [Fish Tasks API](https://platform.acedata.cloud/documents/fish-tasks) per richiamare attivamente i risultati in base a `task_id`, vedere la documentazione per maggiori dettagli.

## Gestione degli errori

* `400 token_mismatched`: parametri di richiesta mancanti o non validi (il più comune è `text` vuoto, o `format` con valori diversi da `mp3`/`wav`/`pcm`).
* `401 invalid_token`: il token di autenticazione non esiste o è non valido.
* `429 too_many_requests`: attivazione del limite di velocità dell'account.
* `500 api_error`: errore interno del server.

Esempio di risposta di errore:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

Gli errori di convalida dei parametri includeranno il messaggio di errore originale di pydantic nel campo `message`, per facilitare l'individuazione del campo non valido, ad esempio:

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

## Conclusione

Il costo minimo per integrare Fish TTS è: sostituire il token di autenticazione nel codice esistente che chiama `api.fish.audio/v1/tts` con il token della piattaforma, e includere esplicitamente nel corpo della richiesta `format: "mp3"`. Per scenari di testo lungo, si consiglia di utilizzare `callback_url` per il callback asincrono; per la scoperta del `reference_id` del timbro vocale, si prega di utilizzare [Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query) e [Fish Model Get](https://platform.acedata.cloud/documents/fish-model-get).