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

# Instrukcja integracji Fish Model Query API

> Fish music generation 集成指南 - XHuoAPI

W tym dokumencie przedstawiono instrukcję integracji Fish Model Query API (`GET /fish/model`). Interfejs ten jest w pełni kompatybilny z [Fish Audio oficjalnym OpenAPI](https://docs.fish.audio/resources/api-reference/model) i służy do **stronicowanego pobierania** listy klonowanych głosów widocznych dla bieżącego konta lub całej platformy.

> Tworzenie głosów proszę realizować za pomocą [Fish Model Create API](https://api.xhuoapi.ai/documents/62fdf4f1-6a05-4d92-bb15-1bf78b27a14a), a zapytania o pojedynczy głos po `_id` za pomocą [Fish Model Get API](https://api.xhuoapi.ai/documents/dabdffe7-254b-5a3f-9eca-425d614d82b9).

## Proces aplikacji

Aby korzystać z API, należy najpierw złożyć wniosek o odpowiednią usługę na stronie [Fish Model API](https://api.xhuoapi.ai/services/caf99abc-ddcf-4714-b2a5-862d9b469509). Po wejściu na stronę kliknij przycisk „Acquire”.

Jeśli nie jesteś zalogowany lub zarejestrowany, zostaniesz automatycznie przekierowany na stronę logowania, gdzie możesz się zarejestrować i zalogować. Po zalogowaniu zostaniesz automatycznie przekierowany z powrotem na bieżącą stronę.

Przy pierwszym wniosku otrzymasz darmowy limit, który pozwala na bezpłatne korzystanie z API.

## Różnice względem oficjalnego API

* **Metoda uwierzytelniania**: używa `Authorization: Bearer {token}`, gdzie `{token}` to klucz uzyskany na tej platformie.
* **Struktura odpowiedzi**: bezpośrednio przekazuje stronicowaną odpowiedź z Fish, bez opakowania w platformowy envelope; w przypadku błędu stosuje standardową strukturę platformy `{success:false, error:{code,message}, trace_id}`.

## Przykład zapytania

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

## Parametry zapytania

Zgodne z Fish Audio:

* `page_size`: liczba elementów na stronę, domyślnie 10.
* `page_number`: numer strony, zaczynając od 1.
* `title`: wyszukiwanie rozmyte po tytule.
* `tag`: filtrowanie po tagach.
* `self`: jeśli `true`, zwraca tylko głosy utworzone przez bieżące konto.
* `author_id`: filtrowanie po twórcy.
* `language`: filtrowanie po języku głosu.
* `title_language`: filtrowanie po języku tytułu.

## Przykład odpowiedzi

Pomyślna odpowiedź bezpośrednio przekazuje strukturę stronicowania 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
}
```

Zwrócone `_id` może być użyte jako wartość pola `reference_id` w kolejnych wywołaniach [Fish TTS API](https://api.xhuoapi.ai/documents/77adcb84-d59f-5ef9-b8a0-8b35eb42a71d) do syntezy mowy z wykorzystaniem tego klonowanego głosu.

## Informacje o rozliczeniach

To API jest bezpłatne — stronicowane zapytania o listę głosów są darmowe. Opłaty naliczane są tylko za `POST /fish/model` podczas tworzenia nowego głosu z polem `voices` w ciele żądania.

## Obsługa błędów

* `400 token_mismatched`: brak lub nieprawidłowe parametry zapytania.
* `400 api_not_implemented`: metoda lub parametry nie są obecnie obsługiwane.
* `401 invalid_token`: brak lub nieważne dane uwierzytelniające.
* `429 too_many_requests`: przekroczono limit szybkości dla konta.
* `500 api_error`: wewnętrzny błąd serwera.

### Przykład odpowiedzi błędu

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

## Podsumowanie

Fish Model Query API zapewnia w pełni kompatybilną z Fish Audio oficjalną funkcjonalność wyszukiwania głosów, umożliwiając utrzymanie własnej biblioteki klonowanych głosów na platformie. W połączeniu z [Fish Model Get API](https://api.xhuoapi.ai/documents/dabdffe7-254b-5a3f-9eca-425d614d82b9) pozwala pobrać pełne szczegóły pojedynczego głosu po jego ID.