Fish TTS API Integrazione Istruzioni

Questo API si basa su Fish Audio Official TTS API, 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 per ottenere il tuo API Token, da tenere come riserva.

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.

📘 Documentazione Completa: Fish TTS API →

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 o recuperato in 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.

Esempio 1: Richiesta Minima (`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"
  }'

Risposta (testata):

{
  "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):

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):

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

Esempio 3: Regolazione della Velocità / Volume (`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"
  }'

Risposta (testata):

{
  "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:

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):

{
  "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:

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):

{
  "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.

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):

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

Successivamente, callback_url riceverà un messaggio simile a:

{
  "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 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:

{
  "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:

{
  "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 e Fish Model Get.

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Proxy

Avanzato

Fish TTS API Integrazione Istruzioni

Processo di Richiesta

Intestazione della Richiesta

Campi del Corpo della Richiesta

Esempio 1: Richiesta Minima (`text` + `format=mp3`)

Esempio 2: Utilizzo del timbro vocale clone `reference_id`

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

Esempio 4: Cambio Modello + Controllo Bitrate

Esempio 5: Forma d’onda PCM grezza

Callback asincrono (`callback_url`)

Gestione degli errori

Conclusione

​Processo di Richiesta

​Intestazione della Richiesta

​Campi del Corpo della Richiesta

​Esempio 1: Richiesta Minima (text + format=mp3)

​Esempio 2: Utilizzo del timbro vocale clone reference_id

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

​Esempio 4: Cambio Modello + Controllo Bitrate

​Esempio 5: Forma d’onda PCM grezza

​Callback asincrono (callback_url)

​Gestione degli errori

​Conclusione

Processo di Richiesta

Intestazione della Richiesta

Campi del Corpo della Richiesta

Esempio 1: Richiesta Minima (`text` + `format=mp3`)

Esempio 2: Utilizzo del timbro vocale clone `reference_id`

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

Esempio 4: Cambio Modello + Controllo Bitrate

Esempio 5: Forma d’onda PCM grezza

Callback asincrono (`callback_url`)

Gestione degli errori

Conclusione