> ## 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 Model API Integrationsanleitung

> Fish music generation 集成指南 - XHuoAPI

Dieser Artikel beschreibt die Integrationsanleitung für die Fish Model API. Diese Schnittstelle ist vollständig kompatibel mit der [Fish Audio offiziellen OpenAPI](https://docs.fish.audio/resources/api-reference/model) 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](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“.

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.

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

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

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

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

```json theme={null}
{
  "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](https://api.xhuoapi.ai/documents/77adcb84-d59f-5ef9-b8a0-8b35eb42a71d) für die Sprachsynthese verwendet werden.