Choose the mode before the request
Capslane checks the cache before applying the requested mode. A cached result can come from native captions or audio generation in any mode. Check source and cached in the response; mode controls what happens on a cache miss.
| Mode | On a cache miss |
|---|---|
| native | Fetch a native caption track. Never start audio generation. Return transcript_unavailable if no usable track exists. |
| auto | Try native captions, then start generation only after transcript_unavailable. A temporary upstream failure remains an error. |
| generate | Start or reuse an asynchronous generation job without first trying native extraction. |
curl --fail-with-body --get "https://capslane.com/v1/transcript" \
--header "x-api-key: $CAPSLANE_API_KEY" \
--data-urlencode "url=dQw4w9WgXcQ" \
--data-urlencode "mode=auto"Do not confuse absence with a network failure
A timeout, regional block or temporary extractor failure does not prove that captions are absent. Capslane keeps transcript_unavailable distinct from upstream_unavailable, so transient failures do not silently create expensive audio jobs.
Treat HTTP 202 as accepted work
Store the job ID and poll the job endpoint. The terminal response uses the same transcript fields as an immediate native result.
{
"jobId": "job_550e8400-e29b-41d4-a716-446655440000",
"status": "queued",
"requestId": "req_example"
}Control generation cost
Use native mode for probes and discovery workflows. Use auto when the application truly needs text. Free workspaces include 50 transcript requests and 15 generated minutes per month, with one active generation at a time. A separate error code identifies request allowance, generated-minute and concurrency limits. Check current limits before importing a playlist.
Polling an existing job does not consume another transcript request. Keep the job ID across retries and application restarts. A browser timeout does not mean the server cancelled the job; a new submission is a separate request.
Poll the original job until a terminal result
curl --fail-with-body "https://capslane.com/v1/transcript/$CAPSLANE_JOB_ID" \
--header "x-api-key: $CAPSLANE_API_KEY"Intermediate states include queued, downloading, processing and persisting. Display progress when present, but use the job status and returned content to decide completion. On failed or cancelled, stop and record the error with the request ID. HTTP 200 can also contain a pending or failed job. Set CAPSLANE_JOB_ID to the accepted ID before running the command above; it checks once.
The Python guide and Node.js guide provide complete polling clients with a total deadline and HTTP error checks. For a short-lived serverless handler, store the ID and resume from a later request instead of keeping an HTTP connection open for the entire job.
The public job endpoint returns canonical timestamped segments when complete. It does not reapply text or chunkSize from the initial request. Join the returned segment text locally if you need one string. A completed response also has jobId, so use content to recognize a ready transcript.
Understand what audio generation can recover
A public, accessible video with speech and no usable caption track is a candidate. A private or removed video is not made accessible by selecting generate. Region restrictions, audio access failures, duration limits and exhausted quotas can still prevent completion.
Generated text and timing should be reviewed for names, numbers, overlapping speakers, background music and clip boundaries. The selected language is reported with the result; requesting a preferred language is not a translation service. Preserve the source field so your product can distinguish extracted captions from generated text.
The public inspector checks native availability and previews segments without starting generation. Use an authenticated workspace to test the audio path on a suitable video within your plan limits.