Threadmap

Developer API

YouTube Transcript API.
One API call.

Send a YouTube URL or video ID. Get a clean, timestamped transcript as structured JSON—ready for your product, agent, or workflow.

Create API account Try the free extractor

Captions free · 20 audio credits included · no card required

Live APIJSON
POST /api/v1/transcripts

{
  "video_id": "dQw4w9WgXcQ",
  "mode": "auto"
}

200 OK
{
  "language": "en",
  "mode": "auto",
  "duration_seconds": 212,
  "transcript": "We're no strangers...",
  "segments": [
    { "start": 0.0, "text": "We're..." }
  ]
}
01

Built for products

Predictable JSON, clear errors, and timestamps you can use immediately.

02

One simple input

Send a full YouTube URL or the 11-character video ID.

03

Ready to automate

Use transcripts in agents, search, research, and content workflows.

01

captions

Return existing YouTube captions only. Fastest and most economical.

02

auto

Try captions first, then transcribe the audio with OpenAI when needed.

03

transcribe

Skip captions and create a fresh transcript directly from the video audio.

Quickstart

One endpoint. Any server stack.

Send your API key as a Bearer token. Keys belong on your server—never expose them in browser JavaScript.

curl

curl https://threadmap.online/api/v1/transcripts \
  -X POST \
  -H "Authorization: Bearer tm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"video_id":"dQw4w9WgXcQ","mode":"auto"}'

JavaScript · Node.js

const response = await fetch(
  "https://threadmap.online/api/v1/transcripts",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer tm_live_YOUR_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ video_id: "dQw4w9WgXcQ", mode: "auto" })
  }
);

const data = await response.json();
if (!response.ok) throw new Error(data.error.message);
console.log(data.transcript);

Python

import requests

response = requests.post(
    "https://threadmap.online/api/v1/transcripts",
    headers={"Authorization": "Bearer tm_live_YOUR_KEY"},
    json={"video_id": "dQw4w9WgXcQ", "mode": "auto"},
)
response.raise_for_status()
print(response.json()["transcript"])

Free video check

Inspect metadata and caption languages before requesting audio transcription.

GET /api/v1/videos/info uses the same Bearer API key but consumes zero credits. Send either video_id or url.

Request

curl "https://threadmap.online/api/v1/videos/info?video_id=dQw4w9WgXcQ"   -H "Authorization: Bearer tm_live_YOUR_KEY"

Response · 0 credits

{
  "video_id": "dQw4w9WgXcQ",
  "title": "Never Gonna Give You Up",
  "channel_name": "Rick Astley",
  "captions_status": "available",
  "available_languages": [
    { "code": "en", "generated": false }
  ],
  "credits_used": 0
}

Remote MCP

Connect Threadmap to your AI agent.

Use the Streamable HTTP endpoint with the same Bearer API key. Existing captions and cached results are free; fresh audio transcription uses the same Threadmap Credit balance as the REST API.

Connection

URL https://threadmap.online/mcp
Transport Streamable HTTP
Authorization Bearer tm_live_YOUR_KEY

Available tools

get_youtube_transcript
  url | video_id
  mode: captions | auto | transcribe

get_transcript_usage
  no arguments

Usage

Check the current credit balance.

The same server-side API key can read its current non-expiring Threadmap Credit balance.

curl

curl https://threadmap.online/api/v1/usage   -H "Authorization: Bearer tm_live_YOUR_KEY"

Response

{
  "billing_mode": "credits",
  "balance_credits": 852,
  "remaining_credits": 852,
  "audio_equivalent_minutes": 852,
  "credits_expire_at": null
}

API reference

Request parameters and limits.

Send exactly one video identifier. The default auto mode uses captions when available and falls back to audio transcription.

FieldTypeRequiredDescription
video_idstringEither/orAn 11-character YouTube video ID. Do not send it together with url.
urlstringEither/orA public YouTube video, Short, embed, or live-stream URL. Do not send it together with video_id.
modestringNocaptions, auto, or transcribe. Defaults to auto.
Rate limit10 requests/minute

Applied per API key. A rejected request returns 429 RATE_LIMIT_EXCEEDED.

Video limitsNo per-video limit

Caption retrieval and paid audio transcription are billed or processed by the video's actual duration. Fresh audio is charged per started audio minute.

Response sizeUp to 180,000 characters

If a transcript exceeds the response limit, truncated is true.

Threadmap Credits

How usage is calculated.

Credits belong to the account, not to an individual key, and they do not expire. They are used only when Threadmap creates a fresh transcript from audio.

01

Pay only for fresh audio

Existing captions and cached transcripts cost 0 credits. Fresh audio costs max(1, ceil(duration_seconds / 60)) credits.

02

Only successful results are charged

Validation errors, unavailable videos, worker failures, and requests rejected before completion do not debit credits. The account must have enough credits for the complete result.

03

Captions and cache are free

API, MCP, and playlist requests use zero credits when an existing or cached transcript can be returned.

04

Read the balance before audio work

Use GET /api/v1/usage or the X-Credits-Remaining response header. Insufficient balance returns HTTP 402 only when fresh audio transcription is required.

Errors

Consistent JSON errors.

Every API error includes a request ID. Include it when contacting support. Retry only 429 and temporary 5xx responses, using exponential backoff.

402 Payment Required
{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "There are no Threadmap Credits remaining...",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
HTTPCodeMeaning
400INVALID_JSON, INVALID_REQUESTThe body is not valid JSON or is not a JSON object.
400INVALID_URL, INVALID_VIDEO_ID, AMBIGUOUS_INPUT, INVALID_MODEThe input fields are invalid or conflicting.
401INVALID_API_KEYThe Bearer key is missing or invalid.
402INSUFFICIENT_CREDITSFresh audio transcription was required and the balance was too low. Existing or cached transcripts remain free.
403API_KEY_REVOKED, API_KEY_EXPIREDThe key can no longer be used.
404VIDEO_UNAVAILABLEThe video is private, removed, or otherwise unavailable.
422VIDEO_TOO_LONG, VIDEO_DURATION_UNKNOWN, EMPTY_TRANSCRIPT, TRANSCRIPT_DISABLED, TRANSCRIPT_UNAVAILABLEThe request is valid, but the video cannot produce a supported transcript.
429RATE_LIMIT_EXCEEDEDThe API key exceeded 10 requests in one minute.
500–503TRANSCRIPT_FAILED, TRANSCRIPT_WORKER_ERROR, CAPTION_FETCH_TEMPORARY, YOUTUBE_RATE_LIMIT, API_STORAGE_UNAVAILABLE, LIBRARY_SAVE_FAILEDA temporary Threadmap, YouTube, worker, or storage failure occurred. Retry temporary caption errors before switching to audio transcription.

Useful response headers

X-Request-Id identifies the request, X-RateLimit-Limit shows the per-minute request limit, and X-Credits-Remaining reports the balance after a successful response.

Start building

Your API key is one sign-in away.

Create an account, copy your server-side key, and use the included 20 audio credits before buying anything. Existing captions remain free.

Start with 20 free credits No card required. Paid credits never expire. Create account

Questions

Is the API live?

Yes. Create an account to receive your API key and 20 audio credits immediately. No card is required.

Which videos are supported?

Public YouTube videos. Transcript availability can depend on captions and video accessibility.

How does pricing work?

Existing captions and cached transcripts are free. Choose 400 credits for $4, 1,200 for $9, or 4,000 for $25 USD when you need fresh audio transcription at 1 credit per minute. Packs are one-time payments and do not expire.

Can I test Threadmap today?

Yes. Use the free extractor without an account, or create an API key with 20 included audio credits.