Fish TTS API Integracja Opis

Ten interfejs oparty jest na oficjalnym API TTS Fish Audio, 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, aby uzyskać swój token API, zachowaj go na przyszłość.

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.

📘 Pełna dokumentacja: Fish TTS API →

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 lub wyszukać w 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.

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

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):

{
  "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):

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):

{
  "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`)

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):

{
  "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:

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):

{
  "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:

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):

{
  "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.

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):

{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "started_at": 1778462584.742
}

Później callback_url otrzyma coś w stylu:

{
  "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 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:

{
  "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:

{
  "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 oraz Fish Model Get.

Getting Started

Czat AI

Obraz AI

Wideo AI

Audio AI

Sieć i dane

CAPTCHA

Tożsamość

Proxy

Advanced

Fish TTS API Integracja Opis

Proces aplikacji

Nagłówki żądania

Pola ciała żądania

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

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

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

Przykład 4: Zmiana modelu + kontrola bitrate

Przykład 5: PCM surowa fala

Asynchroniczny callback (`callback_url`)

Obsługa błędów

Wnioski

​Proces aplikacji

​Nagłówki żądania

​Pola ciała żądania

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

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

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

​Przykład 4: Zmiana modelu + kontrola bitrate

​Przykład 5: PCM surowa fala

​Asynchroniczny callback (callback_url)

​Obsługa błędów

​Wnioski

Proces aplikacji

Nagłówki żądania

Pola ciała żądania

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

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

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

Przykład 4: Zmiana modelu + kontrola bitrate

Przykład 5: PCM surowa fala

Asynchroniczny callback (`callback_url`)

Obsługa błędów

Wnioski