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

# Fish Model API Integrationsanvisningar

> Fish music generation 集成指南 - XHuoAPI

Denna artikel beskriver integrationsanvisningarna för Fish Model API, som är helt kompatibel med [Fish Audio officiella OpenAPI](https://docs.fish.audio/resources/api-reference/model) och inkluderar:

* `POST /fish/model`: Skapa en ny klonad röstmodell baserat på ljudprov.
* `GET /fish/model`: Paginera och hämta listan över röster synliga för det aktuella kontot eller hela plattformen.

## Ansökningsprocess

För att använda API:et måste du först ansöka om motsvarande tjänst på [Fish Model API](https://api.xhuoapi.ai/services/caf99abc-ddcf-4714-b2a5-862d9b469509). När du går in på sidan klickar du på knappen "Acquire".

Om du inte är inloggad eller registrerad kommer du automatiskt att omdirigeras till inloggningssidan för att registrera dig och logga in. Efter inloggning eller registrering återvänder du automatiskt till den aktuella sidan.

Vid första ansökan får du en gratis kvot som gör att du kan använda API:et kostnadsfritt.

## Skillnader från officiella API

* **Autentisering**: Använder `Authorization: Bearer {token}`, där `{token}` är nyckeln som ansöks om på denna plattform.
* **Uppladdning av prov vid modellskapande**: Detta API stöder för närvarande endast JSON-format där ljudprovs-URL:er skickas via fältet `voices`. Fish officiella API stöder multipart/msgpack för direkt binär uppladdning, vilket ännu inte är implementerat här. URL-baserad uppladdning täcker cirka 80 % av vanliga scenarier.
* **Svarstruktur**: Både `POST /fish/model` och `GET /fish/model` vidarebefordrar direkt svaren från Fish upstream utan plattforms-envelope. Vid fel används plattformens standardstruktur `{success:false, error:{code,message}, trace_id}`.

## Skapa röstmodell (POST /fish/model)

Minimikrav för skapande är fälten `title` och `voices`. `voices` är en lista med URL:er till ljudprov. Varje fil rekommenderas vara minst 30 sekunder lång med en samplingsfrekvens på 16 kHz eller högre.

```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"
  }'
```

Ett lyckat svar returnerar direkt Fish-plattformens ModelEntity-objekt:

```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"
  }
}
```

Det returnerade `_id` kan användas som värde för fältet `reference_id` i efterföljande `POST /fish/tts` för att syntetisera tal med den klonade rösten.

## Hämta röstmodell-lista (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'
```

Tillgängliga sökparametrar (samma som Fish officiella API):

* `page_size`: Antal poster per sida, standard är 10.
* `page_number`: Sidnummer, börjar från 1.
* `title`: Fritextsökning i titel.
* `tag`: Filtrera på tagg.
* `self`: Om `true` returneras endast röster skapade av det aktuella kontot.
* `author_id`: Filtrera på skapare.
* `language`: Filtrera på röstspråk.
* `title_language`: Filtrera på titelspråk.

Ett lyckat svar vidarebefordrar Fish-plattformens paginerade struktur direkt:

```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
}
```

## Prissättning

Detta API debiterar endast vid "Skapa röstmodell" (`POST /fish/model` med `voices` i request body). "Hämta röstmodell-lista" (`GET /fish/model`) är kostnadsfritt.

## Felhantering

* `400 token_mismatched`: Felaktig förfrågan, troligen saknade eller ogiltiga parametrar.
* `400 api_not_implemented`: Felaktig förfrågan, troligen saknade eller ogiltiga parametrar.
* `401 invalid_token`: Obefogad, ogiltig eller saknad auktoriseringstoken.
* `429 too_many_requests`: För många förfrågningar, gränsen för förfrågningar har överskridits.
* `500 api_error`: Intern serverfel, något gick fel på servern.

### Exempel på felrespons

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## Slutsats

Fish Model API är helt kompatibelt med Fish Audio officiella OpenAPI:s ModelEntity-gränssnitt och möjliggör migrering av befintlig kod för klonad rösthantering utan kodändringar. Det skapade röstmodellens `_id` kan direkt användas som `reference_id` i [Fish TTS API](https://api.xhuoapi.ai/documents/77adcb84-d59f-5ef9-b8a0-8b35eb42a71d) för talsyntes.