Fish TTS API Integrationsanleitung

Diese Schnittstelle bietet Text-zu-Sprache, den Aufruf gespeicherter Stimmen und einmalige sofortige Sprachklonierung an, die Adresse lautet POST https://api.acedata.cloud/fish/tts。

Antragsprozess

Um die Fish TTS API zu nutzen, müssen Sie zunächst ein API-Token im Ace Data Cloud Dashboard anfordern 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 erschöpft ist, können Sie im Dashboard Ihr 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 `s1`、`s2-pro` oder `s2.1-pro`，Standard `s2-pro`。`s2.1-pro` ist die neueste Generation, `s2-pro` hat eine starke Ausdruckskraft; `s1` ist stabiler und bei langen Texten weniger anfällig für Abweichungen. Alle drei haben den gleichen Preis.

Anfragekörperfelder

Feld	Typ	Pflicht	Beschreibung
`text`	string	Ja	Der zu synthetisierende Text, nicht leere Zeichenfolge.
`format`	string	Nein	Ausgabe-Audioformat, wählbar `mp3`（Standard）、`wav`、`pcm`。`wav` und `pcm` geben beide ein WAV-Container zurück. `opus` wird nicht unterstützt, eine Eingabe führt direkt zu `400`.
`reference_id`	string \| string[]	Nein	Modell-ID von gespeicherten oder öffentlichen Stimmen, die über die Fish Model API erstellt werden kann oder in Fish Model Query abgerufen werden kann. Kann nicht gleichzeitig mit `references` verwendet werden.
`references`	object[]	Nein	Einmalige sofortige Sprachklonierung, unterstützt nur ein `{audio, text}`-Beispiel: `audio` ist eine öffentliche HTTPS MP3/WAV-URL, `text` ist das genaue Transkript des Audios. Kann nicht gleichzeitig mit `reference_id` verwendet werden.
`sample_rate`	integer	Nein	Abtastrate, häufig `16000`、`22050`、`44100`。`format=mp3` Standard ist 44100。
`mp3_bitrate`	integer	Nein	MP3-Bitrate, wählbar `64`、`128`、`192`。Gilt nur für `format=mp3`。
`prosody`	object	Nein	Prosodie-Überlagerung, unterstützt `speed`（Sprechgeschwindigkeit, 1.0 ist die Originalgeschwindigkeit）und `volume`（Lautstärkeverstärkung dB）。Beispiel `{"speed":1.2,"volume":0}`。
`chunk_length`	integer	Nein	Länge der upstream-Teile, standardmäßig von 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 von upstream abgelehnt).
`normalize`	boolean	Nein	Ob der Text normalisiert werden soll.
`callback_url`	string	Nein	Asynchrone Rückrufadresse, siehe unten „Asynchrone Rückrufe“. Dies ist eine Erweiterung der offiziellen Schnittstelle。

Einmalige Klonierung akzeptiert nur HTTPS-Audio-URLs, keine MessagePack-, Base64-, Data-URI- oder URL mit Anmeldeinformationen. Referenzaudio wird für 10–270 Sekunden empfohlen; Studio verwendet einen konservativeren Bereich von 10–60 Sekunden.

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 heruntergeladen oder in <audio> abgespielt werden. Die endgültige erfolgreiche Antwort enthält auch die oberste cost, wobei amount die tatsächlich abgezogenen Credits für diese Transaktion ist; bei Kontorabatten zeigt list_amount den Betrag vor dem Rabatt an. Der Link ist langfristig verfügbar, es wird jedoch empfohlen, eine Kopie in Ihrem eigenen Speicher aufzubewahren.

Beispiel 2: Verwendung des Klonstimmtyps `reference_id`

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

Antwort (gemessen):

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

Beispiel 3: Einmalige sofortige Sprachklonierung (`references`)

Legen Sie die Referenzaudio an einer öffentlichen HTTPS-Adresse ab und geben Sie den genauen Wortlaut an, der tatsächlich gesagt wurde. Diese Stimme wird nur für diese Synthese verwendet und es wird kein langfristiges Modell erstellt:

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "Neue Reise beginnt in diesem Moment, lassen Sie uns gemeinsam vorwärts gehen.",
    "format": "mp3",
    "references": [{
      "audio": "https://platform2.cdn.acedata.cloud/fish/6220d605-39d0-4d43-9e58-0f12949dc9b9.mp3",
      "text": "An einem Frühlingmorgen, die Sonne scheint durch die Blätter und fällt auf den ruhigen Weg."
    }]
  }'

Gemessene erfolgreiche Antwort:

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

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

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

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

Rückgabe (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 Zahlen erhöhen, negative Zahlen verringern.

Beispiel 5: Modell wechseln + Bitrate steuern

Durch den HTTP-Header model: s1 auf das stabile Modell wechseln, im Anfragekörper mp3_bitrate: 128 hinzufügen, 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 6: PCM Rohwelle

Für Szenarien, in denen Echtzeit-Zusammenführung im Browser oder nachträgliche Verarbeitung (Mixing, Geschwindigkeitsänderung) auf dem Client erforderlich ist, wird 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 langer Texte 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 in Form von POST JSON an diese URL zurückgerufen, wobei der gleiche task_id und die endgültigen Kosten im Anfragekörper enthalten sind. Die ursprüngliche Aufgabenbestätigung zeigt an, dass die Synthese noch nicht abgeschlossen ist, daher sind keine cost enthalten.

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Das Wetter ist heute 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 wie folgt 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; die endgültigen Aufzeichnungen der response.cost stimmen mit den Kosten im Rückruf überein, siehe das Dokument.

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

Parametervalidierungsfehler werden im message-Feld beschrieben, um ungültige Felder anzugeben, 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" hinzuzufügen. Für lange Textszenarien wird empfohlen, callback_url für asynchrone Rückrufe zu verwenden; zur Entdeckung von Klonstimmen reference_id sollte die 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

Coding

Fish TTS API Integrationsanleitung

Antragsprozess

Anfrageheader

Anfragekörperfelder

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

Beispiel 2: Verwendung des Klonstimmtyps `reference_id`

Beispiel 3: Einmalige sofortige Sprachklonierung (`references`)

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

Beispiel 5: Modell wechseln + Bitrate steuern

Beispiel 6: PCM Rohwelle

Asynchrone Rückrufe (`callback_url`)

Fehlerbehandlung

Fazit

​Antragsprozess

​Anfrageheader

​Anfragekörperfelder

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

​Beispiel 2: Verwendung des Klonstimmtyps reference_id

​Beispiel 3: Einmalige sofortige Sprachklonierung (references)

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

​Beispiel 5: Modell wechseln + Bitrate steuern

​Beispiel 6: PCM Rohwelle

​Asynchrone Rückrufe (callback_url)

​Fehlerbehandlung

​Fazit

Antragsprozess

Anfrageheader

Anfragekörperfelder

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

Beispiel 2: Verwendung des Klonstimmtyps `reference_id`

Beispiel 3: Einmalige sofortige Sprachklonierung (`references`)

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

Beispiel 5: Modell wechseln + Bitrate steuern

Beispiel 6: PCM Rohwelle

Asynchrone Rückrufe (`callback_url`)

Fehlerbehandlung

Fazit