Scority

YouTube API Transcript Guide

Learn how to fetch YouTube transcripts with an API, when the official YouTube Data API is not enough, and how Scority returns text and segments.

View API docsRead captions guide
Direct answer

How to get a transcript from a YouTube video via API

Use a transcript-specific endpoint that accepts a YouTube video ID or URL and returns transcript text plus timestamped segments. In Scority, the current endpoint is GET /v1/youtube/transcript on https://api.scority.ai.

  • Send exactly one of video_id or video_url.
  • Authenticate with the x-api-key header from server-side code.
  • Use language or lang when you want to request a caption language.
  • Handle transcript_not_available and upstream_transcript_failed as normal integration cases.
Search intent

Why YouTube API transcript is confusing

People use the phrase YouTube API transcript for several different jobs: the official YouTube Data API, caption track management, browser scraping, open-source transcript libraries, and hosted transcript APIs. Those are not the same thing.

  • If you need official video metadata, channel data or search, start with the official YouTube Data API.
  • If you need transcript text for AI workflows, use a transcript-specific API or library.
  • If you use Scority, your app receives JSON with language, source, text and segments.
Official API

Official YouTube Data API vs transcript-specific API

The official YouTube Data API is the right tool for many YouTube platform tasks, but transcript extraction has different requirements. A transcript workflow needs readable text, segment timing and clear errors when captions are missing or upstream access fails.

  • Use the official API for official metadata and platform workflows.
  • Use a transcript API when your app needs spoken video content as text.
  • Do not treat Scority as a replacement for every YouTube API use case.
  • Do treat Scority as a focused transcript and captions endpoint for server-side apps.
Scority flow

How Scority handles transcript requests

Scority validates the video input, checks authentication and quota, selects an accessible caption path, then returns a normalized JSON response when a transcript is available.

  • video_id should be the 11-character YouTube video ID.
  • video_url is useful when your app stores full YouTube links.
  • language and lang are aliases; send only one.
  • The public web /api/transcript proxy is disabled. Use https://api.scority.ai with an API key.

Request by video ID

curl "https://api.scority.ai/v1/youtube/transcript?video_id=dQw4w9WgXcQ" \
  -H "x-api-key: YOUR_API_KEY"

Request by video URL

curl "https://api.scority.ai/v1/youtube/transcript?video_url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ" \
  -H "x-api-key: YOUR_API_KEY"
Response

Response shape

A successful response includes the selected caption language, transcript source, full text and timestamped segments.

  • language: selected caption language when available.
  • source: transcript source such as caption_track_direct.
  • text: full transcript text.
  • segments: ordered transcript segments with text, start and duration.
Errors

Common transcript API errors

Build error handling around stable error codes instead of scraping messages. Scority returns normalized JSON errors under error.code.

  • invalid_video_id and invalid_video_url mean the request input should be fixed.
  • ambiguous_request means both video_id and video_url were sent.
  • transcript_not_available means captions were not available for the requested video or language.
  • upstream_transcript_failed means the upstream fetch failed and may be worth retrying later.
Limitations

When this will not work

Transcript APIs depend on upstream access and usable source material. Scority uses caption-first extraction and can support fallback processing for harder videos, but some videos still cannot return transcript text safely.

  • Private, removed, region-restricted or captionless videos may fail.
  • A requested language may not exist for a given video.
  • Upstream caption access can fail even when a video page is visible in a browser.
  • Fallback processing is account-specific infrastructure, not an every-video guarantee.
Reference

API reference

See query parameters, response fields, errors and rate-limit headers.

Open →
Auth

Authentication

Use x-api-key safely from server-side code.

Open →
Errors

Error codes

Map each error code to a retry, input or support action.

Open →
Concepts

Transcript API guide

Read the broader YouTube Transcript API guide.

Open →