> ## 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 TTS API

> Fish music generation 集成指南 - XHuoAPI

W tym dokumencie przedstawiono instrukcję integracji Fish TTS API. Interfejs ten jest w pełni kompatybilny z [oficjalnym OpenAPI Fish Audio](https://docs.fish.audio/text-to-speech/text-to-speech) i umożliwia bezpośrednią migrację kodu wywołującego `https://api.fish.audio/v1/tts` do `https://api.xhuoapi.ai/v1/fish/tts`. Wystarczy jedynie zamienić dane uwierzytelniające, bez konieczności modyfikacji struktury żądania.

## Proces aplikacji

Aby korzystać z API, należy najpierw złożyć wniosek o odpowiednią usługę na stronie [Fish TTS 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 do strony logowania, gdzie możesz się zarejestrować i zalogować. Po zalogowaniu zostaniesz automatycznie przeniesiony z powrotem na tę stronę.

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

## Różnice względem oficjalnego API

To API zachowuje pola żądań i odpowiedzi oficjalnego Fish Audio, ale wprowadza kilka drobnych usprawnień ułatwiających integrację na naszej platformie:

* **Sposób uwierzytelniania**: używa `Authorization: Bearer {token}`, gdzie `{token}` to klucz uzyskany na naszej platformie, a nie oficjalny klucz Fish.
* **Wybór modelu TTS**: określany w nagłówku HTTP `model`, dostępne opcje to `s1` lub `s2-pro`, domyślnie `s2-pro`. To zgodne z oficjalnym API Fish.
* **Domyślna wartość `latency`**: upstream `/fish/v1/tts` zwraca błąd, jeśli `latency` nie jest podane. Nasz interfejs automatycznie ustawia `latency=normal` gdy jest pominięte, co odpowiada domyślnemu zachowaniu Fish.
* **Asynchroniczne wywołanie zwrotne (rozszerzenie platformy)**: jeśli w ciele żądania podasz dodatkowe pole `callback_url`, API zwróci natychmiast `{task_id, started_at}`, a po zakończeniu generowania upstream wyśle pełny wynik `{audio_url, ...}` metodą POST w formacie JSON pod wskazany URL. Oficjalne API Fish nie obsługuje tego pola, jego podanie uruchamia nasz asynchroniczny proces.

Poza powyższymi różnicami wszystkie pola w żądaniu TTS (`text`, `reference_id`, `references`, `prosody`, `format`, `sample_rate`, `mp3_bitrate`, `chunk_length`, `temperature`, `top_p` itd.) są przekazywane bezpośrednio do upstream i działają zgodnie z oficjalną dokumentacją.

## Podstawowe użycie

Minimalne żądanie wymaga tylko pola `text`. Przykład 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": "今天天气真好，我们一起出去散散步吧。"
  }'
```

Przykładowa odpowiedź:

```json theme={null}
{
  "audio_url": "https://platform.r2.fish.audio/task/8a72ff9840234006a9f74cb2fa04f978.mp3"
}
```

Odpowiedź zawiera pola zgodne z oficjalnym API Fish, w tym:

* `audio_url`: URL do wygenerowanego pliku audio, możliwy do pobrania lub odtworzenia.
* `latency_ms` (opcjonalne): czas przetwarzania upstream w milisekundach.

Jeśli chcesz użyć klonowanego głosu, dodaj do ciała żądania `reference_id`:

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

## Asynchroniczne wywołanie zwrotne

Ponieważ generowanie długich tekstów w Fish TTS może trwać długo, utrzymywanie długiego połączenia zużywa zasoby systemowe. Nasze API oferuje możliwość asynchronicznego wywołania zwrotnego (rozszerzenie względem oficjalnego API Fish).

Proces jest następujący: klient wysyła żądanie z dodatkowym polem `callback_url` w ciele. API natychmiast zwraca odpowiedź zawierającą `task_id`. Po zakończeniu generowania upstream wysyła pełne dane (`audio_url` itd.) metodą POST w formacie JSON na `callback_url`, dołączając ten sam `task_id` w ciele, co umożliwia powiązanie wyniku z oryginalnym zadaniem.

Przykład żądania:

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

Natychmiastowa odpowiedź:

```json theme={null}
{
  "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "started_at": "2025-05-09T12:34:56.789Z"
}
```

Po chwili `callback_url` otrzyma pełny wynik:

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

Możesz też użyć [Fish Tasks API](https://api.xhuoapi.ai/documents/fc541fac-a941-47fd-b6f7-48d6cb9da523) do aktywnego sprawdzania statusu zadania po `task_id`.

## Obsługa błędów

API zachowuje oficjalne kody statusu HTTP Fish, ale ciało odpowiedzi jest w ujednoliconym formacie platformy, spójnym z serią `/fish/audios`, `/fish/voices`:

* `400 token_mismatched`: Nieprawidłowe żądanie, możliwe brakujące lub niepoprawne parametry.
* `400 api_not_implemented`: Nieprawidłowe żądanie, możliwe brakujące lub niepoprawne parametry.
* `401 invalid_token`: Brak autoryzacji, nieprawidłowy lub brakujący token.
* `429 too_many_requests`: Zbyt wiele żądań, przekroczono limit.
* `500 api_error`: Błąd wewnętrzny 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 TTS API jest w pełni kompatybilne z oficjalnym OpenAPI Fish Audio i pozwala na migrację istniejących projektów bez żadnych zmian w kodzie, jednocześnie oferując zunifikowane uwierzytelnianie, rozliczanie zużycia oraz asynchroniczne wywołania zwrotne. Zalecamy stosowanie asynchronicznego wywołania zwrotnego przy generowaniu długich tekstów, aby uniknąć obciążenia zasobów przez długie połączenia.