Fish TTS API Integracja Opis

Ten interfejs oferuje konwersję tekstu na mowę, wywołanie zapisanych dźwięków oraz jednorazowe klonowanie dźwięku w czasie rzeczywistym, 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, zachowując go na później.

Jeśli nie jesteś zalogowany lub zarejestrowany, automatycznie zostaniesz przekierowany na stronę logowania, aby zarejestrować się i zalogować, a 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}`，`{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ściowego 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 modelu zapisanych lub publicznych dźwięków, które można utworzyć za pomocą Fish Model API lub wyszukać w Fish Model Query. Nie można używać jednocześnie z `references`.
`references`	object[]	Nie	Jednorazowe klonowanie dźwięku w czasie rzeczywistym, obsługuje tylko jeden `{audio, text}` przykład: `audio` to publiczny HTTPS MP3/WAV URL, `text` to dokładny transkrypt audio. Nie można używać jednocześnie z `reference_id`.
`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, obsługuje `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, w zakresie 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 rozszerzenie w stosunku do oficjalnego interfejsu。

Jednorazowe klonowanie akceptuje tylko HTTPS audio URL, nie akceptuje MessagePack, Base64, data URI ani 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://platform2.cdn.acedata.cloud/fish/e2ffcc06-18da-4a8c-b9aa-9337d0f9ec1d.mp3"
}

audio_url wskazuje na CDN tej platformy, można go bezpośrednio pobrać za pomocą GET lub odtworzyć w <audio>. Ostateczna odpowiedź sukcesu zwróci również górny cost, w którym amount to rzeczywista kwota odjęta z kredytów; jeśli są zniżki na koncie, list_amount oznacza kwotę przed zniżką. Link jest dostępny przez długi czas, ale nadal zaleca się przechowywanie kopii w swoim własnym magazynie.

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

Poniżej użyto jednego z publicznych głosów w języku hiszpańskim 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: Jednorazowe klonowanie dźwięku (`references`)

Umieść referencyjny dźwięk w publicznym adresie HTTPS i podaj dokładny oryginalny tekst, który został faktycznie wypowiedziany. Ten dźwięk jest używany tylko do tej syntezy i nie stworzy długoterminowego 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://platform2.cdn.acedata.cloud/fish/6220d605-39d0-4d43-9e58-0f12949dc9b9.mp3",
      "text": "春天的清晨，阳光穿过树叶，落在安静的小路上。"
    }]
  }'

Testowana odpowiedź sukcesu:

{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/995dfe37-b187-474d-8323-b08d6678ed8f.mp3",
  "cost": {"amount": 0.007609319999999999, "currency": "kredyt"}
}

方式	生命周期	适用场景
`references`	仅本次 TTS 请求	Tymczasowe użycie lub różne dźwięki za każdym razem
`reference_id`	可重复使用	Publiczne dźwięki lub długoterminowe dźwięki utworzone przez `/fish/model`

示例 3：调节语速 / 音量（`prosody`）

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Szybsza mowa z nadpisaniami prosody.",
    "prosody": { "speed": 1.2, "volume": 0 },
    "format": "mp3"
  }'

返回（实测）：

{
  "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, ujemne to osłabienie.

示例 5：切换模型 + 控制码率

通过 HTTP 头 model: s1 切换到稳定型模型，请求体中加 mp3_bitrate: 128 控制 MP3 码率：

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s1' \
  -d '{
    "text": "mp3 o wysokim bitrate",
    "format": "mp3",
    "mp3_bitrate": 128
  }'

返回（实测）：

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

示例 6：PCM 原始波形

需要在浏览器里做实时拼接、或在客户端做后续处理（混音、变速）的场景，推荐使用 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
  }'

返回（实测）：

{
  "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 dają .wav (kontener WAV, 16 bit PCM).

异步回调（`callback_url`）

长文本一次合成可能需要十几秒到几十秒，连接如果中断需要重试。请求体中传 callback_url 后，接口会立即返回 {task_id, started_at}，上游真正完成时把完整结果以 POST JSON 形式回调到该 URL，请求体中带同一个 task_id 和本次最终计费的顶层 cost。初始任务确认尚未完成合成，因此不包含 cost。

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"
  }'

立即返回（实测）：

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

稍后 callback_url 会收到形如：

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

也可以用 Fish Tasks API 主动按 task_id 拉取结果；终态记录的 response.cost 与回调中的 cost 一致，详见该文档。

错误处理

400 token_mismatched：请求参数缺失或不合法（最常见是 text 为空，或 format 传了 mp3/wav/pcm 之外的值）。
401 invalid_token：鉴权 token 不存在或无效。
429 too_many_requests：触发账号速率限制。
500 api_error：服务器内部错误。

错误响应示例：

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

参数校验错误会在 message 字段说明不合法的字段，例如：

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

结论

接入 Fish TTS 的最小代价是：在已有调用 api.fish.audio/v1/tts 的代码里把鉴权换成本平台 token，并在请求体里显式带上 format: "mp3"。长文本场景建议使用 callback_url 异步回调；对克隆音色 reference_id 的发现，请配合 Fish Model Query 与 Fish Model Get。

Getting Started

Czat AI

Obraz AI

Wideo AI

Audio AI

Sieć i dane

CAPTCHA

Tożsamość

Proxy

Advanced

Coding

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 klonowania głosu `reference_id`

Przykład 3: Jednorazowe klonowanie dźwięku (`references`)

示例 3：调节语速 / 音量（`prosody`）

示例 5：切换模型 + 控制码率

示例 6：PCM 原始波形

异步回调（`callback_url`）

错误处理

结论

​Proces aplikacji

​Nagłówki żądania

​Pola ciała żądania

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

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

​Przykład 3: Jednorazowe klonowanie dźwięku (references)

​示例 3：调节语速 / 音量（prosody）

​示例 5：切换模型 + 控制码率

​示例 6：PCM 原始波形

​异步回调（callback_url）

​错误处理

​结论

Proces aplikacji

Nagłówki żądania

Pola ciała żądania

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

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

Przykład 3: Jednorazowe klonowanie dźwięku (`references`)

示例 3：调节语速 / 音量（`prosody`）

示例 5：切换模型 + 控制码率

示例 6：PCM 原始波形

异步回调（`callback_url`）

错误处理

结论