YouTube Video Summary API: Automate Structured Summaries at Scale

What the Summary API Does

The ReelWords summary API takes a YouTube video URL and returns a structured summary object — key points, actionable takeaways, quotes, facts, entities, and topical metadata.

It handles the full pipeline in one call. You don't need to fetch a transcript first, manage a transcription job, or prompt a language model yourself. Submit a URL, get structured JSON back.

This is aimed at teams building research tooling, content pipelines, media monitoring, and internal knowledge systems on top of video content.

Authentication

The endpoint accepts either an API key or a session token.

API key — the right choice for server-to-server automation. Pass it in either header:

x-api-key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

Supabase access token — used by the web app, also accepted as a bearer token if you're building against an authenticated user session.

Requests without valid credentials return 401 unauthorized.

Creating a Summary

POST /api/v1/summarize

Request body:

A minimal request:

curl -X POST https://reelwords.ai/api/v1/summarize \
  -H "x-api-key: $REELWORDS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"video_url": "https://youtube.com/watch?v=VIDEO_ID"}'

The legacy path /api/summarize remains available and behaves identically, so existing integrations don't need to change.

Accepted URL Formats

The video ID is extracted from any of these:

• https://youtube.com/watch?v=VIDEO_ID
• https://youtu.be/VIDEO_ID
• https://youtube.com/shorts/VIDEO_ID
• https://youtube.com/embed/VIDEO_ID
• A bare 11-character video ID

Anything that doesn't resolve to a YouTube video ID returns 400 invalid_url. The summary API is YouTube-only. For TikTok, Instagram, and Facebook video, use the transcription API, which accepts a much broader range of public social URLs.

Response Shape

A successful call returns:

{
  "success": true,
  "fromCache": false,
  "data": {
    "id": "...",
    "videoId": "VIDEO_ID",
    "videoUrl": "https://youtube.com/watch?v=VIDEO_ID",
    "summaryText": "...",
    "keyPoints": ["..."],
    "actionableTakeaways": ["..."],
    "factsAndExamples": ["..."],
    "memorableQuotes": ["..."],
    "mentionedEntities": ["..."],
    "transcription": "...",
    "category": "...",
    "tags": ["..."],
    "estimatedReadTime": "...",
    "toneAnalysis": "..."
  }
}

Note that transcription contains the full transcript text used to build the summary. If your pipeline needs both, one call gets you both.

The Caching Behaviour Matters

Summaries are cached globally by video ID. When a request comes in for a video that has already been summarized — by your account or any other — the stored summary is returned with fromCache: true.

Two properties worth designing around:

1. Cache hits are checked before the quota check. A cached response does not consume any of your monthly allowance. Re-requesting the same video costs nothing.
2. Cache hits are fast. No transcription, no model call.

If you're building a system that repeatedly processes overlapping sets of videos — media monitoring, a shared research corpus, a public-facing tool — your effective throughput is considerably higher than your nominal limit.

Handling the Transcript Step

If you don't supply transcript_text, the API creates a transcription job and polls for it internally, waiting up to roughly 55 seconds.

If the transcript doesn't complete in that window, you get:

504 timeout

This is not a permanent failure — it means the job was still running. Retrying the same URL shortly after will often succeed, since the transcription may have completed in the background.

Supplying your own transcript avoids this entirely. If you already hold transcript text, pass it in transcript_text and the call skips retrieval and goes straight to summarization. This is the fastest and most reliable path for high-volume pipelines.

Checking Usage

GET /api/v1/summarize/usage

Returns:

{
  "used": 12,
  "limit": 50,
  "remaining": 38,
  "summaryCreditBalance": 30,
  "planTier": "pro"
}

Poll this before batch runs so you can throttle rather than collect 402 responses.

Errors You Should Handle

402 is the one to design around properly. When the monthly limit is reached, the API automatically draws on top-up credits if the account has any. Only when both are exhausted does the request fail — so a 402 means genuinely out of capacity, not just past the plan limit.

Limits by Plan

Limits reset on a rolling 30-day basis. Cached responses don't count. See pricing for current plan details.

Batch Processing Pattern

For processing a set of videos reliably:

1. Call /usage and confirm you have headroom for the batch.
2. Process sequentially or with modest concurrency — the transcript stage is the bottleneck, not the model.
3. Treat 504 as retryable with backoff; the transcription usually finishes shortly after.
4. Treat 402 as a hard stop and surface it rather than silently dropping videos.
5. Persist results keyed by videoId on your side too, so you're not dependent on the shared cache for your own repeat lookups.

FAQ

Is there an API to summarize YouTube videos?

Yes. POST /api/v1/summarize accepts a YouTube URL and returns a structured summary including key points, takeaways, quotes, facts, and entities.

Can the API summarize TikTok or Instagram videos?

No. The summary endpoint is YouTube-only and returns 400 invalid_url for other platforms. The transcription API supports a much wider range of public social video URLs.

Do cached summaries count against my monthly limit?

No. The cache is checked before the quota, so requesting an already-summarized video returns instantly without consuming allowance.

Can I supply my own transcript?

Yes. Pass transcript_text in the request body and the API skips the retrieval step. This is faster and avoids the transcript timeout path entirely.

What model does the summarizer use?

gemini-2.5-pro by default. You can pass a different value in the model field.

What happens when I run out of summaries?

The API automatically consumes top-up credits if the account has any. Once both the monthly limit and credit balance are exhausted, requests return 402 usage_limit_reached.

Is the full transcript included in the response?

Yes. The transcription field on the response contains the transcript text used to generate the summary.

Get Started

Generate an API key from your account, then send a single POST with a YouTube URL. Full endpoint documentation is at reelwords.ai/docs/api.

If your pipeline also needs transcripts from non-YouTube sources, the social video transcription API covers TikTok, Reels, Shorts, and Facebook video.

The same API key also drives caption rendering — see the auto captions feature set for what can be produced from a transcript, pricing for plan limits, and the FAQ for API and billing questions.