Travaux asynchrones v1

# tâches asynchrones

Utilisez les tâches asynchrones TTS pour le texte long, la génération par lots, les flux de travail de type webhook et les flux d'interface utilisateur où les utilisateurs peuvent quitter la page pendant que l'audio est encore en traitement.

Créer un emploi

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

Demande

{
  "text": "Hello from Fish Audio.",
  "voiceId": "00a1b221-6137-4b73-ad62-b0cbce134167",
  "modelId": "fishaudio-s21pro-flash",
  "format": "mp3",
  "speed": 1,
  "volume": 0,
  "stability": 1,
  "similarity": 1,
  "pitch": 0,
  "language": "auto",
  "emotion": "neutral",
  "instruction": "Speak naturally",
  "textNormalization": true
}

Conservez le hachage du texte, la voix demandée et l'ID de tâche renvoyé dans votre base de données. Si votre travailleur plante après sa création, l'interrogation par ID de tâche est plus sûre que la création d'un deuxième travail.

L'exemple utilise la voix de test du système public 00a1b221-6137-4b73-ad62-b0cbce134167. Remplacez-le par votre identifiant vocal préféré après avoir vérifié la connexion.

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"}'

Réponse

Le point de terminaison de création renvoie 202 Accepted. Enregistrez task.id avant de commencer l'interrogation.

{
  "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
}

Obtenir un emploi

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

Les valeurs d'état sont pending, processing, success, partial_fail et fail.

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

Les liens task.segments[].playbackUrl nécessitent le même en-tête. Ne créez pas une autre tâche pour récupérer un téléchargement.

Récupérer un ID de tâche perdu

Si la requête de création a atteint le serveur mais que le client n'a pas reçu la réponse 202 Accepted, commencez par lister les tâches récentes :

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

Les résultats sont triés du plus récent au plus ancien. Utilisez createdAt, textFingerprint, voiceId et engineModelId pour retrouver la requête locale. Les paramètres pris en charge sont page, limit (maximum 100), status et createdAfter au format ISO 8601. La liste ne renvoie qu'un aperçu du texte, jamais le texte complet. Une fois le taskId retrouvé, continuez à interroger la tâche existante. Cette requête ne consomme pas de quota API.

Facturation et crédits

Le serveur réserve creditsUsed une seule fois lorsque la tâche est acceptée. L'interrogation, le téléchargement et le téléchargement répété du même audio ne déclenchent aucun nouveau débit. Une tâche prépayée qui échoue est remboursée via un chemin idempotent.

Pour un lot, limitez la simultanéité de votre côté et vérifiez Profil avant d'ajouter un grand nombre de tâches. Si une tâche échoue en raison de crédits insuffisants, suspendez le rest du lot jusqu'à ce que le propriétaire du compte résolve le solde.

Erreurs