Fish TTS API Integrationsanleitung

Diese Schnittstelle basiert auf der Fish Audio offiziellen TTS API und unterscheidet sich nur in der Authentifizierungsmethode (Verwendung des Tokens dieser Plattform) und dem asynchronen Callback (Erweiterung callback_url), die Struktur des Anfragekörpers ist identisch mit der des upstream. Die Adresse lautet POST https://api.acedata.cloud/fish/tts.

Antragsprozess

Um die Fish TTS API zu verwenden, müssen Sie zunächst Ihr API-Token im Ace Data Cloud Dashboard abrufen und für zukünftige Verwendung aufbewahren.

Wenn Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, um sich zu registrieren und anzumelden. Nach Abschluss werden Sie automatisch zur aktuellen Seite zurückgeleitet. Ein API-Token reicht aus, um alle Dienste der Plattform zu nutzen, es ist nicht erforderlich, für jeden Dienst separat zu beantragen. Bei der ersten Beantragung erhalten Sie ein kostenloses Kontingent, um es kostenlos auszuprobieren; wenn das Kontingent nicht ausreicht, können Sie im Dashboard Ihr allgemeines Guthaben aufladen.

📘 Vollständige Dokumentation: Fish TTS API →

Anfrageheader

Header	Pflicht	Beschreibung
`authorization`	Ja	`Bearer {token}`; `{token}` ist der Schlüssel, der auf dieser Plattform beantragt wurde.
`content-type`	Ja	`application/json`.
`accept`	Nein	`application/json`.
`model`	Nein	TTS-Modell, wählbar zwischen `s1`, `s2-pro` oder `s2.1-pro`, Standard ist `s2-pro`. `s2.1-pro` ist die neueste Generation, `s2-pro` hat eine starke Ausdruckskraft; `s1` ist stabiler und weicht bei langen Texten nicht so leicht ab. Alle drei kosten gleich viel.

Anfragekörperfelder

Feld	Typ	Pflicht	Beschreibung
`text`	string	Ja	Der zu synthetisierende Text, nicht leer.
`format`	string	Nein	Ausgabe-Audioformat, wählbar zwischen `mp3` (Standard), `wav`, `pcm`. `wav` und `pcm` geben beide einen WAV-Container zurück. `opus` wird nicht unterstützt, eine Übertragung führt direkt zu `400`.
`reference_id`	string \| string[]	Nein	Klon-Stimm-ID (kann über die Fish Model API erstellt oder in der Fish Model Query abgerufen werden).
`references`	object[]	Nein	Inline-Referenzmuster, Struktur identisch mit dem upstream, jede enthält `audio` und `text`. Entweder `reference_id` oder `references`.
`sample_rate`	integer	Nein	Abtastrate, gängig sind `16000`, `22050`, `44100`. `format=mp3` hat standardmäßig `44100`.
`mp3_bitrate`	integer	Nein	MP3-Bitrate, wählbar zwischen `64`, `128`, `192`. Gilt nur für `format=mp3`.
`prosody`	object	Nein	Prosodie-Übersteuerung, unterstützt `speed` (Sprechgeschwindigkeit, 1.0 ist die Originalgeschwindigkeit) und `volume` (Lautstärkeverstärkung in dB). Beispiel `{"speed":1.2,"volume":0}`.
`chunk_length`	integer	Nein	Upstream-Chunk-Länge, standardmäßig vom Upstream bestimmt.
`temperature`	number	Nein	Abtasttemperatur, Bereich etwa 0.0–1.0.
`top_p`	number	Nein	top-p Abtastparameter.
`latency`	string	Nein	`normal` oder `balanced`, standardmäßig wird von dieser Schnittstelle automatisch `normal` ergänzt (direkte Übertragung eines leeren Strings wird vom Upstream abgelehnt).
`normalize`	boolean	Nein	Ob der Text normalisiert werden soll.
`callback_url`	string	Nein	Asynchrone Callback-Adresse, siehe unten „Asynchrone Rückrufe“. Dies ist eine Erweiterung der offiziellen Schnittstelle.

Die Feldbenennungen sind identisch mit dem upstream. Abgesehen von callback_url beziehen sich die anderen Felder auf die Bedeutungen und Werte in der Fish offiziellen TTS-Dokumentation.

Beispiel 1: Minimale Anfrage (`text` + `format=mp3`)

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Hallo Welt.",
    "format": "mp3"
  }'

Antwort (gemessen):

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

audio_url verweist auf das CDN dieser Plattform, kann direkt mit GET heruntergeladen oder in <audio> abgespielt werden. Der Link ist langfristig verfügbar, es wird jedoch empfohlen, eine Kopie in Ihrem eigenen Speicher zu behalten.

Beispiel 2: Verwendung der Klon-Stimme `reference_id`

Hier wird eine öffentliche spanische Stimme auf der Fish-Plattform verwendet (_id kann über die 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"
  }'

Antwort (gemessen):

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

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

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Schnelleres Sprechen mit Prosodie-Übersteuerungen.",
    "prosody": { "speed": 1.2, "volume": 0 },
    "format": "mp3"
  }'

Antwort (gemessen):

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

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

Beispiel 4: Modellwechsel + Steuerung der Bitrate

Durch den HTTP-Header model: s1 wird auf das stabile Modell gewechselt, im Anfragekörper wird mp3_bitrate: 128 hinzugefügt, 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": "hohe Bitrate mp3",
    "format": "mp3",
    "mp3_bitrate": 128
  }'

Rückgabe (gemessen):

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

Beispiel 5: PCM Rohwelle

Für Szenarien, in denen Echtzeit-Zusammenführung im Browser oder nachträgliche Verarbeitung (Mixing, Geschwindigkeitsänderung) auf der Client-Seite erforderlich ist, 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 (gemessen):

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

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

Asynchrone Rückrufe (`callback_url`)

Die Synthese von langen Texten kann mehrere Sekunden bis mehrere Minuten in Anspruch nehmen, und wenn die Verbindung unterbrochen wird, muss sie erneut versucht werden. Wenn callback_url im Anfragekörper übergeben wird, gibt die Schnittstelle sofort {task_id, started_at} zurück, und wenn die Verarbeitung tatsächlich abgeschlossen ist, wird das vollständige Ergebnis als POST-JSON an diese URL zurückgerufen, wobei der gleiche task_id im Anfragekörper enthalten ist.

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Heute ist das Wetter schön, lass uns spazieren gehen.",
    "format": "mp3",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'

Sofortige Rückgabe (gemessen):

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

Später wird callback_url eine Nachricht in folgender Form erhalten:

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

Es kann auch die Fish Tasks API verwendet werden, um aktiv Ergebnisse nach task_id abzurufen, siehe dazu die Dokumentation.

Fehlerbehandlung

400 token_mismatched: Fehlende oder ungültige Anfrageparameter (am häufigsten ist text leer oder format hat einen Wert, der nicht mp3/wav/pcm ist).
401 invalid_token: Authentifizierungstoken existiert nicht oder ist ungültig.
429 too_many_requests: Konto-Rate-Limit überschritten.
500 api_error: Interner Serverfehler.

Beispiel für eine Fehlerantwort:

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

Fehler bei der Parameterüberprüfung werden im message-Feld mit dem Originalfehlertext von pydantic angezeigt, um zu helfen, welches Feld ungültig ist, zum Beispiel:

{
  "status": 400,
  "message": "[{\"type\":\"literal_error\",\"loc\":[\"format\"],\"msg\":\"Eingabe sollte 'pcm' oder 'mp3' sein\",\"input\":\"wav\"}]"
}

Fazit

Die minimalen Kosten für die Integration von Fish TTS sind: In bestehendem Code, der api.fish.audio/v1/tts aufruft, das Authentifizierungstoken durch das Plattform-Token zu ersetzen und im Anfragekörper explizit format: "mp3" anzugeben. Für lange Textszenarien wird empfohlen, callback_url für asynchrone Rückrufe zu verwenden; zur Entdeckung von Klonstimmen reference_id sollten Fish Model Query und Fish Model Get verwendet werden.

Erste Schritte

KI Chat

KI Bild

KI Video

KI Audio

Web & Daten

CAPTCHA

Identität

Proxy

Erweitert

Fish TTS API Integrationsanleitung

Antragsprozess

Anfrageheader

Anfragekörperfelder

Beispiel 1: Minimale Anfrage (`text` + `format=mp3`)

Beispiel 2: Verwendung der Klon-Stimme `reference_id`

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

Beispiel 4: Modellwechsel + Steuerung der Bitrate

Beispiel 5: PCM Rohwelle

Asynchrone Rückrufe (`callback_url`)

Fehlerbehandlung

Fazit

​Antragsprozess

​Anfrageheader

​Anfragekörperfelder

​Beispiel 1: Minimale Anfrage (text + format=mp3)

​Beispiel 2: Verwendung der Klon-Stimme reference_id

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

​Beispiel 4: Modellwechsel + Steuerung der Bitrate

​Beispiel 5: PCM Rohwelle

​Asynchrone Rückrufe (callback_url)

​Fehlerbehandlung

​Fazit

Antragsprozess

Anfrageheader

Anfragekörperfelder

Beispiel 1: Minimale Anfrage (`text` + `format=mp3`)

Beispiel 2: Verwendung der Klon-Stimme `reference_id`

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

Beispiel 4: Modellwechsel + Steuerung der Bitrate

Beispiel 5: PCM Rohwelle

Asynchrone Rückrufe (`callback_url`)

Fehlerbehandlung

Fazit