Przejdź do głównej treści

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.

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: 
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ź: 
{
  "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: 
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: 
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ź: 
{
  "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "started_at": "2025-05-09T12:34:56.789Z"
}
Po chwili callback_url otrzyma pełny wynik: 
{
  "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 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

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