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-s21pro-flash",
  "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-s21pro-flash","format":"mp3"}'

Antwort

Der Erstellungsendpunkt gibt 202 Accepted zurück. Speichern Sie task.id, bevor Sie mit der Abfrage beginnen.

{
  "task": {
    "id": "task_123",
    "status": "pending",
    "audioUrl": null,
    "delivery": { "downloadUrl": null, "downloadReady": false }
  },
  "record": { "id": "task_123", "status": "pending" },
  "requestId": "req_123",
  "quotaRemaining": 99994,
  "creditsUsed": 6
}

Job bekommen

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

Die Statuswerte sind pending, processing, success, partial_fail und fail.

GET /api/open/tts/jobs/{taskId}/audio?download=1
Authorization: Bearer FISHAUDIO_API_KEY

Auch task.segments[].playbackUrl benötigt denselben Header. Erstellen Sie keinen neuen Job, um einen Download wiederherzustellen.

Verlorene Aufgaben-ID wiederfinden

Wenn die Erstellungsanfrage den Server erreicht hat, der Client aber keine Antwort 202 Accepted erhalten hat, listen Sie zuerst die letzten Jobs auf:

curl "https://fishaudio.org/api/open/v1/speech/tts/jobs?limit=20&createdAfter=2026-07-20T00%3A00%3A00Z" \
  -H "Authorization: Bearer FISHAUDIO_API_KEY"

Die Ergebnisse sind nach Erstellungszeit absteigend sortiert. Gleichen Sie die lokale Anfrage mit createdAt, textFingerprint, voiceId und engineModelId ab. Unterstützt werden page, limit (maximal 100), status und createdAfter im ISO-8601-Format. Die Liste enthält nur eine Textvorschau, nicht den vollständigen Text. Nach dem Wiederfinden von taskId fragen Sie den vorhandenen Job weiter ab. Das Auflisten verbraucht kein API-Kontingent.

Abrechnung und Gutschriften

Der Server reserviert creditsUsed genau einmal, wenn der Job akzeptiert wird. Abfragen, Downloads und wiederholte Downloads desselben Audios verursachen keine weitere Belastung. Ein fehlgeschlagener, vorab belasteter Job wird über einen idempotenten Rückerstattungspfad gutgeschrieben.

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 |