Introduction

Capslane provides one API for retrieving YouTube captions and generating transcripts when captions are unavailable.

Overview

Every request follows the same path. Capslane first looks for an existing transcript, then starts an asynchronous generation job when the selected mode allows it.

Native and automatic YouTube captions
AI-generated fallback for videos without captions
Plain text or timestamped segments
Shared cache with a stable response contract

Get an API key

Create or open your Capslane workspace.
Open API Keys and create a server key.
Copy it immediately. The complete key is shown only once.

Keep it server-side

Do not commit the key or expose it in browser and mobile bundles.

Authentication

Send the workspace API key in the x-api-key header on every request.

cURL

curl 'https://capslane.com/v1/transcript?url=dQw4w9WgXcQ&mode=auto' \
  -H 'x-api-key: YOUR_API_KEY'

The production base URL is https://capslane.com.

GET

/v1/transcript

Return a transcript immediately or start a generation job for a public YouTube video.

Query parameters

Name	Type	Required	Description
`url`	string	Yes	YouTube URL or 11-character video ID.
`lang`	string	No	Preferred ISO language code.
`mode`	enum	No	`auto`, `native` or `generate`.
`text`	boolean	No	Return one plain text string when true.
`chunkSize`	number	No	Maximum 50 to 10,000 characters per segment.

200 response

JSON

{
  "lang": "en",
  "availableLangs": ["en", "fr"],
  "content": [
    {
      "text": "Never gonna give you up...",
      "offset": 18800,
      "duration": 1000,
      "lang": "en"
    }
  ],
  "source": "native",
  "cached": false,
  "requestId": "req_..."
}

GET

/v1/transcript/:jobId

Generated transcripts can return HTTP 202. Poll the job endpoint with the same API key until the status is completed or failed.

202 JSON

{
  "jobId": "job_550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "progress": 35,
  "requestId": "req_..."
}

Errors

Errors use JSON and include a request ID for support and log correlation.

Status	Code	Meaning
400	`invalid_video_id`	The URL or video ID is invalid.
401	`invalid_api_key`	The API key is missing or revoked.
404	`job_not_found`	The job does not belong to this workspace.
429	`monthly_limit_exceeded`	The workspace reached its monthly limit.
404	`transcript_unavailable`	No native transcript is available in native mode.
502	`upstream_unavailable`	The transcript worker could not complete the request.

Monitor the workspace

The Overview shows monthly usage, success rate, cache rate, latency and recent API activity.

Capslane Overview with usage metrics and request chart — Overview keeps usage and service health in one place.

Test a request

The Playground runs through the server, so you can inspect the real response without exposing an API key in the browser.

Capslane Playground request form and JSON response panel — Choose the language, mode and output format before sending a request.

Limits and billing

One accepted transcript request reserves one unit from the workspace monthly allowance. Job status checks are not counted again. Limits reset at the start of each billing period.

NextView plans