> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Fish TTS API Integrationsanleitung

> Fish voice generation API guide - Ace Data Cloud

Diese Schnittstelle basiert auf der [Fish Audio offiziellen TTS API](https://docs.fish.audio/text-to-speech/text-to-speech) und unterscheidet sich nur in der Authentifizierungsmethode (Verwendung des Tokens dieser Plattform) und der asynchronen Rückmeldung (Erweiterung `callback_url`), die Struktur des Anfragekörpers ist identisch mit der des Upstreams. Die Adresse lautet `POST https://api.acedata.cloud/fish/tts`.

## Antragsprozess

Um die Fish TTS API zu nutzen, müssen Sie zunächst im [Ace Data Cloud Dashboard](https://platform.acedata.cloud/console/applications) Ihr API-Token abrufen und für zukünftige Verwendung aufbewahren.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

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](https://platform.acedata.cloud/console/coin) das allgemeine Guthaben aufladen.

> 📘 Vollständige Dokumentation: [Fish TTS API →](https://platform.acedata.cloud/services/fish)

## 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 ist `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 kosten gleich viel. |

## Anfragekörperfelder

| Feld           | Typ       | Pflicht   | Beschreibung                                                                                                                                                                                                                                                    |                                                                                                                                                                                                                          |
| -------------- | --------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `text`         | string    | Ja        | Der zu synthetisierende Text, nicht leer.                                                                                                                                                                                                                       |                                                                                                                                                                                                                          |
| `format`       | string    | Ja        | Ausgabe-Audioformat. **Der Wert muss derzeit explizit angegeben werden**, wählbar `mp3` oder `pcm`. Selbst wenn die offizielle Dokumentation `wav`, `opus` auflistet, wird diese Schnittstelle vom Upstream mit `400 Input should be 'pcm' or 'mp3'` antworten. |                                                                                                                                                                                                                          |
| `reference_id` | string    | string\[] | Nein                                                                                                                                                                                                                                                            | Klon-Stimm-ID (kann über die [Fish Model API](https://platform.acedata.cloud/documents/fish-model) erstellt oder in der [Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query) abgerufen werden). |
| `references`   | object\[] | Nein      | Inline-Referenzproben, Struktur identisch mit dem Upstream, jede enthält `audio` und `text`. Entweder `reference_id` oder `references`.                                                                                                                         |                                                                                                                                                                                                                          |
| `sample_rate`  | integer   | Nein      | Abtastrate, häufig `16000`, `22050`, `44100`. `format=mp3` hat standardmäßig 44100.                                                                                                                                                                             |                                                                                                                                                                                                                          |
| `mp3_bitrate`  | integer   | Nein      | MP3-Bitrate, wählbar `64`, `128`, `192`. Nur wirksam bei `format=mp3`.                                                                                                                                                                                          |                                                                                                                                                                                                                          |
| `prosody`      | object    | Nein      | Prosodie-Übersteuerung, unterstützt `speed` (Sprechgeschwindigkeit, 1.0 ist die Originalgeschwindigkeit) und `volume` (Lautstärkeverstärkung in dB). Zum Beispiel `{"speed":1.2,"volume":0}`.                                                                   |                                                                                                                                                                                                                          |
| `chunk_length` | integer   | Nein      | Fragmentlänge des Upstreams, 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 (direktes Übermitteln eines leeren Strings wird vom Upstream abgelehnt).                                                                                     |                                                                                                                                                                                                                          |
| `normalize`    | boolean   | Nein      | Ob der Text normalisiert werden soll.                                                                                                                                                                                                                           |                                                                                                                                                                                                                          |
| `callback_url` | string    | Nein      | Asynchrone Rückmeldeadresse, siehe unten „Asynchrone Rückmeldung“. **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](https://docs.fish.audio/text-to-speech/text-to-speech).

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

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Hello world.",
    "format": "mp3"
  }'
```

Antwort (gemessen):

```json theme={null}
{
  "audio_url": "https://platform.r2.fish.audio/task/05f81919f2e04e35bb404a88fb177854.mp3"
}
```

`audio_url` ist der direkte Link von Fish R2, kann direkt mit GET heruntergeladen oder in `<audio>` abgespielt werden, die Signatur ist normalerweise innerhalb von 1 Stunde gültig, es wird empfohlen, nach dem Speichern in Ihren eigenen Objektspeicher zu übertragen.

## Beispiel 2: Verwendung der Klonstimme `reference_id`

Hier wird eine öffentliche spanische Stimme auf der Fish-Plattform verwendet (`_id` kann über die [Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query) abgerufen werden):

```shell theme={null}
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):

```json theme={null}
{
  "audio_url": "https://platform.r2.fish.audio/task/560078cf603d4584a2313ca4cd742056.mp3"
}
```

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

```shell theme={null}
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"
  }'
```

Antwort (gemessen):

```json theme={null}
{
  "audio_url": "https://platform.r2.fish.audio/task/f16759a3335748f1b4d1e56ed54d81dd.mp3"
}
```

`speed` größer als 1 beschleunigt, kleiner als 1 verlangsamt; `volume` in dB, 0 bedeutet unverändert, positive Zahlen verstärken, negative Zahlen 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:

```shell theme={null}
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):

```json theme={null}
{
  "audio_url": "https://platform.r2.fish.audio/task/6b660348776e40529e537aa30b1051d2.mp3"
}
```

## Beispiel 5: PCM Rohwelle

Für Szenarien, in denen eine Echtzeitverknüpfung im Browser oder eine nachträgliche Verarbeitung (Mixing, Geschwindigkeitsänderung) auf der Client-Seite erforderlich ist, wird die Verwendung von `pcm` empfohlen:

```shell theme={null}
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):

```json theme={null}
{
  "audio_url": "https://platform.r2.fish.audio/task/2052cc1f33b049d99a18fcc496f4462e.mp3"
}
```

> Die Erweiterung des aktuellen Antwortlinks ist fest auf `.mp3` eingestellt, der tatsächliche Inhalt ist der Byte-Stream, der im Antrag angegebenen `format`. Beim Herunterladen sollte entschieden werden, wie der Inhalt basierend auf dem `format` im Antrag zu interpretieren ist.

## Asynchrone Rückrufe (`callback_url`)

Die Synthese von langen Texten kann einige 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` im Anfragekörper enthalten ist.

```shell theme={null}
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):

```json theme={null}
{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "started_at": "2026-05-11T01:23:04.742Z"
}
```

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

```json theme={null}
{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "audio_url": "https://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
}
```

Es kann auch die [Fish Tasks API](https://platform.acedata.cloud/documents/fish-tasks) 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 wird `format` vergessen oder `text` ist leer).
* `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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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` sollte die [Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query) und [Fish Model Get](https://platform.acedata.cloud/documents/fish-model-get) verwendet werden.