API reference
The complete HTTP contract for retrieving native YouTube captions and generating transcripts when captions are unavailable.
Base URL
All public API endpoints use HTTPS and the following production origin.
https://capslane.comAuthentication
Send a workspace key in the x-api-key request header. Keep production keys in server-side environment variables.
x-api-key: vxl_live_.../v1/transcript
Return an existing transcript immediately or create an asynchronous generation job.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
url | string | Required | Public YouTube URL, Shorts URL or 11-character video ID. |
lang | string | Source language | Preferred ISO language code such as en or fr-FR. |
mode | enum | auto | native, auto or generate. |
text | boolean | false | Return one string instead of timestamped segments. |
chunkSize | integer | Native segments | Group content into chunks from 50 to 10,000 characters. |
curl --get 'https://capslane.com/v1/transcript' \
--data-urlencode 'url=dQw4w9WgXcQ' \
--data-urlencode 'lang=en' \
--data-urlencode 'mode=auto' \
-H 'x-api-key: YOUR_API_KEY'200 response
A native, generated or cached transcript is ready. Offsets and durations are expressed in milliseconds.
{
"content": [
{
"text": "Example segment",
"offset": 8150,
"duration": 1200,
"lang": "en"
}
],
"lang": "en",
"availableLangs": ["en", "fr"],
"source": "native",
"cached": false,
"requestId": "req_..."
}202 response
A generated transcript was accepted. Poll the returned job URL with the same API key.
{
"jobId": "job_550e8400-e29b-41d4-a716-446655440000",
"status": "queued",
"progress": 5,
"requestId": "req_..."
}/v1/transcript/:jobId
Read the current state of an asynchronous transcript. The job belongs to the workspace that created it.
curl 'https://capslane.com/v1/transcript/job_550e8400-e29b-41d4-a716-446655440000' \
-H 'x-api-key: YOUR_API_KEY'Job states
queued, downloading, processing, persisting, completed, failed or cancelled.
{
"jobId": "job_550e8400-e29b-41d4-a716-446655440000",
"status": "processing",
"progress": 35,
"requestId": "req_..."
}Errors
Every error is JSON and includes a request ID for log correlation.
{
"error": "invalid_video_id",
"message": "The YouTube video ID is invalid",
"requestId": "req_..."
}| Status | Common code | Meaning |
|---|---|---|
| 400 | invalid_request | The query does not match the API contract. |
| 401 | invalid_api_key | The key is missing, invalid, expired or revoked. |
| 404 | transcript_unavailable | No caption is available in native mode. |
| 404 | job_not_found | The job does not exist in this workspace. |
| 429 | monthly_limit_exceeded | The workspace reached its monthly request limit. |
| 502 | upstream_unavailable | The source could not be reached safely. |
Limits
The API accepts up to 120 requests per minute per client. One accepted transcript request reserves one monthly unit. Polling an existing job does not reserve another unit.