Asynchrone Jobs

Verwenden Sie asynchrone TTS-Jobs für Langtext, Batch-Generierung, Webhook-Workflows und UI-Flows, bei denen Benutzer die Seite verlassen können, während Audio noch verarbeitet wird.

Job erstellen

POST /api/open/v1/speech/tts/jobs
Authorization: Bearer FISHAUDIO_API_KEY
Content-Type: application/json

Anfrage

{
  "text": "Hello from Fish Audio.",
  "voiceId": "00a1b221-6137-4b73-ad62-b0cbce134167",
  "modelId": "fishaudio-s2pro",
  "format": "mp3"
}

Behalten Sie den Text-Hash, die angeforderte Stimme und die zurückgegebene Aufgaben-ID in Ihrer Datenbank bei. Wenn Ihr Worker nach der Erstellung abstürzt, ist die Abfrage anhand der Aufgaben-ID sicherer als das Erstellen eines zweiten Jobs.

Das Beispiel verwendet die öffentliche Systemteststimme 00a1b221-6137-4b73-ad62-b0cbce134167. Ersetzen Sie es durch Ihre bevorzugte Sprach-ID, nachdem Sie die Verbindung überprüft haben.

curl https://fishaudio.org/api/open/v1/speech/tts/jobs \
  -H "Authorization: Bearer FISHAUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from Fish Audio.","voiceId":"00a1b221-6137-4b73-ad62-b0cbce134167","modelId":"fishaudio-s2pro","format":"mp3"}'

Antwort

Der Erstellungsendpunkt gibt 202 Accepted mit einem Aufgabenobjekt zurück. Die genauen Aufgabenfelder können sich ändern, aber Kunden sollten zumindest die ID und den Status speichern.

{
  "id": "task_123",
  "status": "queued"
}

Job bekommen

GET /api/open/v1/speech/tts/jobs/{taskId}
Authorization: Bearer FISHAUDIO_API_KEY

Zu den erfolgreichen Aufgaben gehört audioUrl, wenn eine kurzlebige Audio-URL generiert werden kann. Zu fehlgeschlagenen Aufgaben gehört ein Fehlercode oder eine Fehlermeldung. Behandeln Sie queued und processing als nicht-terminale Zustände und fragen Sie mit Backoff ab.

Abrechnung und Gutschriften

Asynchrone Jobs können je nach aktiviertem Modell während der Aufgabenerstellung oder -abwicklung Credits reservieren oder verbrauchen. Erstellen Sie keine doppelten Jobs als Wiederholungsstrategie, es sei denn, der Benutzer hat ausdrücklich nach einer zweiten Ausgabe gefragt. Speichern Sie die Aufgaben-ID und stellen Sie sie wieder her.

Drosseln Sie für einen Stapel die Parallelität auf Ihrer Seite und überprüfen Sie Profil, bevor Sie eine große Anzahl von Aufgaben hinzufügen. Wenn eine Aufgabe aufgrund unzureichender Credits fehlschlägt, pausieren Sie den rest des Stapels, bis der Kontoinhaber den Restbetrag ausgeglichen hat.

Fehler

| Status | Bedeutung | Aktion | | ------ | --------------------------------------------------- | ---------------------------------------------------------------------- | ----------------- | | 400 | Ungültiger Text, Sprache, Modell oder Ausgabeformat | Korrigieren Sie die Nutzlast | | 401 | Authentifizierung fehlgeschlagen | Beenden Sie die Abfrage und aktualisieren Sie die Anmeldeinformationen | | 402 | Unzureichende Credits oder Quote | Warteschlange anhalten | | 404 | Die Aufgaben-ID ist diesem API-Schlüssel unbekannt | Überprüfen Sie, ob Sie die zurückgegebene ID für dasselbe Konto | gespeichert haben | | 429 | Zu viele Erstellungs- oder Umfrageanfragen | Machen Sie einen Schritt zurück und behalten Sie die Aufgaben-ID bei |