> ## 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 Model API > Fish music generation 集成指南 - XHuoAPI Questo documento illustra le istruzioni per l'integrazione con Fish Model API, un'interfaccia completamente compatibile con la [Fish Audio OpenAPI ufficiale](https://docs.fish.audio/resources/api-reference/model), che include: * `POST /fish/model`: crea un nuovo modello vocale (Voice Model) basato su campioni audio. * `GET /fish/model`: ricerca paginata della lista dei modelli vocali visibili per l'account corrente o su tutta la piattaforma. ## Procedura di richiesta Per utilizzare l'API, è necessario prima richiedere il servizio corrispondente sulla pagina [Fish Model API](https://api.xhuoapi.ai/services/caf99abc-ddcf-4714-b2a5-862d9b469509). Una volta entrati nella pagina, cliccare sul pulsante "Acquire". Se non si è ancora effettuato l'accesso o la registrazione, si verrà reindirizzati automaticamente alla pagina di login per registrarsi o accedere; dopo il login o la registrazione, si tornerà automaticamente alla pagina corrente. Alla prima richiesta verrà assegnata una quota gratuita per utilizzare l'API senza costi. ## Differenze rispetto all'API ufficiale * **Metodo di autenticazione**: si utilizza `Authorization: Bearer {token}`, dove `{token}` è la chiave ottenuta sulla nostra piattaforma. * **Upload dei campioni per la creazione del modello**: attualmente questa API supporta solo l'invio in formato JSON tramite il campo `voices`, contenente gli URL dei campioni audio. L'API ufficiale Fish supporta multipart/msgpack per l'upload diretto di binari, ma questa funzionalità non è ancora implementata sulla nostra piattaforma; l'uso degli URL copre circa l'80% degli scenari comuni. * **Struttura della risposta**: sia `POST /fish/model` che `GET /fish/model` inoltrano direttamente la risposta proveniente da Fish senza incapsularla in un envelope della piattaforma; in caso di errore viene utilizzata la struttura standard `{success:false, error:{code,message}, trace_id}`. ## Creazione di un modello vocale (POST /fish/model) La richiesta minima per la creazione richiede i campi `title` e `voices`. `voices` è una lista di URL dei campioni audio, consigliati file di almeno 30 secondi con frequenza di campionamento di 16kHz o superiore. ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/fish/model' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "title": "我的克隆音色", "description": "用一段播客录音克隆的音色", "voices": [ "https://example.com/sample-voice.mp3" ], "cover_image": "https://example.com/cover.png", "visibility": "private" }' ``` La risposta di successo restituisce direttamente l'oggetto ModelEntity della piattaforma Fish: ```json theme={null} { "_id": "d7900c21663f485ab63ebdb7e5905036", "type": "tts", "title": "我的克隆音色", "description": "用一段播客录音克隆的音色", "cover_image": "https://example.com/cover.png", "train_mode": "fast", "state": "trained", "tags": [], "samples": [], "created_at": "2025-05-09T12:34:56.789Z", "updated_at": "2025-05-09T12:34:56.789Z", "languages": ["zh", "en"], "visibility": "private", "lock_visibility": false, "like_count": 0, "mark_count": 0, "shared_count": 0, "task_count": 0, "author": { "_id": "user_id", "nickname": "user_nickname", "avatar": "user_avatar" } } ``` L'`_id` restituito può essere utilizzato come valore del campo `reference_id` nelle successive chiamate `POST /fish/tts` per la sintesi vocale con il modello clonato. ## Ricerca della lista dei modelli vocali (GET /fish/model) ```shell theme={null} curl -G 'https://api.xhuoapi.ai/v1/fish/model' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ --data-urlencode 'page_size=10' \ --data-urlencode 'page_number=1' \ --data-urlencode 'self=true' ``` Parametri di query disponibili (uguali all'API ufficiale Fish): * `page_size`: numero di elementi per pagina, default 10. * `page_number`: numero della pagina, a partire da 1. * `title`: ricerca fuzzy per titolo. * `tag`: filtro per tag. * `self`: se `true`, restituisce solo i modelli creati dall'account corrente. * `author_id`: filtro per autore. * `language`: filtro per lingua del modello vocale. * `title_language`: filtro per lingua del titolo. La risposta di successo inoltra direttamente la struttura paginata della piattaforma Fish: ```json theme={null} { "items": [ { "_id": "d7900c21663f485ab63ebdb7e5905036", "title": "我的克隆音色", "description": "用一段播客录音克隆的音色", "cover_image": "https://example.com/cover.png", "type": "tts", "state": "trained", "tags": [], "languages": ["zh", "en"], "visibility": "private", "created_at": "2025-05-09T12:34:56.789Z", "updated_at": "2025-05-09T12:34:56.789Z" } ], "total": 1 } ``` ## Informazioni sulla fatturazione Questa API addebita solo per la creazione di modelli vocali (`POST /fish/model` con campo `voices` nel corpo della richiesta); la ricerca della lista dei modelli (`GET /fish/model`) è gratuita. ## Gestione degli errori * `400 token_mismatched`: richiesta errata, probabilmente parametri mancanti o non validi. * `400 api_not_implemented`: richiesta errata, probabilmente 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 frequenza. * `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 Model API è completamente compatibile con l'interfaccia ModelEntity della Fish Audio OpenAPI ufficiale, permettendo di migrare il codice di gestione dei modelli vocali clonati esistente senza modifiche. L'`_id` del modello creato può essere utilizzato direttamente come valore del campo `reference_id` nella [Fish TTS API](https://api.xhuoapi.ai/documents/77adcb84-d59f-5ef9-b8a0-8b35eb42a71d) per la sintesi vocale.