Fish TTS API Integrazione

Questo API fornisce la conversione da testo a voce, chiamate a suoni salvati e clonazione istantanea di suoni una tantum, l’indirizzo è POST https://api.acedata.cloud/fish/tts.

Processo di richiesta

Per utilizzare l’API Fish TTS, prima vai al Pannello di controllo di Ace Data Cloud per ottenere il tuo API Token, da conservare per uso futuro.

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 riceverà un credito gratuito, per un’esperienza gratuita; se il credito è insufficiente, puoi ricaricare il saldo generale nel pannello di controllo.

📘 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 si discostano facilmente. 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 di output, opzioni `mp3` (predefinito), `wav`, `pcm`. `wav` e `pcm` restituiscono entrambi contenitori WAV. `opus` non è supportato, l’invio restituirà direttamente `400`.
`reference_id`	string \| string[]	No	ID del modello di suono salvato o pubblico, può essere creato tramite Fish Model API o recuperato in Fish Model Query. Non può essere utilizzato insieme a `references`.
`references`	object[]	No	Clonazione istantanea di suoni, supporta solo un campione `{audio, text}`: `audio` è un URL MP3/WAV HTTPS pubblico, `text` è la trascrizione esatta dell’audio. Non può essere utilizzato insieme a `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à, 1.0 è la velocità originale) e `volume` (guadagno in dB). Ad esempio `{"speed":1.2,"volume":0}`.
`chunk_length`	integer	No	Lunghezza del chunk 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 compensa automaticamente con `normal` (se si invia una stringa vuota, l’upstream rifiuterà).
`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 clonazione istantanea accetta solo URL audio HTTPS, non accetta MessagePack, Base64, data URI o URL con credenziali. L’audio di riferimento è consigliato tra 10 e 270 secondi; Studio utilizza un intervallo più conservativo di 10-60 secondi.

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>. La risposta finale di successo restituirà anche il cost di livello superiore, dove amount è il credito effettivamente addebitato; se ci sono sconti sul conto, list_amount indica il credito prima dello sconto. Il link è disponibile a lungo termine, ma si consiglia comunque di conservarne una copia nel proprio storage.

Esempio 2: Utilizzo del tono di clonazione `reference_id`

Di seguito viene utilizzato un tono di voce 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: Clonazione istantanea di suoni (`references`)

Posizionare l’audio di riferimento su un indirizzo HTTPS pubblico e fornire il testo esatto pronunciato. Questo suono è utilizzato solo per questa sintesi e non creerà un modello a lungo termine:

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://platform2.cdn.acedata.cloud/fish/6220d605-39d0-4d43-9e58-0f12949dc9b9.mp3",
      "text": "春天的清晨，阳光穿过树叶，落在安静的小路上。"
    }]
  }'

Risposta di successo testata:

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

Metodo	Ciclo di vita	Scenari applicabili
`references`	Solo per questa richiesta TTS	Utilizzo temporaneo o voce diversa ogni volta
`reference_id`	Riutilizzabile	Voce pubblica o voce a lungo termine creata tramite `/fish/model`

Esempio 3: Regolare la velocità / volume (`prosody`)

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Parlare più velocemente con sovrascritture di prosodia.",
    "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 significa invariato, numero positivo guadagna, numero negativo attenua.

Esempio 5: Cambiare modello + controllare bitrate

Per passare al modello stabile, utilizzare l’intestazione HTTP model: s1, aggiungere 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": "mp3 ad alto bitrate",
    "format": "mp3",
    "mp3_bitrate": 128
  }'

Risposta (testata):

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

Esempio 6: Forma d’onda PCM grezza

Se è necessario eseguire un montaggio in tempo reale nel browser o elaborare successivamente (mixaggio, variazione di 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’interfaccia restituirà immediatamente {task_id, started_at}, quando il processo è completato, il risultato completo verrà richiamato a quell’URL in formato JSON POST, con lo stesso task_id e il cost finale di questa richiesta. La conferma del compito iniziale non è ancora completata, quindi non include cost.

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, andiamo a fare una passeggiata insieme.",
    "format": "mp3",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'

Risposta 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 al task_id; il response.cost registrato nello stato finale corrisponde al cost nel callback, vedere il documento 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: superamento 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 saranno descritti nel campo message, 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 l’autenticazione con il token della piattaforma nel codice già esistente che chiama api.fish.audio/v1/tts, e nel corpo della richiesta includere esplicitamente format: "mp3". Per testi lunghi, si consiglia di utilizzare callback_url per il callback asincrono; per la scoperta del reference_id del tono vocale clonabile, 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

Coding

Processo di richiesta

Intestazione della richiesta

Campi del corpo della richiesta

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

Esempio 2: Utilizzo del tono di clonazione `reference_id`

Esempio 3: Clonazione istantanea di suoni (`references`)

Esempio 3: Regolare la velocità / volume (`prosody`)

Esempio 5: Cambiare modello + controllare bitrate

Esempio 6: 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 tono di clonazione reference_id

​Esempio 3: Clonazione istantanea di suoni (references)

​Esempio 3: Regolare la velocità / volume (prosody)

​Esempio 5: Cambiare modello + controllare bitrate

​Esempio 6: 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 tono di clonazione `reference_id`

Esempio 3: Clonazione istantanea di suoni (`references`)

Esempio 3: Regolare la velocità / volume (`prosody`)

Esempio 5: Cambiare modello + controllare bitrate

Esempio 6: Forma d’onda PCM grezza

Callback asincrono (`callback_url`)

Gestione degli errori

Conclusione