Instrukcja integracji API Fish TTS

Ten interfejs oferuje konwersję tekstu na mowę, wywoływanie zapisanych głosów oraz jednorazowe natychmiastowe klonowanie głosu, pod adresem POST https://api.acedata.cloud/fish/tts.

Proces składania wniosku

Aby korzystać z Fish TTS API, najpierw przejdź do konsoli Ace Data Cloud, aby uzyskać swój API Token i zachować go na później.

Jeśli nie jesteś jeszcze zalogowany lub zarejestrowany, nastąpi automatyczne przekierowanie na stronę logowania z zaproszeniem do rejestracji i zalogowania się, a po zakończeniu automatycznie wrócisz na bieżącą stronę. Jeden API Token umożliwia wywoływanie wszystkich usług platformy, bez konieczności składania osobnego wniosku dla każdej usługi. Przy pierwszym wniosku otrzymasz bezpłatny limit, aby wypróbować usługę za darmo; gdy limit będzie niewystarczający, możesz doładować uniwersalne saldo w konsoli.

📘 Pełna dokumentacja: Fish TTS API →

Nagłówki żądania

Header	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, do wyboru `s1`, `s2-pro` lub `s2.1-pro`, domyślnie `s2-pro`. `s2.1-pro` jest najnowszą generacją, `s2-pro` ma silną ekspresję; `s1` jest bardziej stabilny i rzadziej odbiega od tekstu przy długich tekstach. Wszystkie trzy mają tę samą cenę.

Pola treści żądania

Pole	Typ	Wymagane	Opis
`text`	string	Tak	Tekst do syntezy, niepusty ciąg znaków.
`format`	string	Nie	Format wyjściowego audio, do wyboru `mp3` (domyślnie), `wav`, `pcm`. Zarówno `wav`, jak i `pcm` zwracają kontener WAV. `opus` nie jest obsługiwany i jego przekazanie bezpośrednio zwróci `400`.
`reference_id`	string \| string[]	Nie	ID modelu zapisanego lub publicznego głosu, które można utworzyć przez Fish Model API lub wyszukać w Fish Model Query. Nie można używać jednocześnie z `references`.
`references`	object[]	Nie	Jednorazowe natychmiastowe klonowanie głosu, obsługuje tylko jedną próbkę `{audio, text}`: `audio` to publiczny adres URL HTTPS MP3/WAV, a `text` to dokładna transkrypcja audio słowo w słowo. Nie można używać jednocześnie z `reference_id`.
`sample_rate`	integer	Nie	Częstotliwość próbkowania, często używane `16000`, `22050`, `44100`. Domyślnie dla `format=mp3` jest 44100.
`mp3_bitrate`	integer	Nie	Przepływność MP3, do wyboru `64`, `128`, `192`. Działa tylko dla `format=mp3`.
`prosody`	object	Nie	Zastąpienie prozodii, obsługuje `speed` (szybkość mowy, 1.0 to prędkość oryginalna) i `volume` (wzmocnienie głośności w dB). Na przykład `{"speed":1.2,"volume":0}`.
`chunk_length`	integer	Nie	Długość fragmentu upstream, domyślnie określana 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`, jeśli brak, ten interfejs automatycznie uzupełnia `normal` (bezpośrednie przekazanie pustego ciągu zostanie odrzucone przez upstream).
`normalize`	boolean	Nie	Czy normalizować tekst.
`callback_url`	string	Nie	Adres asynchronicznego callbacku, szczegóły poniżej w sekcji „Asynchroniczny callback”. Jest to rozszerzenie względem oficjalnego interfejsu.

Jednorazowe klonowanie akceptuje wyłącznie adresy URL audio HTTPS, nie akceptuje MessagePack, Base64, data URI ani adresów URL z poświadczeniami. Zalecany czas trwania referencyjnego audio to 10–270 sekund; Studio używa bardziej konserwatywnego zakresu 10–60 sekund.

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://cdn.acedata.cloud/assets/examples/fish/e2ffcc06-18da-4a8c-b9aa-9337d0f9ec1d-230825dfc559.mp3"
}

audio_url wskazuje na CDN tej platformy i można go bezpośrednio pobrać przez GET lub odtworzyć w <audio>. Końcowa pomyślna odpowiedź zwróci również najwyższego poziomu cost, gdzie amount to faktycznie odjęte Credits dla tego wywołania; jeśli istnieje zniżka na koncie, list_amount oznacza limit przed zniżką. Link jest dostępny przez długi czas, ale nadal zaleca się zachowanie kopii we własnej pamięci.

Przykład 2: użycie sklonowanego głosu `reference_id`

Poniżej użyto publicznego hiszpańskiego głosu na platformie Fish (_id można uzyskać przez wyszukiwanie w 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://cdn.acedata.cloud/assets/examples/fish/b6f161f2-a100-4818-add2-47694f234659-6532864739de.mp3"
}

Przykład 3: jednorazowe natychmiastowe klonowanie głosu (`references`)

Umieść referencyjne audio pod publicznym adresem HTTPS i podaj dokładny oryginalny tekst faktycznie wypowiedziany w nim. Ten głos jest używany tylko do tej syntezy i nie utworzy trwałego modelu:

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "新的旅程从这一刻开始，让我们一起向前。",
    "format": "mp3",
    "references": [{
      "audio": "https://cdn.acedata.cloud/assets/examples/fish/6220d605-39d0-4d43-9e58-0f12949dc9b9-570cfdf96ad9.mp3",
      "text": "春天的清晨，阳光穿过树叶，落在安静的小路上。"
    }]
  }'

Pomyślna odpowiedź z testu rzeczywistego:

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/995dfe37-b187-474d-8323-b08d6678ed8f-6359be9f8873.mp3",
  "cost": {"amount": 0.007609319999999999, "currency": "credit"}
}

Metoda	Cykl życia	Scenariusze zastosowania
`references`	Tylko dla bieżącego żądania TTS	Tymczasowe użycie lub inny głos za każdym razem
`reference_id`	Może być używany wielokrotnie	Głosy publiczne lub długoterminowe głosy utworzone przez `/fish/model`

Przykład 3: Regulacja szybkości mowy / 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ź (test rzeczywisty):

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3"
}

speed większe niż 1 przyspiesza, mniejsze niż 1 zwalnia; jednostką volume jest dB, 0 oznacza brak zmian, liczba dodatnia oznacza wzmocnienie, a ujemna tłumienie.

Przykład 5: Przełączanie modelu + kontrola bitrate’u

Przełącz na stabilny model poprzez nagłówek HTTP model: s1, a w treści żądania dodaj mp3_bitrate: 128, 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": "high bitrate mp3",
    "format": "mp3",
    "mp3_bitrate": 128
  }'

Odpowiedź (test rzeczywisty):

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/7e7abf3d-3d72-4c9f-8eb6-8af932d7c96e-6f11bf2f30e9.mp3"
}

Przykład 6: Surowa fala PCM

W scenariuszach, w których konieczne jest wykonywanie łączenia w czasie rzeczywistym w przeglądarce lub dalsze przetwarzanie po stronie klienta (miksowanie, zmiana prędkości), 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": "hi",
    "format": "pcm",
    "sample_rate": 16000
  }'

Odpowiedź (test rzeczywisty):

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/64adc04b-c196-4a0f-9070-222ba101ce6c-fc50de38c165.wav"
}

Rozszerzenie linku jest zgodne z format w żądaniu: mp3 daje .mp3, a wav i pcm dają .wav (kontener WAV, 16-bit PCM).

Asynchroniczne wywołanie zwrotne (`callback_url`)

Jednorazowa synteza długiego tekstu może wymagać od kilkunastu do kilkudziesięciu sekund; jeśli połączenie zostanie przerwane, wymagane jest ponowienie próby. Po przekazaniu callback_url w treści żądania interfejs natychmiast zwróci {task_id, started_at}, a po rzeczywistym zakończeniu po stronie upstream pełny wynik zostanie wywołany zwrotnie do tego URL w formie POST JSON, z tym samym task_id i końcowym najwyższopoziomowym cost naliczonym za to wywołanie. Początkowe potwierdzenie zadania nie zakończyło jeszcze syntezy, dlatego nie zawiera cost.

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。",
    "format": "mp3",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'

Natychmiastowa odpowiedź (test rzeczywisty):

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

Nieco później callback_url otrzyma coś w formie:

{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/bd66b8c5-7543-4557-b684-baa72407e336-52f2e79732f2.mp3"
}

Można również aktywnie pobrać wynik według task_id za pomocą Fish Tasks API; response.cost w rekordzie stanu końcowego jest zgodne z cost w wywołaniu zwrotnym, szczegóły znajdują się w tej dokumentacji.

Obsługa błędów

400 token_mismatched: Parametry żądania są brakujące lub nieprawidłowe (najczęściej text jest puste albo format ma wartość inną niż mp3/wav/pcm).
401 invalid_token: Token uwierzytelniający nie istnieje lub jest nieprawidłowy.
429 too_many_requests: Został uruchomiony limit częstotliwości konta.
500 api_error: Wewnętrzny błąd serwera.

Przykład odpowiedzi błędu:

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Błędy walidacji parametrów opisują nieprawidłowe pole w polu message, na przykład:

{
  "status": 400,
  "message": "[{\"type\":\"literal_error\",\"loc\":[\"format\"],\"msg\":\"Input should be 'pcm' or 'mp3'\",\"input\":\"wav\"}]"
}

Wnioski

Minimalny koszt integracji Fish TTS to: w istniejącym kodzie wywołującym api.fish.audio/v1/tts zastąpić uwierzytelnianie tokenem tej platformy oraz jawnie dodać format: "mp3" w treści żądania. W przypadku długiego tekstu zaleca się użycie asynchronicznego wywołania zwrotnego callback_url; aby znaleźć reference_id dla sklonowanego głosu, skorzystaj z Fish Model Query oraz Fish Model Get.

Getting Started

Czat AI

Obraz AI

Wideo AI

Audio AI

Sieć i dane

CAPTCHA

Tożsamość

Coding

Więcej przewodników

Instrukcja integracji API Fish TTS

Proces składania wniosku

Nagłówki żądania

Pola treści żądania

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

Przykład 2: użycie sklonowanego głosu `reference_id`

Przykład 3: jednorazowe natychmiastowe klonowanie głosu (`references`)

Przykład 3: Regulacja szybkości mowy / głośności (`prosody`)

Przykład 5: Przełączanie modelu + kontrola bitrate’u

Przykład 6: Surowa fala PCM

Asynchroniczne wywołanie zwrotne (`callback_url`)

Obsługa błędów

Wnioski

​Proces składania wniosku

​Nagłówki żądania

​Pola treści żądania

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

​Przykład 2: użycie sklonowanego głosu reference_id

​Przykład 3: jednorazowe natychmiastowe klonowanie głosu (references)

​Przykład 3: Regulacja szybkości mowy / głośności (prosody)

​Przykład 5: Przełączanie modelu + kontrola bitrate’u

​Przykład 6: Surowa fala PCM

​Asynchroniczne wywołanie zwrotne (callback_url)

​Obsługa błędów

​Wnioski

Proces składania wniosku

Nagłówki żądania

Pola treści żądania

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

Przykład 2: użycie sklonowanego głosu `reference_id`

Przykład 3: jednorazowe natychmiastowe klonowanie głosu (`references`)

Przykład 3: Regulacja szybkości mowy / głośności (`prosody`)

Przykład 5: Przełączanie modelu + kontrola bitrate’u

Przykład 6: Surowa fala PCM

Asynchroniczne wywołanie zwrotne (`callback_url`)

Obsługa błędów

Wnioski