guide

YouTube and podcast transcripts by API, with timestamps

A transcript turns an hour of audio into text you can search, quote, summarize or hand to a language model. Getting one is fiddly: every platform hides its audio in a different place, media links expire, and a long episode takes longer to transcribe than most HTTP connections stay open. POST /v1/audio/transcript takes a URL and returns the transcript with timestamps, and an async variant handles long recordings. This guide covers both, plus subtitles, partial results and costs.

What you can transcribe

  • YouTube videos. The video's captions are used when it has them; otherwise the audio is transcribed.
  • Podcast episodes: an Apple Podcasts or Overcast episode page, or the episode's audio file URL from its RSS feed. Feed URLs themselves are refused; pass one episode.
  • X Spaces, SoundCloud, TikTok and Facebook video posts.
  • Direct links to MP3, M4A, WAV or OGG files.

One request takes up to 4 hours or 250 MB of audio. You need a ScrapeNest key: sign up, verify your email address, then mint a key on the dashboard. The free plan includes 1,000 credits a month.

A short clip, in one call

For a clip of up to about 90 seconds, the synchronous call returns the transcript in the response. In Python:

import os
from scrapenest import Client

client = Client(os.environ["SCRAPENEST_API_KEY"])

t = client.audio_transcript("https://www.youtube.com/watch?v=dQw4w9WgXcQ", language="en")
print(t.title, "|", t.channel, "|", t.duration_seconds, "seconds")
print(t.text[:500])
for chunk in (t.chunks or [])[:5]:
    print(f"{chunk.start:7.1f}s  {chunk.text}")

In TypeScript:

import { ScrapeNest } from "scrapenest";

const client = new ScrapeNest({ apiKey: process.env.SCRAPENEST_API_KEY ?? "" });

const t = await client.audioTranscript({ url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ" });
console.log(t.title, t.duration_seconds, t.text.slice(0, 500));

The language field is an optional ISO 639-1 hint such as en, es or ja. Leave it out and the language is detected.

A full episode, as a background job

Requests to the API time out after about 100 seconds, so anything longer than a short clip belongs on the async variant. POST /v1/audio/transcript/async takes the same body and returns 202 Accepted with a run_id. Poll GET /v1/scrape/runs/{run_id} until the run completes; its result holds the same body the synchronous call returns.

run = client.audio_transcript_async("https://podcasts.apple.com/us/podcast/.../id...?i=...")
final = client.wait_for_run(run.run_id, poll_interval=5, timeout=1800)

if final.status == "completed":
    result = final.result
    print(result.get("title"), result.get("duration_seconds"))
    print(result["text"][:500])
else:
    print(final.status, final.error_code, final.error_message)

The TypeScript client has the same calls as audioTranscriptAsync and waitForRun. With curl:

RUN=$(curl -s -X POST https://scrapenest.dev/v1/audio/transcript/async \
  -H "Authorization: Bearer $SCRAPENEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}' | jq -r .run_id)

curl -s https://scrapenest.dev/v1/scrape/runs/$RUN \
  -H "Authorization: Bearer $SCRAPENEST_API_KEY" | jq '{status, credits_charged}'

Polling is free and counts toward your rate limit; every few seconds is fine. wait_for_run gives up after 300 seconds unless you pass a longer timeout, while the job keeps running on the server, and runs expire after seven days.

Timestamps, chapters and subtitles

Every response has a text field with the whole transcript. When the source provides timing, it also has a chunks array, each entry with start, end and text in seconds. Chunks are what you need for captions, jump-to links, chapter lists and time-anchored embeddings for retrieval. Some podcast feeds and short clips come without timing, so treat chunks as optional.

Writing chunks out as an SRT subtitle file takes a few lines:

def srt_time(seconds):
    ms = int(round(seconds * 1000))
    h, ms = divmod(ms, 3_600_000)
    m, ms = divmod(ms, 60_000)
    s, ms = divmod(ms, 1000)
    return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"

chunks = final.result.get("chunks") or []
with open("episode.srt", "w", encoding="utf-8") as srt:
    for number, chunk in enumerate(chunks, 1):
        srt.write(f"{number}\n")
        srt.write(f"{srt_time(chunk['start'])} --> {srt_time(chunk['end'])}\n")
        srt.write(chunk["text"].strip() + "\n\n")

For chapters, hand the chunks to a language model with an instruction such as "Group these into 5 to 10 chapters, each with a start time taken from the chunks." Because every chunk already carries its time, the chapters line up with the audio.

Feeding a transcript to a language model

An hour of conversation runs to many thousands of words, often more than you want in a single prompt. Split the transcript along chunk boundaries into pieces of a few thousand words, summarize each piece, then summarize the summaries. Keep the first start time of each piece next to its summary, so an answer about the episode can point to the minute where something was said.

Partial transcripts

If part of a long recording still cannot be transcribed after retries, the response returns the rest with partial: true and missing_ranges, a list of [start, end] spans in seconds. Only the covered time is billed, and a partial result is not cached, so a retry runs fresh. Neither field appears on a complete transcript.

Videos that need a signed-in session

Some YouTube videos can only be downloaded from a signed-in session, such as age-restricted videos or videos without captions that YouTube will not serve anonymously. Those come back as 401 login_required. The REST API accepts a cookies field holding the contents of a Netscape-format cookies.txt, exported from a browser that is signed in to YouTube. Use a separate account rather than your personal one, because the requests made with those cookies are tied to that account. The cookies section of the docs walks through the export. Requests with cookies are never cached.

Errors worth handling

CodeMeaning
400 invalid_audio_sourceThe URL is a podcast feed, not an episode.
401 login_requiredThe source needs a signed-in session.
403 audio_privateThe audio is private or members-only.
410 audio_not_availableThe audio was removed.
413 audio_too_long, audio_too_largeLonger than 4 hours, or larger than 250 MB.
422 audio_is_live, audio_not_readyA live broadcast, or one that has ended with no replay yet.
422 drm_protectedThe audio is DRM-protected. Try the same episode on another platform.
451 geo_restrictedThe source blocks the region the audio is fetched from.

The audio error table lists the rest. A failed async run reports the same codes in its error_code.

What it costs

Transcription costs 20 credits per 2 minutes of audio, rounded up, with a minimum of 20 credits. The async variant costs the same.

RecordingCredits
1 minute20
3 minutes40
30 minutes300
1 hour600
2 hours1,200

Transcripts are cached for 30 days by default, so requesting the same URL again bills 1 credit; set cache_ttl_seconds to change the window. The free plan's 1,000 monthly credits cover about 100 minutes of audio, and paid plans start at $29 a month for 200,000 credits. See pricing.

Transcripts from an AI assistant

The ScrapeNest MCP server exposes the same endpoint as the audio_transcript tool. Give Claude, Cursor or ChatGPT an episode link and ask for a summary: the tool runs the transcription as a background job and returns a run_id for poll_run when it needs more than about a minute. The MCP tool does not take cookies, so gated videos go through the REST API.

1,000 free credits a month

Run this guide with free credits

Sign up, verify your email, then mint a key on the dashboard. The free plan includes 1,000 credits a month and needs no card.