Trabajos asíncronos

Utilice trabajos asíncronos TTS para textos largos, generación por lotes, flujos de trabajo estilo webhook y flujos de interfaz de usuario donde los usuarios pueden abandonar la página mientras el audio aún se está procesando.

Crear trabajo

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

Pedido

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

Conserve el hash de texto, la voz solicitada y la identificación de la tarea devuelta en su base de datos. Si su trabajador falla después de la creación, sondear por identificación de tarea es más seguro que crear un segundo trabajo.

El ejemplo utiliza la voz de prueba del sistema público 00a1b221-6137-4b73-ad62-b0cbce134167. Reemplácelo con su ID de voz preferido después de verificar la conexión.

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

Respuesta

El punto final de creación devuelve 202 Accepted. Guarde task.id antes de comenzar a consultar.

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

conseguir trabajo

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

Los valores de estado son pending, processing, success, partial_fail y fail.

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

Los enlaces de task.segments[].playbackUrl requieren el mismo encabezado. No cree otro trabajo para recuperar una descarga.

Recuperar un ID de tarea perdido

Si la solicitud de creación llegó al servidor pero el cliente no recibió la respuesta 202 Accepted, primero enumere los trabajos recientes:

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

Los resultados se ordenan del más reciente al más antiguo. Utilice createdAt, textFingerprint, voiceId y engineModelId para relacionarlos con la solicitud local. Se admiten page, limit (máximo 100), status y createdAfter en formato ISO 8601. La lista solo devuelve una vista previa del texto, no el texto completo. Después de recuperar taskId, continúe consultando el trabajo existente. La consulta de la lista no consume cuota de API.

Facturación y créditos

El servidor reserva creditsUsed una sola vez cuando acepta el trabajo. Consultar, descargar o volver a descargar el mismo audio no genera otro cargo. Un trabajo prepagado que falla se reembolsa mediante una ruta idempotente.

Para un lote, limite la concurrencia de su lado y verifique Perfil antes de agregar una gran cantidad de tareas. Si una tarea falla por créditos insuficientes, suspenda el rest del lote hasta que el propietario de la cuenta resuelva el saldo.

Errores