Batch Transcription Jobs

PreviousNext

Asynchronous batch transcription from audio_url.

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).

Endpoint

POST /v1/audio/transcriptions/jobs

POST / 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"
}
FieldTypeRequiredDefaultDescription
audio_urlstringyes—Public URL of the audio file. Must be http(s)://.
request_idstringnorandom UUIDIdempotency key. Re-submitting with the same ID starts a new job (a new workflow_id) and may reuse completed chunks from the R2 checkpoint.
languagestringno—Audio language hint (e.g. zh, en).
modelstringno—Optional compatibility field; omit it. Clients that require a name can use lanson-live-1. It does not select an upstream model.
promptstringno—Transcription context hint.
segment_secondsnumberno300Target slice length in seconds. Must be > 0.
response_formatstringnoverbose_jsonResponse format (workflow hardcodes verbose_json per chunk today).
concurrencynumberno6Concurrent transcription of chunks. Must be > 0.
webhook_urlstringno—POSTed the full result (raw + reviewed) when the job completes.
reviewbooleannotrue (omitted = on)LLM correction pipeline; set false to opt out.
target_languagesstringno—Translation targets (BCP-47, max 8). Frozen at job creation; each language is billed separately.
translate_tostringno—Single-language shorthand for target_languages. Ignored when target_languages is present.
metadataobjectno—Contextual metadata 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.

Errors

StatusDescription
400Non-JSON body or invalid/missing audio_url
401Authentication 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

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

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}/:

ArtifactR2 key
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)

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.