POST /v1/audio/transcriptions/jobs
What it does
Use the Batch path of Lanson Live API to submit an audio URL for asynchronous processing. The service fetches the file, slices it by time, processes chunks concurrently, aggregates results, and optionally posts to a webhook.
For synchronous client-VAD clips use Segment Transcription (POST /v1/audio/transcriptions with multipart).
Billing: batch jobs are metered by processed audio and billed at the offline transcription rate. See API pricing.
Endpoint
POST /v1/audio/transcriptions/jobsPOST / and POST /v1/audio/transcriptions with JSON still work but are deprecated (return Deprecation: true).
Authentication
Authorization: Bearer sk-...Request body
{
"audio_url": "https://cdn.example.com/audio/meeting.wav",
"language": "zh",
"prompt": "Medical cardiology conference",
"review": true,
"metadata": { "medical_specialty": "cardiology" },
"webhook_url": "https://your-server.com/webhook"
}| Field | Type | Required | Default | Description |
|---|---|---|---|---|
audio_url | string | yes | — | Public URL of the audio file. Must be http(s)://. |
request_id | string | no | random UUID | Idempotency key. Re-submitting with the same ID starts a new job (a new workflow_id) and may reuse completed chunks from the R2 checkpoint. |
language | string | no | — | Audio language hint (e.g. zh, en). |
model | string | no | — | Optional compatibility field; omit it. Clients that require a name can use lanson-live-1. It does not select an upstream model. |
prompt | string | no | — | Transcription context hint. |
segment_seconds | number | no | 300 | Target slice length in seconds. Must be > 0. |
response_format | string | no | verbose_json | Response format (workflow hardcodes verbose_json per chunk today). |
concurrency | number | no | 6 | Concurrent transcription of chunks. Must be > 0. |
webhook_url | string | no | — | POSTed the full result (raw + reviewed) when the job completes. |
review | boolean | no | true (omitted = on) | LLM correction pipeline; set false to opt out. |
target_languages | string | no | — | Translation targets (BCP-47, max 8). Frozen at job creation; each language is billed separately. |
translate_to | string | no | — | Single-language shorthand for target_languages. Ignored when target_languages is present. |
metadata | object | no | — | Contextual metadata forwarded to review stages. |
review is on by default. Omit it to run correction (the job includes a correct step and returns result.metadata.correction and result.raw_segments); set review: false to receive the raw transcript only.
Response — 202 Accepted
{
"request_id": "...",
"workflow_id": "local55190d1a608984daf77cbfca6b7b5438",
"status": "queued",
"endpoint": "GET /local...",
"poll_endpoint": "GET /v1/audio/transcriptions/jobs/local..."
}workflow_id is an opaque job id. On the production endpoint it is local + 32 hex (local-runner id); on the Cloudflare Worker deployment it is cf_ + 64 hex. It is not a UUID.
Errors
| Status | Description |
|---|---|
| 400 | Non-JSON body or invalid/missing audio_url |
| 401 | Authentication failed |
GET /v1/audio/transcriptions/jobs/{workflowId}
What it does
Poll batch job status and result (preferred path).
Endpoint
GET /v1/audio/transcriptions/jobs/{workflowId}Aliases: GET /v1/audio/transcriptions/{workflowId}, GET /{workflowId}
Response
{
"workflow_id": "local...",
"status": "complete",
"steps": [ ... ],
"output": { ... },
"error": null
}Status values
| Status | Meaning |
|---|---|
queued | Waiting to start |
running | Processing |
complete | Done (result in output) |
errored | Failed (error in error) |
terminated | Terminated |
paused | Paused |
waiting | Waiting |
Complete output structure
{
"result": {
"segments": [
{
"id": 0,
"start_time": 0.0,
"end_time": 3.2,
"duration": 3.2,
"text": "The weather is nice today",
"confidence": 0.95,
"timing": "estimated"
}
],
"summary": {
"total_duration": 120.5,
"total_speech_duration": 95.3,
"overall_speech_ratio": 0.79,
"num_segments": 45
},
"metadata": {
"language": "zh",
"chunk_count": 3,
"audio_duration_seconds": 120.5,
"translation": {
"target_languages": ["en"],
"model": "deepseek/deepseek-v4.1-flash-1017",
"failed_batches": 0,
"usage": { "calls": 1, "prompt_tokens": 120, "completion_tokens": 24, "total_tokens": 144 }
},
"llm_usage": {
"calls": 2,
"prompt_tokens": 220,
"completion_tokens": 44,
"total_tokens": 264,
"by_stage": {
"refinement": { "calls": 1, "prompt_tokens": 100, "completion_tokens": 20, "total_tokens": 120 },
"translation": { "calls": 1, "prompt_tokens": 120, "completion_tokens": 24, "total_tokens": 144 }
}
}
},
"translations": [
{
"language": "en",
"text": "The weather is nice today.",
"segments": [
{ "id": 0, "start_time": 0.0, "end_time": 3.2, "duration": 3.2, "text": "The weather is nice today.", "source_text": "今天天气很好" }
],
"failed_batches": 0
}
]
}
}confidence is 0 when the upstream does not provide a value. The production batch path returns timing: "estimated". With review on, the job also returns result.raw_segments and result.metadata.correction. With target_languages set, the job returns result.translations (one track per language) and result.metadata.translation (model, token usage, failed batches).
R2 artifacts
Result artifacts are stored in R2 under transcription/{request_id}/:
| Artifact | R2 key |
|---|---|
| Per-chunk transcription | chunk_{i}.json |
| Raw aggregated transcript | result.json |
| Per-chunk review annotations | review_chunk_{i}.json (when review is on — the default) |
| Final corrected transcript | reviewed_result.json (when review is on — the default) |
Webhook
Set webhook_url to receive the final result via HTTP POST when the job completes.
OpenAPI
Full OpenAPI specification at GET /openapi.json. Swagger UI at GET /docs.
Related
- Transcribe Audio — usage guide
- Segment Transcription — sync client-VAD clips
- Timestamps & Speakers — timestamp details
- Errors — error codes