Zum Hauptinhalt springen
Dieser Artikel beschreibt eine Integrationsanleitung für die Fish Voices Generation API, mit der Sie Ihre eigene Stimme durch Eingabe eines Audio-Links erstellen können.

​
Antragsprozess

Um die API zu nutzen, müssen Sie zunächst auf die entsprechende Seite der Fish Voices Generation API gehen und den entsprechenden Dienst beantragen. Nachdem Sie die Seite betreten haben, klicken Sie auf die Schaltfläche „Acquire“, wie im Bild gezeigt: Wenn Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, um sich zu registrieren und anzumelden. Nach der Anmeldung werden Sie automatisch zur aktuellen Seite zurückgeleitet. Bei der ersten Beantragung gibt es ein kostenloses Kontingent, mit dem Sie die API kostenlos nutzen können.

​
Grundlegende Nutzung

Zunächst sollten Sie die grundlegende Nutzung verstehen, bei der Sie den Audio-Link der Stimme voice_url eingeben, um das verarbeitete Ergebnis zu erhalten. Die genauen Inhalte sind wie folgt:

Hier haben wir die Request-Header festgelegt, einschließlich:
  • accept: In welchem Format Sie die Antwort erhalten möchten, hier eingetragen als application/json, also im JSON-Format.
  • authorization: Der Schlüssel zur Nutzung der API, den Sie nach der Beantragung direkt auswählen können.
Außerdem haben wir den Request-Body festgelegt, einschließlich:
  • voice_url: Der hochgeladene Audio-Link der Stimme.
  • title: Die Titelinformation dieser Stimme.
  • image_urls: Das Coverbild dieser Stimme.
  • description: Die Beschreibungsinformation dieser Stimme.
  • callback_url: Die URL, an die das Ergebnis zurückgegeben werden soll.
Nach der Auswahl können Sie feststellen, dass auf der rechten Seite auch der entsprechende Code generiert wurde, wie im Bild gezeigt:

Klicken Sie auf die Schaltfläche „Try“, um einen Test durchzuführen. Wie im obigen Bild gezeigt, haben wir folgendes Ergebnis erhalten: 
{
  "success": true,
  "task_id": "b01db503-dd9e-4f92-861a-344f14756217",
  "trace_id": "8731a2f1-7736-4a47-98e7-da942f9346a7",
  "data": {
    "_id": "d5d21261512b4852b9ccd709facf93f3",
    "type": "tts",
    "title": "test",
    "description": "test",
    "cover_image": "coverimage/d5d21261512b4852b9ccd709facf93f3",
    "train_mode": "fast",
    "state": "trained",
    "tags": [],
    "samples": [
      {
        "title": "Default Sample",
        "text": "Durch langfristige Beobachtungen wurde festgestellt, dass die Fische im Korallenriff-Ökosystem komplexe Gruppenverhaltensmuster aufweisen. Sie nutzen Farbänderungen und spezifische Schwimmhaltungen, um Informationen zu übermitteln. Dieses präzise nonverbale Kommunikationssystem zeigt die Anpassungsfähigkeit der Meereslebewesen.",
        "task_id": "4ae961828fc94c07b2103dc039a8466b",
        "audio": "task/4ae961828fc94c07b2103dc039a8466b.mp3"
      }
    ],
    "created_at": "2025-09-21T07:29:41.058506Z",
    "updated_at": "2025-09-21T07:29:41.057917Z",
    "languages": [
      "zh"
    ],
    "visibility": "public",
    "lock_visibility": false,
    "default_text": "Durch langfristige Beobachtungen wurde festgestellt, dass die Fische im Korallenriff-Ökosystem komplexe Gruppenverhaltensmuster aufweisen. Sie nutzen Farbänderungen und spezifische Schwimmhaltungen, um Informationen zu übermitteln. Dieses präzise nonverbale Kommunikationssystem zeigt die Anpassungsfähigkeit der Meereslebewesen.",
    "like_count": 0,
    "mark_count": 0,
    "shared_count": 0,
    "task_count": 0,
    "unliked": false,
    "liked": false,
    "marked": false,
    "author": {
      "_id": "7ecad23df62a4174acd6a2a6cb5201ee",
      "nickname": "Matthew Garcia",
      "avatar": "avatars/7ecad23df62a4174acd6a2a6cb5201ee.jpg"
    }
  }
}
Die Rückgabe enthält mehrere Felder, die wie folgt beschrieben werden:
  • success, der Status des Erstellungsauftrags der Stimme.
    • data, das Ergebnis des Musikauftrags
      • _id, die ID des Erstellungsauftrags der Stimme, die später zur Klonung der Stimme verwendet wird.
      • title, der Titel der Stimme.
      • image_url, die Coverinformation der Stimme.
      • description, die Beschreibungsinformation der Stimme.
      • train_mode, der Modus, der für den Erstellungsauftrag der Stimme verwendet wird.
      • tags, der Stil der Stimme.
      • default_text, die Textinformation des Erstellungsauftrags der Stimme.
Wir haben die gewünschten Informationen zur Stimme erhalten und müssen nur den data-Wert von _id verwenden, um den Klonauftrag der Stimme durchzuführen. Wenn Sie den entsprechenden Integrationscode generieren möchten, können Sie ihn direkt kopieren, zum Beispiel ist der CURL-Code wie folgt: 
curl -X POST 'https://api.acedata.cloud/fish/voices' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "voice_url": "https://platform.r2.fish.audio/task/604133d7b3c7430385382470f67770e8.mp3",
  "title": "test",
  "description": "test"
}'

​
Asynchrone Rückrufe

Da die Generierung durch die Fish Voices Generation API relativ lange dauert, etwa 1-2 Minuten, bleibt die HTTP-Anfrage bei längerer Nichtantwort verbunden, was zu einem zusätzlichen Ressourcenverbrauch des Systems führt. Daher bietet diese API auch Unterstützung für asynchrone Rückrufe. Der gesamte Prozess ist: Wenn der Client die Anfrage stellt, gibt er zusätzlich ein Feld callback_url an. Nachdem der Client die API-Anfrage gestellt hat, gibt die API sofort ein Ergebnis zurück, das ein Feld task_id enthält, das die aktuelle Aufgaben-ID darstellt. Wenn die Aufgabe abgeschlossen ist, wird das Ergebnis des Erstellungsauftrags in Form von POST JSON an die vom Client angegebene callback_url gesendet, wobei auch das Feld task_id enthalten ist, sodass die Aufgabenergebnisse über die ID miteinander verknüpft werden können. Lassen Sie uns anhand eines Beispiels verstehen, wie dies konkret funktioniert. Zunächst ist der Webhook-Rückruf ein Dienst, der HTTP-Anfragen empfangen kann. Entwickler sollten die URL ihres eigenen HTTP-Servers ersetzen. Zur Vereinfachung der Demonstration verwenden wir eine öffentliche Webhook-Beispielseite https://webhook.site/, auf der Sie eine Webhook-URL erhalten können, wie im Bild gezeigt: Kopieren Sie diese URL, um sie als Webhook zu verwenden. Das Beispiel hier lautet https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34. Anschließend können wir das Feld callback_url auf die oben genannte Webhook-URL setzen und die entsprechenden Parameter eingeben, wie im Bild gezeigt:

Klicken Sie auf Ausführen, und Sie werden sofort ein Ergebnis erhalten, wie folgt: 
{
  "task_id": "9f626a13-96ec-4dec-8846-dc5aab7362a8"
}
Bitte einen Moment Geduld, wir können die Ergebnisse der Generierungsaufgabe unter https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34 beobachten, wie im Bild gezeigt: Der Inhalt ist wie folgt: 
{
    "success": true,
    "task_id": "9f626a13-96ec-4dec-8846-dc5aab7362a8",
    "trace_id": "3fcdea82-7c1c-4a0a-b8d8-f7616f722d8f",
    "data": {
        "_id": "fa75e7c3f02f42e79a6aa622b6cf075e",
        "type": "tts",
        "title": "test",
        "description": "test",
        "cover_image": "coverimage/fa75e7c3f02f42e79a6aa622b6cf075e",
        "train_mode": "fast",
        "state": "trained",
        "tags": [],
        "samples": [
            {
                "title": "Default Sample",
                "text": "Delfine navigieren im Ozean durch ein Echolot-System, diese präzise Schallwellen-Technologie ermöglicht es ihnen, die Umgebung zu erkennen, Nahrung zu suchen und Gefahren zu vermeiden. Dies zeigt nicht nur die Anpassungsfähigkeit der Meereslebewesen, sondern offenbart auch das wunderbare Design der Natur.",
                "task_id": "68cdda24d26e4794bae177e20da740db",
                "audio": "task/68cdda24d26e4794bae177e20da740db.mp3"
            }
        ],
        "created_at": "2025-09-21T07:36:20.200865Z",
        "updated_at": "2025-09-21T07:36:20.200353Z",
        "languages": [
            "zh"
        ],
        "visibility": "public",
        "lock_visibility": false,
        "default_text": "Delfine navigieren im Ozean durch ein Echolot-System, diese präzise Schallwellen-Technologie ermöglicht es ihnen, die Umgebung zu erkennen, Nahrung zu suchen und Gefahren zu vermeiden. Dies zeigt nicht nur die Anpassungsfähigkeit der Meereslebewesen, sondern offenbart auch das wunderbare Design der Natur.",
        "like_count": 0,
        "mark_count": 0,
        "shared_count": 0,
        "task_count": 0,
        "unliked": false,
        "liked": false,
        "marked": false,
        "author": {
            "_id": "7ecad23df62a4174acd6a2a6cb5201ee",
            "nickname": "Matthew Garcia",
            "avatar": "avatars/7ecad23df62a4174acd6a2a6cb5201ee.jpg"
        }
    }
}
Es ist zu sehen, dass das Ergebnis ein task_id-Feld enthält, die anderen Felder sind ähnlich wie oben, über dieses Feld kann die Aufgabe verknüpft werden.

​
Fehlerbehandlung

Beim Aufruf der API, wenn ein Fehler auftritt, gibt die API den entsprechenden Fehlercode und die Informationen zurück. Zum Beispiel:
  • 400 token_mismatched: Ungültige Anfrage, möglicherweise aufgrund fehlender oder ungültiger Parameter.
  • 400 api_not_implemented: Ungültige Anfrage, möglicherweise aufgrund fehlender oder ungültiger Parameter.
  • 401 invalid_token: Unbefugt, ungültiger oder fehlender Autorisierungstoken.
  • 429 too_many_requests: Zu viele Anfragen, Sie haben das Kontingent überschritten.
  • 500 api_error: Interner Serverfehler, etwas ist auf dem Server schiefgelaufen.

​
Beispiel für eine Fehlerantwort

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

​
Fazit

Durch dieses Dokument haben Sie gelernt, wie Sie die Fish Voices Generation API verwenden können, um Ihre eigenen Stimmen durch die Eingabe von Audioverbindungen zu erstellen. Wir hoffen, dass dieses Dokument Ihnen hilft, die API besser zu integrieren und zu nutzen. Bei Fragen wenden Sie sich bitte jederzeit an unser technisches Support-Team.