Zum Hauptinhalt springen

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.

Dieser Artikel beschreibt die Integrationsanleitung für die Fish TTS API. Diese Schnittstelle ist vollständig kompatibel mit der offiziellen Fish Audio OpenAPI 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 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: 
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: 
{
  "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: 
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: 
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: 
{
  "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: 
{
  "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "audio_url": "https://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
}
Alternativ kann auch die Fish Tasks API 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

{
  "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.