Fish TTS API Integrationsanleitung

Diese Schnittstelle bietet Text-zu-Sprache, Aufruf gespeicherter Stimmen und einmaliges sofortiges Stimmenklonen. Die Adresse lautet POST https://api.acedata.cloud/fish/tts.

Antragsprozess

Um die Fish TTS API zu verwenden, rufen Sie zunächst die Ace Data Cloud-Konsole auf, um Ihren API-Token zu erhalten, und bewahren Sie ihn als Reserve auf.

Wenn Sie sich noch nicht angemeldet oder registriert haben, werden Sie automatisch zur Anmeldeseite weitergeleitet, auf der Sie zur Registrierung und Anmeldung eingeladen werden. Nach Abschluss kehren Sie automatisch zur aktuellen Seite zurück. Ein API-Token kann alle Dienste der Plattform aufrufen, ohne dass für jeden Dienst ein separater Antrag erforderlich ist. Beim ersten Antrag wird ein kostenloses Guthaben verschenkt, das kostenlos getestet werden kann; bei unzureichendem Guthaben kann in der Konsole allgemeines Guthaben aufgeladen werden.

📘 Vollständige Dokumentation: Fish TTS API →

Request-Header

Header	Erforderlich	Beschreibung
`authorization`	Ja	`Bearer {token}`, wobei `{token}` der auf dieser Plattform beantragte Schlüssel ist.
`content-type`	Ja	`application/json`.
`accept`	Nein	`application/json`.
`model`	Nein	TTS-Modell, optional `s1`, `s2-pro` oder `s2.1-pro`, Standard ist `s2-pro`. `s2.1-pro` ist die neueste Generation, `s2-pro` ist ausdrucksstark; `s1` ist stabiler und weicht bei langen Texten nicht leicht ab. Alle drei haben denselben Preis.

Request-Body-Felder

Feld	Typ	Erforderlich	Beschreibung
`text`	string	Ja	Der zu synthetisierende Text, eine nicht leere Zeichenfolge.
`format`	string	Nein	Ausgabe-Audioformat, optional `mp3` (Standard), `wav`, `pcm`. Sowohl `wav` als auch `pcm` geben einen WAV-Container zurück. `opus` wird nicht unterstützt und gibt bei Übergabe direkt `400` zurück.
`reference_id`	string \| string[]	Nein	Die Modell-ID einer gespeicherten oder öffentlichen Stimme, die über die Fish Model API erstellt oder in der Fish Model Query abgerufen werden kann. Kann nicht gleichzeitig mit `references` verwendet werden.
`references`	object[]	Nein	Einmaliges sofortiges Stimmenklonen, unterstützt nur ein `{audio, text}`-Beispiel: `audio` ist eine öffentliche HTTPS-MP3/WAV-URL, `text` ist die genaue wortgetreue Abschrift des Audios. Kann nicht gleichzeitig mit `reference_id` verwendet werden.
`sample_rate`	integer	Nein	Abtastrate, häufig verwendet werden `16000`, `22050`, `44100`. `format=mp3` verwendet standardmäßig 44100.
`mp3_bitrate`	integer	Nein	MP3-Bitrate, optional `64`, `128`, `192`. Wirkt nur bei `format=mp3`.
`prosody`	object	Nein	Prosodie-Überschreibung, unterstützt `speed` (Sprechgeschwindigkeit, 1.0 ist Originalgeschwindigkeit) und `volume` (Lautstärkeverstärkung in dB). Zum Beispiel `{"speed":1.2,"volume":0}`.
`chunk_length`	integer	Nein	Länge der Upstream-Segmente, standardmäßig vom Upstream bestimmt.
`temperature`	number	Nein	Sampling-Temperatur, Bereich etwa 0.0–1.0.
`top_p`	number	Nein	Top-p-Sampling-Parameter.
`latency`	string	Nein	`normal` oder `balanced`, bei Auslassung ergänzt diese Schnittstelle automatisch `normal` (bei direkter Übergabe einer leeren Zeichenfolge lehnt der Upstream ab).
`normalize`	boolean	Nein	Ob der Text normalisiert werden soll.
`callback_url`	string	Nein	Asynchrone Callback-Adresse, siehe unten unter „Asynchroner Callback“. Dies ist eine Erweiterung gegenüber der offiziellen Schnittstelle.

Einmaliges Klonen akzeptiert nur HTTPS-Audio-URLs und akzeptiert kein MessagePack, Base64, data URI oder URLs mit Anmeldedaten. Für Referenzaudio werden 10–270 Sekunden empfohlen; Studio verwendet den konservativeren Bereich von 10–60 Sekunden.

Beispiel 1: Minimaler Request (`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"
  }'

Rückgabe (getestet):

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/e2ffcc06-18da-4a8c-b9aa-9337d0f9ec1d-230825dfc559.mp3"
}

audio_url verweist auf das CDN dieser Plattform und kann direkt per GET heruntergeladen oder in <audio> abgespielt werden. Die endgültige erfolgreiche Antwort gibt außerdem das oberste cost zurück, wobei amount die tatsächlich für diesen Vorgang abgezogenen Credits darstellt; falls es einen Kontorabatt gibt, zeigt list_amount das Guthaben vor dem Rabatt an. Der Link ist langfristig verfügbar, dennoch wird empfohlen, eine Kopie in Ihrem eigenen Speicher aufzubewahren.

Beispiel 2: Verwendung der geklonten Stimme `reference_id`

Im Folgenden wird eine öffentliche spanische Stimme auf der Fish-Plattform verwendet (_id kann über Fish Model Query abgerufen werden):

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

Rückgabe (getestet):

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/b6f161f2-a100-4818-add2-47694f234659-6532864739de.mp3"
}

Beispiel 3: Einmaliges sofortiges Stimmenklonen (`references`)

Legen Sie das Referenzaudio unter einer öffentlichen HTTPS-Adresse ab und geben Sie den darin tatsächlich gesprochenen genauen Originaltext an. Diese Stimme wird nur für diese Synthese verwendet und erstellt kein langfristiges Modell:

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": "春天的清晨，阳光穿过树叶，落在安静的小路上。"
    }]
  }'

Erfolgreiche Testantwort:

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

Methode	Lebenszyklus	Geeignete Szenarien
`references`	Nur für diese TTS-Anfrage	Temporäre Nutzung oder bei jedes Mal unterschiedlicher Stimme
`reference_id`	Wiederverwendbar	Öffentliche Stimmen oder langfristige Stimmen, die über `/fish/model` erstellt wurden

Beispiel 3: Sprechgeschwindigkeit / Lautstärke anpassen (`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"
  }'

Rückgabe (getestet):

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

speed größer als 1 beschleunigt, kleiner als 1 verlangsamt; die Einheit von volume ist dB, 0 bedeutet unverändert, positive Werte verstärken, negative Werte dämpfen.

Beispiel 5: Modell wechseln + Bitrate steuern

Wechseln Sie über den HTTP-Header model: s1 zum stabilen Modell und fügen Sie im Request-Body mp3_bitrate: 128 hinzu, um die MP3-Bitrate zu steuern:

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

Rückgabe (getestet):

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

Beispiel 6: PCM-Rohwellenform

Für Szenarien, in denen Echtzeit-Zusammenfügung im Browser erforderlich ist oder eine nachträgliche Verarbeitung auf dem Client (Mischen, Geschwindigkeitsänderung) erfolgt, wird die Verwendung von pcm empfohlen:

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

Rückgabe (getestet):

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

Die Erweiterung des Links folgt dem format in der Anfrage: mp3 ergibt .mp3, wav und pcm ergeben .wav (WAV-Container, 16-Bit-PCM).

Asynchroner Callback (`callback_url`)

Die Synthese eines langen Textes kann einmalig mehrere zehn Sekunden dauern; wenn die Verbindung unterbrochen wird, muss erneut versucht werden. Nach Übergabe von callback_url im Request-Body gibt die Schnittstelle sofort {task_id, started_at} zurück. Wenn der Upstream tatsächlich abgeschlossen ist, wird das vollständige Ergebnis als POST-JSON an diese URL zurückgerufen, wobei der Request-Body dieselbe task_id und den endgültig für diesen Durchlauf abgerechneten cost der obersten Ebene enthält. Die anfängliche Aufgabenbestätigung enthält noch keinen cost, da die Synthese noch nicht abgeschlossen ist.

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

Sofortige Rückgabe (getestet):

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

Etwas später erhält callback_url etwa Folgendes:

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

Sie können auch die Fish Tasks API verwenden, um das Ergebnis aktiv anhand von task_id abzurufen; der response.cost im Endstatus-Datensatz stimmt mit dem cost im Callback überein, siehe dazu dieses Dokument.

Fehlerbehandlung

400 token_mismatched: Anfrageparameter fehlen oder sind ungültig (am häufigsten ist text leer oder format enthält einen anderen Wert als mp3/wav/pcm).
401 invalid_token: Der Authentifizierungs-Token existiert nicht oder ist ungültig.
429 too_many_requests: Das Ratenlimit des Kontos wurde ausgelöst.
500 api_error: Interner Serverfehler.

Beispiel für eine Fehlerantwort:

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

Fehler bei der Parameterprüfung erläutern das ungültige Feld im Feld message, zum Beispiel:

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

Fazit

Der minimale Aufwand zur Integration von Fish TTS besteht darin, im vorhandenen Code, der api.fish.audio/v1/tts aufruft, die Authentifizierung durch den Token dieser Plattform zu ersetzen und im Request-Body explizit format: "mp3" mitzugeben. Für Szenarien mit langen Texten wird der asynchrone Callback callback_url empfohlen; für die Ermittlung von reference_id geklonter Stimmfarben verwenden Sie bitte Fish Model Query und Fish Model Get.

Erste Schritte

KI Chat

KI Bild

KI Video

KI Audio

Web & Daten

CAPTCHA

Identität

Coding

Weitere Anleitungen

Fish TTS API Integrationsanleitung

Antragsprozess

Request-Header

Request-Body-Felder

Beispiel 1: Minimaler Request (`text` + `format=mp3`)

Beispiel 2: Verwendung der geklonten Stimme `reference_id`

Beispiel 3: Einmaliges sofortiges Stimmenklonen (`references`)

Beispiel 3: Sprechgeschwindigkeit / Lautstärke anpassen (`prosody`)

Beispiel 5: Modell wechseln + Bitrate steuern

Beispiel 6: PCM-Rohwellenform

Asynchroner Callback (`callback_url`)

Fehlerbehandlung

Fazit

​Antragsprozess

​Request-Header

​Request-Body-Felder

​Beispiel 1: Minimaler Request (text + format=mp3)

​Beispiel 2: Verwendung der geklonten Stimme reference_id

​Beispiel 3: Einmaliges sofortiges Stimmenklonen (references)

​Beispiel 3: Sprechgeschwindigkeit / Lautstärke anpassen (prosody)

​Beispiel 5: Modell wechseln + Bitrate steuern

​Beispiel 6: PCM-Rohwellenform

​Asynchroner Callback (callback_url)

​Fehlerbehandlung

​Fazit

Antragsprozess

Request-Header

Request-Body-Felder

Beispiel 1: Minimaler Request (`text` + `format=mp3`)

Beispiel 2: Verwendung der geklonten Stimme `reference_id`

Beispiel 3: Einmaliges sofortiges Stimmenklonen (`references`)

Beispiel 3: Sprechgeschwindigkeit / Lautstärke anpassen (`prosody`)

Beispiel 5: Modell wechseln + Bitrate steuern

Beispiel 6: PCM-Rohwellenform

Asynchroner Callback (`callback_url`)

Fehlerbehandlung

Fazit