API reference

Get one transcript

curl -G "https://cuebaseapi.com/api/v1/transcript" \
  --data-urlencode "video=https://www.youtube.com/watch?v=cbDemoVide1" \
  -d "format=json" \
  -H "Authorization: Bearer cb_live_demo_local_only_key_0001"

`video` accepts a watch URL, a youtu.be URL, a shorts URL, an embed URL, or an 11 character id. `url` and `id` are accepted aliases. `language` is a BCP 47 tag. `format` is json, txt, srt, or vtt. `timestamps=true` adds times to txt output. JSON always includes segments.

JSON responses include `creditsCharged`, `cacheHit`, and `balance`. Text responses put the same facts in X-Credits-Charged, X-Cache-Hit, and X-Credit-Balance.

Batch

curl -X POST "https://cuebaseapi.com/api/v1/transcripts" \
  -H "Authorization: Bearer $CUEBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"videos":["cbDemoVide1","https://youtu.be/cbDemoVide1"],"format":"txt"}'

Send 1 to 10 videos. The response is JSON. Each result has `ok`, and a success includes `transcript` plus `rendered` in the format you asked for. A batch is refused before any fetch when the balance is below the number of cache misses.

Video metadata

curl "https://cuebaseapi.com/api/v1/videos/cbDemoVide1" \
  -H "Authorization: Bearer $CUEBASE_API_KEY"

The metadata call fills the same cache as a transcript call. A later transcript for that video and language costs 0 credits.

Account

curl "https://cuebaseapi.com/api/v1/account" -H "Authorization: Bearer $CUEBASE_API_KEY"

MCP

The streamable HTTP endpoint is https://cuebaseapi.com/api/mcp. Responses use JSON. Send the same bearer token, and send `Accept: application/json, text/event-stream`.

{
  "mcpServers": {
    "cuebase": {
      "url": "https://cuebaseapi.com/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}

Tools: `get_transcript`, `get_video`, `get_transcripts`, `get_account`. `get_account` is free.

Credits and limits

• A cache miss that returns captions costs 1 credit.
• A cache hit costs 0 credits.
• not_found, no_captions, and upstream failures cost 0 credits and are not cached.
• Manual caption tracks stay cached. Auto-generated tracks refresh after 30 days.
• Each key can record 60 usage rows per minute. A batch writes one row per video.
• The public paste box allows 5 successful transcripts per IP per UTC day.

Errors

{ "error": { "code": "insufficient_credits", "message": "..." } }

• 400 invalid_request
• 401 unauthorized
• 402 insufficient_credits
• 404 not_found, no_captions, age_restricted, or video_unavailable
• 408 timeout, with Retry-After, when the fetch budget runs out
• 429 rate_limited or daily_limit
• 502 upstream, or 503 when every proxy attempt is blocked or the monthly proxy budget is nearly spent