Async Jobs

Use async TTS jobs for long text, batch generation, webhook-style workflows, and UI flows where users can leave the page while audio is still processing.

Create Job

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

Request

{
  "text": "Hello from FishSpeech.",
  "voiceId": "YOUR_VOICE_ID",
  "engineModelId": "fishaudio-s2pro",
  "format": "mp3"
}

Persist the text hash, requested voice, and returned task id in your database. If your worker crashes after creation, polling by task id is safer than creating a second job.

curl https://fishaudio.org/api/open/v1/speech/tts/jobs \
  -H "Authorization: Bearer FISHSPEECH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from FishSpeech.","voiceId":"YOUR_VOICE_ID","format":"mp3"}'

Response

The create endpoint returns 202 Accepted with a task object. The exact task fields can evolve, but clients should at least store the id and status.

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

Get Job

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

Successful tasks include audioUrl when a short-lived audio URL can be generated. Failed tasks include an error code or message. Treat queued and processing as non-terminal states and poll with backoff.

Billing And Credits

Async jobs may reserve or consume credits during task creation or completion depending on the enabled model. Do not create duplicate jobs as a retry strategy unless the user explicitly asked for a second output. Store the task id and recover from it.

For a batch, throttle concurrency on your side and check Profile before adding a large number of tasks. If one task fails for insufficient credits, pause the rest of the batch until the account owner resolves balance.

Errors