> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vocalistic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Jobs

> Start GPU work, then collect the result when it's ready.

Transcription, speech and translation run on GPUs that may need a few minutes to start. So each call returns a job right away, and you collect the result when it's ready. If your connection drops, the work carries on.

## Start a job

```bash theme={null}
curl https://api.vocalistic.ai/v1/audio/speech \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"text": "How far?", "voice": "pcm_spk7"}'
```

You get `202 Accepted`, with a `Location` header pointing at the job:

```json theme={null}
{
  "id": "job_7gyzbwb82m29yktch9sn4gn03s",
  "object": "job",
  "operation": "speech",
  "status": "queued",
  "url": "https://api.vocalistic.ai/v1/jobs/job_7gyzbwb82m29yktch9sn4gn03s",
  "request_id": "req_7gyzbwb82m29yktch9sn4gn03s",
  "created_at": "2026-10-31T12:00:00+00:00",
  "expires_at": null,
  "result": null,
  "error": null,
  "usage": null
}
```

Bad requests are refused immediately and don't create a job, for example unreadable audio or `402 insufficient_credits`.

## Get the result

Check `url` until `status` is final. Start at about once a second and slow down to once every 5 seconds. The `Retry-After` header on the first response is a good starting point.

```bash theme={null}
curl https://api.vocalistic.ai/v1/jobs/JOB_ID \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

| Status | Meaning |
| - | - |
| `queued` | Waiting for a GPU. This can take a few minutes after a quiet period. |
| `running` | In progress. |
| `succeeded` | Done. `result` and `usage` are filled in. |
| `failed` | It didn't work, and you aren't charged. `error` says why, in the [usual format](https://docs.vocalistic.ai/errors.md). A failure that reports `model_unavailable` is worth retrying. |
| `cancelled` | You cancelled it. |
| `expired` | It finished, but the result has been deleted. |

## Wait in one call

For short work, ask to wait with a `Prefer` header, up to 60 seconds:

```bash theme={null}
curl https://api.vocalistic.ai/v1/audio/speech \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Prefer: wait=30' \
  -d '{"text": "How far?", "voice": "pcm_spk7"}'
```

If the job finishes in time you get `200` with the finished job. If not, you get the usual `202`, and the job carries on. A failed job also comes back as `200`, so check `status`.

## Results last 1 hour

We delete a result, including any audio, 1 hour after the job finishes. `expires_at` gives the exact time. To delete it sooner:

```bash theme={null}
curl -X DELETE https://api.vocalistic.ai/v1/jobs/JOB_ID \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

## Cancel a job

```bash theme={null}
curl -X POST https://api.vocalistic.ai/v1/jobs/JOB_ID/cancel \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

You aren't charged for a cancelled job. If it had already finished, nothing changes. A job that hasn't finished after 30 minutes fails on its own, also with no charge.

## Retry safely

If you aren't sure a request got through, send it again with the same `Idempotency-Key` header. You'll get the original job back instead of starting and paying for a second one. A key lasts 24 hours, and using one for a different request returns `409 idempotency_conflict`. If a job couldn't start and you got a `503`, the same key works for the retry.

## Limits

Jobs that are queued or running count towards your [concurrent request limit](https://docs.vocalistic.ai/rate-limits.md). Checking a job doesn't use your request limit. It has its own limit of 600 checks a minute per organization.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.