Transcribe Audio

PreviousNext

Submit an audio URL for batch transcription.

Submit a Batch job through Lanson Live API from a public audio URL.

For client-VAD speech clips use Segment Transcription instead.

Submit a job

Request

curl -X POST https://audio.lansonai.com/v1/audio/transcriptions/jobs \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://cdn.example.com/meeting.wav",
    "language": "zh",
    "prompt": "Medical cardiology conference",
    "webhook_url": "https://your-server.com/webhook"
  }'

Request body

FieldTypeRequiredDefaultDescription
audio_urlstringyes—Public audio URL, must be http(s)://
request_idstringnorandom UUIDIdempotency key; same ID resumes from R2 checkpoint
languagestringno—Language hint (e.g. zh, en)
modelstringno—Optional compatibility field; omit it. Clients that require a name can use lanson-live-1.
promptstringno—Transcription context hint
segment_secondsnumberno300Slice length in seconds, must be > 0
response_formatstringnoverbose_jsonResponse format
concurrencynumberno6Concurrent chunk transcription, must be > 0
webhook_urlstringno—POST final result to this URL on completion
reviewbooleannotrue (omitted = on)LLM correction of the transcript; set false to opt out
metadataobjectno—Context forwarded to review stages

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.

Poll for results

curl https://audio.lansonai.com/v1/audio/transcriptions/jobs/<workflow_id> \
  -H "Authorization: Bearer sk-..."

Legacy aliases: GET /<workflow_id>, GET /v1/audio/transcriptions/<workflow_id>

Status values

StatusMeaning
queuedWaiting to start
runningProcessing
completeDone (result in output)
erroredFailed (error in error)
terminatedTerminated

Complete output

{
  "status": "complete",
  "output": {
    "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
      }
    }
  }
}

Webhook

Set webhook_url to receive the final result via HTTP POST when the job completes.

LLM review

Review is on by default on the production endpoint. When review is omitted, the job runs the correct step and returns result.metadata.correction plus the uncorrected lines in result.raw_segments. Set review: false to opt out and get the raw transcript only.

The OpenAPI schema is the source of truth for this flag: omitted = on where correction is configured.

R2 artifacts

Results are stored in R2 under transcription/{request_id}/:

ArtifactKey
Per-chunk transcriptionchunk_{i}.json
Raw aggregated transcriptresult.json
Per-chunk review annotationsreview_chunk_{i}.json (when review is on — the default)
Final corrected transcriptreviewed_result.json (when review is on — the default)

Idempotency

Provide request_id for idempotency — already-transcribed chunks are skipped on retry.