Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt

Use this file to discover all available pages before exploring further.

Questo documento illustra le istruzioni per l’integrazione con Fish TTS API. Questa interfaccia è completamente compatibile con la Fish Audio OpenAPI ufficiale e consente di migrare direttamente il codice che originariamente chiamava https://api.fish.audio/v1/tts a https://api.xhuoapi.ai/v1/fish/tts, sostituendo solo le informazioni di autenticazione senza modificare la struttura del corpo della richiesta.

​
Procedura di richiesta

Per utilizzare l’API, è necessario prima richiedere il servizio corrispondente nella pagina Fish TTS API. Dopo essere entrati nella pagina, cliccare sul pulsante “Acquire”. Se non si è ancora effettuato l’accesso o la registrazione, si verrà automaticamente reindirizzati alla pagina di login per registrarsi e accedere; dopo il login o la registrazione si tornerà automaticamente alla pagina corrente. Alla prima richiesta viene offerto un credito gratuito per utilizzare l’API senza costi.

​
Differenze rispetto all’API ufficiale

Questa API mantiene i campi di richiesta e risposta ufficiali di Fish Audio, con alcune piccole estensioni per una migliore integrazione sulla nostra piattaforma:
  • Metodo di autenticazione: utilizza Authorization: Bearer {token}, dove {token} è la chiave richiesta sulla nostra piattaforma, non la chiave ufficiale Fish.
  • Selezione del modello TTS: specificata tramite header HTTP model, con opzioni s1 o s2-pro, valore predefinito s2-pro. Questo è conforme all’API ufficiale Fish.
  • Valore predefinito di latency: l’endpoint upstream /fish/v1/tts restituisce errore se latency non è fornito; questa API aggiunge automaticamente latency=normal se omesso, in linea con il comportamento predefinito ufficiale.
  • Callback asincrono (estensione della piattaforma): se nel corpo della richiesta è presente il campo aggiuntivo callback_url, l’API risponde immediatamente con {task_id, started_at} e, al completamento della generazione upstream, invia il risultato completo {audio_url, ...} tramite POST JSON all’URL indicato. L’API ufficiale Fish non supporta questo campo; la sua presenza attiva il flusso asincrono della nostra piattaforma.
A parte queste differenze, tutti i campi del corpo della richiesta TTS (text, reference_id, references, prosody, format, sample_rate, mp3_bitrate, chunk_length, temperature, top_p, ecc.) sono trasmessi direttamente upstream e il comportamento è identico alla documentazione ufficiale.

​
Uso base

La richiesta minima richiede solo il campo text. Ecco un esempio CURL: 
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。"
  }'
Esempio di risposta: 
{
  "audio_url": "https://platform.r2.fish.audio/task/8a72ff9840234006a9f74cb2fa04f978.mp3"
}
La risposta contiene direttamente i campi ufficiali Fish, tra cui:
  • audio_url: URL dell’audio generato, scaricabile o riproducibile direttamente.
  • latency_ms (opzionale): tempo di elaborazione upstream in millisecondi.
Per utilizzare una voce clonata, si può aggiungere reference_id nel corpo della richiesta: 
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。",
    "reference_id": "d7900c21663f485ab63ebdb7e5905036",
    "format": "mp3",
    "sample_rate": 44100
  }'

​
Callback asincrono

Poiché la generazione di testi lunghi con Fish TTS può richiedere tempi prolungati e mantenere connessioni lunghe consuma risorse di sistema, questa API offre la capacità di callback asincrono (estensione rispetto all’API ufficiale Fish). Il flusso è il seguente: il client invia la richiesta specificando nel corpo il campo aggiuntivo callback_url; l’API risponde immediatamente con un task_id; quando la generazione upstream è completata, il risultato finale con audio_url e altri campi viene inviato tramite POST JSON all’URL indicato in callback_url, includendo lo stesso task_id per associare il risultato asincrono al task originale. Esempio di richiesta: 
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'
Risposta immediata: 
{
  "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "started_at": "2025-05-09T12:34:56.789Z"
}
Dopo qualche istante, il callback_url riceverà il risultato completo: 
{
  "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "audio_url": "https://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
}
È inoltre possibile utilizzare la Fish Tasks API per interrogare attivamente lo stato del task tramite task_id.

​
Gestione degli errori

Le risposte di errore di questa API mantengono i codici HTTP ufficiali Fish, ma il corpo della risposta utilizza un formato unificato della piattaforma per coerenza con le serie /fish/audios e /fish/voices:
  • 400 token_mismatched: richiesta errata, probabilmente per parametri mancanti o non validi.
  • 400 api_not_implemented: richiesta errata, probabilmente per parametri mancanti o non validi.
  • 401 invalid_token: non autorizzato, token di autorizzazione mancante o non valido.
  • 429 too_many_requests: troppe richieste, superato il limite di velocità.
  • 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"
}

​
Conclusione

Fish TTS API è completamente compatibile con la Fish Audio OpenAPI ufficiale e consente di migrare progetti esistenti senza modifiche al codice, beneficiando al contempo di autenticazione unificata, contabilizzazione dell’utilizzo e capacità di callback asincrono offerte dalla piattaforma. Si consiglia di utilizzare preferibilmente il callback asincrono per testi lunghi per evitare il consumo di risorse dovuto a connessioni lunghe.