> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Fish TTS API Integracja Opis

> Fish voice generation API guide - Ace Data Cloud

Ten interfejs oparty jest na [oficjalnym API TTS Fish Audio](https://docs.fish.audio/text-to-speech/text-to-speech), różni się jedynie metodą autoryzacji (używając tokena z tej platformy) oraz asynchronicznym wywołaniem zwrotnym (rozszerzenie `callback_url`), struktura ciała żądania jest zgodna z upstream. Adres to `POST https://api.acedata.cloud/fish/tts`.

## Proces aplikacji

Aby korzystać z Fish TTS API, najpierw przejdź do [konsoli Ace Data Cloud](https://platform.acedata.cloud/console/applications), aby uzyskać swój token API, zachowaj go na przyszłość.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

Jeśli nie jesteś zalogowany lub zarejestrowany, automatycznie zostaniesz przekierowany na stronę logowania, aby zarejestrować się i zalogować, po zakończeniu zostaniesz automatycznie przekierowany z powrotem na bieżącą stronę.

**Jeden token API wystarczy do wywołania wszystkich usług platformy, nie ma potrzeby składania osobnych wniosków dla każdej usługi.** Pierwsze zgłoszenie otrzyma darmowy limit, aby móc skorzystać z bezpłatnej wersji; w przypadku niewystarczającego limitu można doładować saldo ogólne w [konsoli](https://platform.acedata.cloud/console/coin).

> 📘 Pełna dokumentacja: [Fish TTS API →](https://platform.acedata.cloud/services/fish)

## Nagłówki żądania

| Nagłówek        | Wymagane | Opis                                                                                                                                                                                                                                                         |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `authorization` | Tak      | `Bearer {token}`, gdzie `{token}` to klucz uzyskany na tej platformie.                                                                                                                                                                                       |
| `content-type`  | Tak      | `application/json`.                                                                                                                                                                                                                                          |
| `accept`        | Nie      | `application/json`.                                                                                                                                                                                                                                          |
| `model`         | Nie      | Model TTS, opcjonalnie `s1`, `s2-pro` lub `s2.1-pro`, domyślnie `s2-pro`. `s2.1-pro` to najnowsza generacja, `s2-pro` ma silniejszą ekspresję; `s1` jest bardziej stabilny, długie teksty nie są łatwe do zniekształcenia. Wszystkie trzy mają tę samą cenę. |

## Pola ciała żądania

| Pole           | Typ                 | Wymagane | Opis                                                                                                                                                                                                                |
| -------------- | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`         | string              | Tak      | Tekst do zsyntetyzowania, niepusty ciąg znaków.                                                                                                                                                                     |
| `format`       | string              | Nie      | Format wyjściowy audio, opcjonalnie `mp3` (domyślnie), `wav`, `pcm`. `wav` i `pcm` zwracają kontener WAV. `opus` nie jest obsługiwany, przesłanie spowoduje bezpośredni zwrot `400`.                                |
| `reference_id` | string \| string\[] | Nie      | ID klonowanego głosu (można utworzyć za pomocą [Fish Model API](https://platform.acedata.cloud/documents/fish-model) lub wyszukać w [Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query)). |
| `references`   | object\[]           | Nie      | Wbudowane próbki referencyjne, struktura zgodna z upstream, każda zawiera `audio` i `text`. Wybór między `reference_id` a `references`.                                                                             |
| `sample_rate`  | integer             | Nie      | Częstotliwość próbkowania, powszechnie używane `16000`, `22050`, `44100`. `format=mp3` domyślnie 44100.                                                                                                             |
| `mp3_bitrate`  | integer             | Nie      | Bitrate MP3, opcjonalnie `64`, `128`, `192`. Działa tylko dla `format=mp3`.                                                                                                                                         |
| `prosody`      | object              | Nie      | Pokrycie prozodii, wspiera `speed` (prędkość mowy, 1.0 to oryginalna prędkość) i `volume` (wzmocnienie głośności dB). Na przykład `{"speed":1.2,"volume":0}`.                                                       |
| `chunk_length` | integer             | Nie      | Długość fragmentu upstream, domyślnie ustalana przez upstream.                                                                                                                                                      |
| `temperature`  | number              | Nie      | Temperatura próbkowania, zakres około 0.0–1.0.                                                                                                                                                                      |
| `top_p`        | number              | Nie      | Parametr próbkowania top-p.                                                                                                                                                                                         |
| `latency`      | string              | Nie      | `normal` lub `balanced`, domyślnie automatycznie uzupełniane przez ten interfejs jako `normal` (przesłanie pustego ciągu spowoduje odrzucenie przez upstream).                                                      |
| `normalize`    | boolean             | Nie      | Czy znormalizować tekst.                                                                                                                                                                                            |
| `callback_url` | string              | Nie      | Adres asynchronicznego wywołania zwrotnego, szczegóły w sekcji „Asynchroniczne wywołanie zwrotne”. **To jest rozszerzenie w stosunku do oficjalnego interfejsu**.                                                   |

> Nazewnictwo pól jest całkowicie zgodne z upstream. Z wyjątkiem `callback_url`, pozostałe pola mają takie same znaczenie i wartości jak w [oficjalnej dokumentacji TTS Fish](https://docs.fish.audio/text-to-speech/text-to-speech).

## Przykład 1: Minimalne żądanie (`text` + `format=mp3`)

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Hello world.",
    "format": "mp3"
  }'
```

Odpowiedź (testowana):

```json theme={null}
{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/e2ffcc06-18da-4a8c-b9aa-9337d0f9ec1d.mp3"
}
```

`audio_url` wskazuje na CDN tej platformy, można bezpośrednio pobrać lub odtworzyć w `<audio>`. Link jest długoterminowy, ale nadal zaleca się przechowywanie kopii w swoim własnym magazynie.

## Przykład 2: Użycie klonowanego głosu `reference_id`

Poniżej użyto jednego z publicznych głosów hiszpańskich na platformie Fish (`_id` można uzyskać za pomocą [Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query)):

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Hermanos míos, hoy es un buen día.",
    "reference_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
    "format": "mp3"
  }'
```

Odpowiedź (testowana):

```json theme={null}
{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/b6f161f2-a100-4818-add2-47694f234659.mp3"
}
```

## Przykład 3: Regulacja prędkości / głośności (`prosody`)

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Faster speech with prosody overrides.",
    "prosody": { "speed": 1.2, "volume": 0 },
    "format": "mp3"
  }'
```

Odpowiedź (testowana):

```json theme={null}
{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3"
}
```

`speed` większe niż 1 przyspiesza, mniejsze niż 1 spowalnia; `volume` w dB, 0 oznacza brak zmian, liczby dodatnie to wzmocnienie, liczby ujemne to osłabienie.

## Przykład 4: Zmiana modelu + kontrola bitrate

Przez nagłówek HTTP `model: s1` przełączamy się na model stabilny, dodajemy `mp3_bitrate: 128` w ciele żądania, aby kontrolować bitrate MP3:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s1' \
  -d '{
    "text": "wysoka jakość mp3",
    "format": "mp3",
    "mp3_bitrate": 128
  }'
```

Zwróć (testowane):

```json theme={null}
{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/7e7abf3d-3d72-4c9f-8eb6-8af932d7c96e.mp3"
}
```

## Przykład 5: PCM surowa fala

W przypadku, gdy potrzebujesz na bieżąco łączyć w przeglądarce lub przeprowadzać dalsze przetwarzanie (miksowanie, zmiana prędkości) po stronie klienta, zaleca się użycie `pcm`:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "cześć",
    "format": "pcm",
    "sample_rate": 16000
  }'
```

Zwróć (testowane):

```json theme={null}
{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/64adc04b-c196-4a0f-9070-222ba101ce6c.wav"
}
```

> Rozszerzenie linku podąża za `format` w żądaniu: `mp3` daje `.mp3`, `wav` i `pcm` daje `.wav` (kontener WAV, 16 bit PCM).

## Asynchroniczny callback (`callback_url`)

Dla długich tekstów, jednorazowa synteza może zająć od kilkunastu do kilkudziesięciu sekund, jeśli połączenie zostanie przerwane, należy spróbować ponownie. Po przesłaniu `callback_url` w ciele żądania, interfejs natychmiast zwróci `{task_id, started_at}`, a gdy zadanie zostanie zakończone, pełny wynik zostanie zwrócony w formacie POST JSON na ten URL, z tym samym `task_id` w ciele żądania.

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Dziś pogoda jest naprawdę ładna, chodźmy na spacer.",
    "format": "mp3",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'
```

Natychmiastowa odpowiedź (testowane):

```json theme={null}
{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "started_at": 1778462584.742
}
```

Później `callback_url` otrzyma coś w stylu:

```json theme={null}
{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/bd66b8c5-7543-4557-b684-baa72407e336.mp3"
}
```

Można również użyć [Fish Tasks API](https://platform.acedata.cloud/documents/fish-tasks) do aktywnego pobierania wyników według `task_id`, szczegóły w tym dokumencie.

## Obsługa błędów

* `400 token_mismatched`: Brakujące lub nieprawidłowe parametry żądania (najczęściej `text` jest pusty lub `format` ma wartość inną niż `mp3`/`wav`/`pcm`).
* `401 invalid_token`: Token autoryzacyjny nie istnieje lub jest nieprawidłowy.
* `429 too_many_requests`: Przekroczenie limitu szybkości konta.
* `500 api_error`: Błąd wewnętrzny serwera.

Przykład odpowiedzi błędu:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "pobieranie nie powiodło się"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

Błędy walidacji parametrów umieszczają oryginalny komunikat błędu pydantic w polu `message`, co ułatwia zlokalizowanie, który parametr jest nieprawidłowy, na przykład:

```json theme={null}
{
  "status": 400,
  "message": "[{\"type\":\"literal_error\",\"loc\":[\"format\"],\"msg\":\"Wprowadzenie powinno być 'pcm' lub 'mp3'\",\"input\":\"wav\"}]"
}
```

## Wnioski

Minimalny koszt integracji z Fish TTS to: w istniejącym kodzie wywołującym `api.fish.audio/v1/tts` zamienić autoryzację na token platformy i w ciele żądania **jawnie dodać** `format: "mp3"`. W przypadku długich tekstów zaleca się użycie asynchronicznego callbacku `callback_url`; w celu odkrycia `reference_id` dla klonowania głosu, należy skorzystać z [Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query) oraz [Fish Model Get](https://platform.acedata.cloud/documents/fish-model-get).