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 Model API. Diese Schnittstelle ist vollständig kompatibel mit der Fish Audio offiziellen OpenAPI und umfasst:
  • POST /fish/model: Erstellen eines neuen Klon-Stimmprofils (Voice Model) basierend auf einer Audioprobe.
  • GET /fish/model: Paginierte Abfrage der für das aktuelle Konto oder die gesamte Plattform sichtbaren Stimmprofile.

​
Antragsprozess

Um die API zu nutzen, müssen Sie zunächst auf der entsprechenden Seite der Fish Model API den Dienst beantragen. Nach dem Aufruf der Seite klicken Sie auf die Schaltfläche „Acquire“. Wenn Sie noch nicht eingeloggt oder registriert sind, werden Sie automatisch zur Login-Seite weitergeleitet, um sich zu registrieren und anzumelden. Nach der Anmeldung kehren Sie automatisch zur aktuellen Seite zurück. Bei der ersten Beantragung erhalten Sie ein kostenloses Kontingent, mit dem Sie die API kostenlos nutzen können.

​
Unterschiede zur offiziellen API

  • Authentifizierungsmethode: Verwendung von Authorization: Bearer {token}, wobei {token} der auf dieser Plattform beantragte Schlüssel ist.
  • Hochladen von Samples bei der Modellerstellung: Diese Schnittstelle unterstützt derzeit nur die Einreichung im JSON-Format, wobei die Audio-Sample-URLs über das Feld voices übergeben werden. Die offizielle Fish API unterstützt multipart/msgpack zum direkten Hochladen von Binärdaten, was hier noch nicht implementiert ist. Die URL-Variante deckt etwa 80 % der gängigen Anwendungsfälle ab.
  • Antwortstruktur: Sowohl POST /fish/model als auch GET /fish/model geben die Antwort der Fish-Plattform direkt zurück, ohne eine zusätzliche Plattform-Envelope-Verpackung. Fehler werden im Plattform-Standardformat {success:false, error:{code,message}, trace_id} ausgegeben.

​
Stimmprofil erstellen (POST /fish/model)

Die minimale Anforderung zum Erstellen benötigt die Felder title und voices. voices ist eine Liste von URLs zu Audio-Samples, empfohlen werden Dateien mit einer Länge von mindestens 30 Sekunden und einer Abtastrate von 16 kHz oder höher. 
curl -X POST 'https://api.xhuoapi.ai/v1/fish/model' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "title": "我的克隆音色",
    "description": "用一段播客录音克隆的音色",
    "voices": [
      "https://example.com/sample-voice.mp3"
    ],
    "cover_image": "https://example.com/cover.png",
    "visibility": "private"
  }'
Eine erfolgreiche Antwort gibt direkt das ModelEntity-Objekt der Fish-Plattform zurück: 
{
  "_id": "d7900c21663f485ab63ebdb7e5905036",
  "type": "tts",
  "title": "我的克隆音色",
  "description": "用一段播客录音克隆的音色",
  "cover_image": "https://example.com/cover.png",
  "train_mode": "fast",
  "state": "trained",
  "tags": [],
  "samples": [],
  "created_at": "2025-05-09T12:34:56.789Z",
  "updated_at": "2025-05-09T12:34:56.789Z",
  "languages": ["zh", "en"],
  "visibility": "private",
  "lock_visibility": false,
  "like_count": 0,
  "mark_count": 0,
  "shared_count": 0,
  "task_count": 0,
  "author": {
    "_id": "user_id",
    "nickname": "user_nickname",
    "avatar": "user_avatar"
  }
}
Die zurückgegebene _id kann anschließend als Wert für das Feld reference_id in POST /fish/tts verwendet werden, um mit dem Klon-Stimmprofil Sprachsynthese durchzuführen.

​
Stimmprofil-Liste abfragen (GET /fish/model)

curl -G 'https://api.xhuoapi.ai/v1/fish/model' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'page_size=10' \
  --data-urlencode 'page_number=1' \
  --data-urlencode 'self=true'
Verfügbare Abfrageparameter (identisch mit Fish offiziell):
  • page_size: Anzahl der Einträge pro Seite, Standard 10.
  • page_number: Seitenzahl, beginnend bei 1.
  • title: Unscharfe Suche nach Titel.
  • tag: Filter nach Tags.
  • self: Bei Wert true werden nur vom aktuellen Konto erstellte Stimmprofile zurückgegeben.
  • author_id: Filter nach Ersteller.
  • language: Filter nach Sprache des Stimmprofils.
  • title_language: Filter nach Sprache des Titels.
Eine erfolgreiche Antwort gibt ebenfalls die Paginierungsstruktur der Fish-Plattform direkt zurück: 
{
  "items": [
    {
      "_id": "d7900c21663f485ab63ebdb7e5905036",
      "title": "我的克隆音色",
      "description": "用一段播客录音克隆的音色",
      "cover_image": "https://example.com/cover.png",
      "type": "tts",
      "state": "trained",
      "tags": [],
      "languages": ["zh", "en"],
      "visibility": "private",
      "created_at": "2025-05-09T12:34:56.789Z",
      "updated_at": "2025-05-09T12:34:56.789Z"
    }
  ],
  "total": 1
}

​
Abrechnungsinformationen

Diese Schnittstelle berechnet nur bei der „Stimmprofil-Erstellung“ (POST /fish/model mit voices im Request-Body) Gebühren. Die „Stimmprofil-Liste abfragen“ (GET /fish/model) ist kostenfrei.

​
Fehlerbehandlung

  • 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ültiges oder fehlendes Autorisierungstoken.
  • 429 too_many_requests: Zu viele Anfragen, Sie haben das Ratenlimit überschritten.
  • 500 api_error: Interner Serverfehler, auf dem Server ist ein Fehler aufgetreten.

​
Beispiel für eine Fehlerantwort

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

​
Fazit

Die Fish Model API ist vollständig kompatibel mit der ModelEntity-Schnittstelle der offiziellen Fish Audio OpenAPI und ermöglicht eine Migration bestehender Klon-Stimmprofil-Verwaltungscode ohne Codeänderungen. Die erstellte _id des Stimmprofils kann direkt als reference_id im Fish TTS API für die Sprachsynthese verwendet werden.