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

# Fish TTS API Integrationsanleitung

> Fish music generation 集成指南 - XHuoAPI

Dieser Artikel beschreibt die Integrationsanleitung für die Fish TTS API. Diese Schnittstelle ist vollständig kompatibel mit der [offiziellen Fish Audio OpenAPI](https://docs.fish.audio/text-to-speech/text-to-speech) und ermöglicht es, bestehenden Code, der `https://api.fish.audio/v1/tts` aufruft, direkt auf `https://api.xhuoapi.ai/v1/fish/tts` zu migrieren. Es ist lediglich erforderlich, die Authentifizierungsinformationen auszutauschen, ohne die Struktur des Anfragekörpers ändern zu müssen.

## Antragsverfahren

Um die API nutzen zu können, müssen Sie zunächst auf der entsprechenden Seite der [Fish TTS API](https://api.xhuoapi.ai/services/caf99abc-ddcf-4714-b2a5-862d9b469509) den Dienst beantragen. Nach dem Aufruf der Seite klicken Sie auf die Schaltfläche „Acquire“.

Falls Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, um sich zu registrieren und anzumelden. Nach der Anmeldung kehren Sie automatisch zur ursprünglichen Seite zurück.

Bei der ersten Beantragung erhalten Sie ein kostenloses Kontingent, mit dem Sie die API kostenfrei nutzen können.

## Unterschiede zur offiziellen API

Diese API bietet auf Basis der offiziellen Fish Audio Anfrage- und Antwortfelder einige wenige Erweiterungen, um eine bessere Integration auf unserer Plattform zu ermöglichen:

* **Authentifizierungsmethode**: Verwendung von `Authorization: Bearer {token}`, wobei `{token}` der auf unserer Plattform beantragte Schlüssel ist und nicht der offizielle Fish-Schlüssel.
* **TTS-Modellauswahl**: Über den HTTP-Header `model` spezifizierbar, wählbar zwischen `s1` oder `s2-pro`, Standardwert ist `s2-pro`. Dies entspricht dem offiziellen Verhalten von Fish.
* **Standardwert für `latency`**: Die Upstream-API `/fish/v1/tts` gibt einen Fehler zurück, wenn `latency` nicht übergeben wird. Diese Schnittstelle ergänzt bei Fehlen automatisch `latency=normal`, was dem Standardverhalten von Fish entspricht.
* **Asynchrone Callback-Funktion (Plattformerweiterung)**: Wird im Anfragekörper zusätzlich das Feld `callback_url` übergeben, antwortet die API sofort mit `{task_id, started_at}`. Nach Abschluss der Verarbeitung sendet die Upstream-API das vollständige Ergebnis `{audio_url, ...}` als POST-JSON an die angegebene URL zurück. Die offizielle Fish-API unterstützt dieses Feld nicht; dessen Verwendung löst nur unseren asynchronen Ablauf aus.

Abgesehen von diesen Unterschieden werden alle Felder im TTS-Anfragekörper (`text`, `reference_id`, `references`, `prosody`, `format`, `sample_rate`, `mp3_bitrate`, `chunk_length`, `temperature`, `top_p` usw.) direkt an die Upstream-API weitergeleitet, das Verhalten entspricht vollständig der offiziellen Dokumentation.

## Grundlegende Nutzung

Die minimale Anfrage benötigt nur das Feld `text`. Ein Beispiel mit CURL:

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。"
  }'
```

Beispielhafte Antwort:

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

Die Antwort enthält direkt die offiziellen Fish-Felder, darunter:

* `audio_url`: URL der generierten Audiodatei, kann direkt heruntergeladen oder abgespielt werden.
* `latency_ms` (optional): Verarbeitungsdauer upstream in Millisekunden.

Wenn Sie eine Klonstimme verwenden möchten, können Sie im Anfragekörper `reference_id` hinzufügen:

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。",
    "reference_id": "d7900c21663f485ab63ebdb7e5905036",
    "format": "mp3",
    "sample_rate": 44100
  }'
```

## Asynchrone Callback-Funktion

Da die Generierung bei längeren Texten zeitintensiv sein kann und eine dauerhafte Verbindung Systemressourcen beansprucht, bietet diese API eine asynchrone Callback-Funktion (eine Erweiterung gegenüber der offiziellen Fish-API).

Der Ablauf ist folgender: Der Client übergibt im Anfragekörper zusätzlich das Feld `callback_url`. Die API antwortet sofort mit einer Antwort, die `task_id` enthält. Nach Abschluss der Generierung sendet die Upstream-API das finale Ergebnis mit `audio_url` und weiteren Feldern als POST-JSON an die `callback_url`. Im Anfragekörper der Callback-Anfrage ist ebenfalls die gleiche `task_id` enthalten, um das asynchrone Ergebnis mit der ursprünglichen Aufgabe zu verknüpfen.

Beispielanfrage:

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'
```

Sofortige Antwort:

```json theme={null}
{
  "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "started_at": "2025-05-09T12:34:56.789Z"
}
```

Nach kurzer Zeit erhält die `callback_url` das vollständige Ergebnis:

```json theme={null}
{
  "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "audio_url": "https://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
}
```

Alternativ kann auch die [Fish Tasks API](https://api.xhuoapi.ai/documents/fc541fac-a941-47fd-b6f7-48d6cb9da523) verwendet werden, um den Status der Aufgabe mit `task_id` aktiv abzufragen.

## Fehlerbehandlung

Die Fehlerantworten dieser Schnittstelle verwenden die HTTP-Statuscodes von Fish, der Antwortkörper folgt jedoch einem einheitlichen Format, um Konsistenz mit den `/fish/audios` und `/fish/voices` APIs zu gewährleisten:

* `400 token_mismatched`: Ungültige Anfrage, möglicherweise fehlende oder ungültige Parameter.
* `400 api_not_implemented`: Ungültige Anfrage, möglicherweise fehlende oder ungültige Parameter.
* `401 invalid_token`: Nicht autorisiert, ungültiger oder fehlender Autorisierungstoken.
* `429 too_many_requests`: Zu viele Anfragen, das Ratenlimit wurde überschritten.
* `500 api_error`: Interner Serverfehler, es ist ein Fehler aufgetreten.

### Beispiel einer Fehlerantwort

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

## Fazit

Die Fish TTS API ist vollständig kompatibel mit der offiziellen Fish Audio OpenAPI und ermöglicht eine Migration bestehender Projekte ohne Codeänderungen. Gleichzeitig profitieren Sie von einheitlicher Authentifizierung, Nutzungsabrechnung und asynchronen Callback-Funktionen, die unsere Plattform bietet. Es wird empfohlen, bei der Generierung längerer Texte bevorzugt die asynchrone Callback-Funktion zu verwenden, um Ressourcen durch lange Verbindungen zu schonen.