Skip to main content
W tym dokumencie przedstawiono instrukcję integracji Fish TTS API. Interfejs ten jest w pełni kompatybilny z oficjalnym OpenAPI Fish Audio 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. 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:
Przykładowa odpowiedź:
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:

​
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:
Natychmiastowa odpowiedź:
Po chwili callback_url otrzyma pełny wynik:
Możesz też użyć Fish Tasks API 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

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