Use the HTTP API¶

AudioText exposes a small client API for applications and a separate admin API for operators. Client applications should use bearer API tokens. Admin routes use the management login session and CSRF checks.

Check service health¶

GET /healthz
GET /readyz
GET /version

/healthz confirms the process is alive. /readyz confirms the database can be opened and the model registry is available.

List transcription models¶

GET /v1/models
Authorization: Bearer <token>

The response is OpenAI-style:

{
  "object": "list",
  "data": [
    {
      "id": "cpu-lite",
      "object": "model",
      "owned_by": "audiotext"
    }
  ]
}

GET /v1/transcription-models is an alias for clients that want a clearer endpoint name.

Run a sync transcription¶

POST /v1/audio/transcriptions
Authorization: Bearer <token>
Content-Type: multipart/form-data

Required form fields:

Field	Description
`file`	Audio file upload.
`model`	Model preset such as `cpu-lite` or `cpu-turbo`.
`language`	`auto`, `en`, `es`, or `ca`.

Useful optional fields:

Field	Description
`response_format`	`json`, `text`, `srt`, or `vtt`.
`beam_size`	Larger values can improve search quality but cost more CPU.
`best_of`	Candidate count for sampling-style decoding.
`vad_filter`	Enable or disable voice activity detection.
`condition_on_previous_text`	Carry context between segments.
`without_timestamps`	Return text without timestamp work.
`word_timestamps`	Request word timestamps when the backend supports them.
`cpu_threads`	Override runtime CPU thread count for this request.
`num_workers`	Override Faster-Whisper worker count for this request.

The JSON response includes transcript text, language metadata, segments, timing fields, and runtime details.

Create an async job¶

POST /v1/transcription-jobs
Authorization: Bearer <token>
Content-Type: multipart/form-data

The form fields match the sync endpoint. The response returns a job ID:

{
  "id": "job_...",
  "status": "queued",
  "object": "transcription.job"
}

Poll the job:

GET /v1/transcription-jobs/{job_id}
Authorization: Bearer <token>

Read only the transcript result:

GET /v1/transcription-jobs/{job_id}/result
Authorization: Bearer <token>

Cancel a queued job:

POST /v1/transcription-jobs/{job_id}/cancel
Authorization: Bearer <token>

Handle errors¶

Errors use one shape:

{
  "error": {
    "message": "missing bearer token",
    "status": 401,
    "type": "http_error"
  }
}

Important statuses:

Status	Meaning
`401`	Missing or invalid authentication.
`403`	Token scope, model, language, admin, or CSRF policy rejected the request.
`413`	Upload or audio duration limit exceeded.
`415`	Unsupported content type, extension, channels, or sample rate.
`429`	Rate, queue, or upload concurrency limit exceeded.
`503`	Runtime dependency or memory guard failed.
`507`	Not enough disk space for the upload.