On this page6 sections
Any app that turns YouTube links into text runs into videos with no captions. That includes summarizers, search over a channel's talks, study tools and RAG pipelines. Music videos, screen recordings, very new uploads and a lot of non-English videos come back empty. The code usually fails in one of three ways:
- It returns nothing and calls it success. A caption-only scraper gets an empty list, and the user sees a blank transcript with no explanation.
- It can't tell "no captions" from "blocked". On a server, the same request that would list caption tracks gets refused, so you can't even find out whether captions exist.
- The fallback is a second pipeline. Speech-to-text means downloading the media, pulling out the audio, sending it to a vendor and stitching the result back into the shape your app expects.
Checking for captions yourself
There are two free ways to find out whether a video has captions before you try to fetch them.
The YouTube Data API. captions.list with the video ID returns one entry per caption track. Each entry has a trackKind: standard for captions the uploader added, asr for YouTube's automatic ones. An empty list means no captions. It needs an API key and costs 50 quota units a call, so the default daily quota covers about 200 checks. It only tells you that tracks exist. captions.download works only on videos the signed-in account can edit, so it can't fetch the text of someone else's video.
A transcript library. In Python, youtube-transcript-api can list the tracks and tell generated from uploaded ones:
from youtube_transcript_api import YouTubeTranscriptApi, TranscriptsDisabled
try:
tracks = YouTubeTranscriptApi().list(video_id)
for t in tracks:
print(t.language_code, 'auto' if t.is_generated else 'uploaded')
except TranscriptsDisabled:
print('no captions')On your own machine this is the right answer, and it's free. From a cloud server it often never gets that far. When we ran it from a cloud machine, YouTube refused the request and the library raised RequestBlocked ("YouTube is blocking requests from your IP"), so the check said nothing about captions at all. You still need a speech-to-text fallback for the videos that really have none.
Check without paying: captions only
Importly takes the same link from your server. Send "mode": "captions" to ask for captions and nothing else:
curl -X POST https://api.importly.io/transcribe \
-H "Authorization: Bearer $IMPORTLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://www.youtube.com/watch?v=<id>",
"mode": "captions",
"wait": true
}'If the video has captions, uploaded or auto-generated, you get the transcript for $0.003. If it has none, the job fails with TRANSCRIPTION_PROVIDER_REQUIRED, nothing is charged, and the response quotes what speech-to-text would cost:
{
"status": "failed",
"code": "TRANSCRIPTION_PROVIDER_REQUIRED",
"message": "This video has no captions. Add \"provider\": \"importly\" to transcribe it with AI speech-to-text ...",
"quote": { "provider": "importly", "estimatedMinutes": 1, "estimatedCostDollars": 0.01 }
}That gives your app a clear answer to show the user, for example "No captions. Transcribe it for about $0.01?". Private, removed and live videos fail with their own codes, so "no captions" never gets mixed up with "can't reach the video".
Or let it fall back in the same call
If you always want text back, send "mode": "auto". Importly uses the captions when there are some and runs speech-to-text when there aren't, all in one request. Set maxCostDollars so a three-hour video can't run up a bill you didn't expect:
curl -X POST https://api.importly.io/transcribe \
-H "Authorization: Bearer $IMPORTLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://www.youtube.com/watch?v=<id>",
"mode": "auto",
"wait": true,
"maxCostDollars": 0.5
}'The transcript has the same shape either way, so your code doesn't branch on where it came from:
sourceisplatform_captionswhen it came from captions andimportlywhen it came from speech-to-text.captionKindismanualorautofor captions, which is worth checking if you quote the text.data.segmentsholds{ start, end, text }with times in seconds: one per caption line, or one per sentence for speech-to-text.
Long videos can take longer than wait allows. Then the response has a jobId, and you collect the transcript from the status endpoint or a webhookUrl. Details are in the transcripts docs.
What it costs
- Captions, uploaded or auto-generated: $0.003 per video.
- No captions with
"mode": "captions": nothing. You get the quote instead. - Speech-to-text: $0.01 per started minute with a $0.01 minimum, and fetching the audio is included. A 10-minute talk with no captions is $0.10.
- Your own AssemblyAI, Deepgram or OpenAI key: $0.005 per minute plus their fees.
It's free to try, no card required. See pricing.
Have your AI agent build it in
Connect https://mcp.importly.io/mcp to Claude Code, Cursor or another coding agent and ask it to add transcripts with a no-captions fallback to your app. It writes the integration for your stack and tests real calls with your API key, and your backend uses the same key. The steps are in Have your agent build Importly into your app.
FAQ
How do I know if a YouTube video has captions?
The YouTube Data API's captions.list returns the video's caption tracks, and an empty list means none. With Importly, a "mode": "captions" request returns the transcript when there are captions and fails free with TRANSCRIPTION_PROVIDER_REQUIRED when there aren't.
Can I get a transcript of a YouTube video without subtitles?
Yes, with speech-to-text on the audio. Send "mode": "auto" and Importly does that only when the video has no captions, in the same request.
Are auto-generated captions good enough?
Usually for search, summaries and RAG. For quotes or subtitles people read, check captionKind: auto means YouTube generated them, and names and technical terms are often wrong.
Why does my caption check work locally but fail on my server?
YouTube blocks or challenges a lot of datacenter traffic, so the same request that lists tracks at home gets refused from a cloud server. Importly works the same from a server as from your laptop.
Related: Best YouTube transcript API, YouTube transcripts in Python, Video transcription API, Video link to SRT subtitles.