> ## 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.

# Istruzioni per l'integrazione con Fish TTS API

> Fish music generation 集成指南 - XHuoAPI

Questo documento illustra le istruzioni per l'integrazione con Fish TTS API. Questa interfaccia è completamente compatibile con la [Fish Audio OpenAPI ufficiale](https://docs.fish.audio/text-to-speech/text-to-speech) 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](https://api.xhuoapi.ai/services/caf99abc-ddcf-4714-b2a5-862d9b469509). 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:

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

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

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

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

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

```json theme={null}
{
  "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "audio_url": "https://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
}
```

È inoltre possibile utilizzare la [Fish Tasks API](https://api.xhuoapi.ai/documents/fc541fac-a941-47fd-b6f7-48d6cb9da523) 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

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