Choose the mode before the request
native returns an explicit unavailable error and never starts speech transcription. auto tries native captions first and creates a generation job only after their absence is confirmed. generate selects the audio path directly unless a compatible generated result is cached.
curl 'https://capslane.com/v1/transcript?url=VIDEO_ID&mode=auto' \
-H 'x-api-key: YOUR_API_KEY'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_..."
}Control generation cost
Use native mode for probes and discovery workflows. Use auto when the application truly needs text. Set an application deadline and avoid submitting the same video concurrently because generation consumes CPU and network capacity.