Batch Transcripts¶
Transcript extraction for a list of videos in one job. Submit up to 20 URLs, get a jobId back immediately, then poll until the job completes. Failed videos never fail the job - each result carries its own status.
| Method | Endpoint | Purpose |
|---|---|---|
POST |
/v1/youtube/transcript/batch |
Submit a batch of URLs (returns 202 + jobId) |
GET |
/v1/youtube/transcript/batch/{job_id} |
Poll job status and retrieve per-video results |
For a single video, use GET /v1/youtube/transcript instead - it returns segments synchronously.
Base URL¶
https://media.toolkitapi.io
Requires an X-API-Key header.
1. Submit a job¶
curl -X POST "https://media.toolkitapi.io/v1/youtube/transcript/batch" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"https://www.youtube.com/watch?v=9bZkp7q19f0"
],
"lang": "en"
}'
{"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}
Request body¶
| Field | Type | Default | Description |
|---|---|---|---|
urls |
string[] | required | 1-20 YouTube URLs or bare video IDs |
lang |
string | null |
Preferred caption language, e.g. en, de, ja. Falls back to the video's default track |
Response¶
202 Accepted
| Field | Description |
|---|---|
jobId |
Opaque job identifier used for polling |
2. Poll for results¶
curl "https://media.toolkitapi.io/v1/youtube/transcript/batch/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
-H "X-API-Key: YOUR_KEY"
import time
import requests
HEADERS = {"X-API-Key": "YOUR_KEY", "Content-Type": "application/json"}
BASE = "https://media.toolkitapi.io/v1/youtube/transcript/batch"
def batch_transcripts(urls: list[str], lang: str = "en", timeout: float = 180.0) -> dict:
job_id = requests.post(
BASE, headers=HEADERS, json={"urls": urls, "lang": lang}, timeout=30
).json()["jobId"]
deadline = time.monotonic() + timeout
delay = 1.0
while time.monotonic() < deadline:
job = requests.get(f"{BASE}/{job_id}", headers=HEADERS, timeout=30).json()
if job["status"] in {"completed", "failed"}:
return job
time.sleep(delay)
delay = min(delay * 1.5, 5.0) # gentle backoff
raise TimeoutError(f"batch job {job_id} still running after {timeout}s")
job = batch_transcripts(
[
"https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"https://www.youtube.com/watch?v=9bZkp7q19f0",
]
)
for item in job["results"]:
if item["status"] == "succeeded":
words = sum(len(seg["text"].split()) for seg in item["content"])
print(item["id"], item["lang"], f"{words} words")
else:
print(item["id"], item["error_code"], item["error"])
const HEADERS = { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" };
const BASE = "https://media.toolkitapi.io/v1/youtube/transcript/batch";
async function batchTranscripts(urls, lang = "en") {
const submit = await fetch(BASE, {
method: "POST",
headers: HEADERS,
body: JSON.stringify({ urls, lang }),
});
const { jobId } = await submit.json();
for (;;) {
const res = await fetch(`${BASE}/${jobId}`, { headers: HEADERS });
const job = await res.json();
if (job.status === "completed" || job.status === "failed") return job;
await new Promise((r) => setTimeout(r, 2000));
}
}
A 2-second poll interval is plenty; these jobs finish in seconds for short videos. Do not poll faster than once per second.
Response¶
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "completed",
"results": [
{
"id": "dQw4w9WgXcQ",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"status": "succeeded",
"lang": "en",
"content": [
{"text": "We're no strangers to love", "offset": 0.0, "duration": 3.4, "lang": "en"},
{"text": "You know the rules and so do I", "offset": 3.4, "duration": 3.1, "lang": "en"}
]
},
{
"id": "not-a-video",
"url": "not-a-video",
"status": "failed",
"error_code": "invalid-request",
"error": "Could not parse video ID from: not-a-video"
}
],
"stats": {"total": 2, "succeeded": 1, "failed": 1},
"completedAt": "2026-10-17T04:12:09.331Z"
}
| Field | Description |
|---|---|
jobId |
Job identifier |
status |
queued, active, completed, or failed |
results |
Per-video outcomes; [] while queued/active |
results[].id |
Video ID (or the raw input, when unparseable) |
results[].url |
Canonical video URL |
results[].status |
succeeded or failed |
results[].content |
Timed segments - present only on success |
results[].lang |
Language the transcript was fetched in |
results[].error_code |
invalid-request or transcript-not-found |
results[].error |
Human-readable failure reason |
stats |
Aggregate counts, present once results exist |
completedAt |
ISO-8601 completion timestamp |
Segment shape¶
Each segment in content is:
{"text": "...", "offset": 12.7, "duration": 2.9, "lang": "en"}
offset and duration are in seconds (floats, not HH:MM:SS). To build a timestamped SRT or readable transcript:
def to_srt(segments: list[dict]) -> str:
def stamp(sec: float) -> str:
h, rem = divmod(int(sec), 3600)
m, s = divmod(rem, 60)
return f"{h:02}:{m:02}:{s:02},000"
lines = []
for idx, seg in enumerate(segments, start=1):
start = seg["offset"]
lines.append(f"{idx}\n{stamp(start)} --> {stamp(start + seg['duration'])}\n{seg['text']}\n")
return "\n".join(lines)
Behaviour to know¶
- No transcript ≠ job failure. Videos without captions come back as
failedwitherror_code: transcript-not-found(404semantics) while the job still reportscompleted. - Language fallback. If
langis unavailable, the service returns whatever track the video has and reports the actual language inresults[].lang. Check it before assuming. - Job expiry. Jobs are kept in memory with a TTL - poll promptly, and persist results once you have them. A
404on the status endpoint means the job expired or never existed. - No retries inside the batch. A failed item is not retried; resubmit just those URLs if you want another attempt.
Errors¶
| Status | Meaning |
|---|---|
202 |
Job accepted |
401 |
Missing or invalid X-API-Key |
404 |
Unknown or expired job_id |
422 |
Body validation - empty urls or more than 20 entries |
Related¶
GET /v1/youtube/transcript- single-video, synchronous transcript endpointGET /v1/youtube/video- titles, stats, and tags for the same videos- Media Conversion - transcode the downloaded video to audio