YouTube Summary

Download a YouTube video's subtitle track and generate a concise plain-text AI summary in Cantonese, Mandarin, English, Japanese, or Korean. The endpoint accepts a YouTube URL (watch, youtu.be, shorts, or embed) or a raw 11-character video ID and returns both the full transcript and the generated summary.

POST/api/youtube-summary/summarize-from-url

Request Parameters

This endpoint accepts a JSON body. Authenticate with your API key using the x-api-key header (or pass api_key in the body).

Parameter	Type	Required	Description
api_key	string	Yes	Your API key (also accepted via `x-api-key` header).
url	string	Yes	YouTube link (`youtube.com/watch?v=…`, `youtu.be/…`, `/shorts/…`, `/embed/…`) or a raw 11-character video ID such as `jcTJoqU_k8U`.
summaryLanguage	string	No	Output language for the summary. One of `cantonese` (Traditional Chinese, Hong Kong style), `mandarin` (Simplified Chinese), `english`, `japanese`, `korean`. Defaults to `cantonese`.
subtitleLanguage	string	No	Caption track to download (e.g. `Cantonese (auto-generated)`, `English`). Defaults to the first available track. Use `/api/youtube-summary/list-languages` to enumerate the available tracks for a given video.
transcript	string	No	Optional. If supplied, the server skips re-downloading the transcript from YouTube and summarizes the provided text directly. Useful for re-summarizing a previously fetched transcript in a different language.

Example Request

Examples for cURL, Python, and JavaScript:

to auto-fill your API key in the code examples below.

curl -X POST https://cantonese.ai/api/youtube-summary/summarize-from-url \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "url": "https://www.youtube.com/watch?v=36dUbDtwZEI",
    "summaryLanguage": "cantonese"
  }'

Response

On success, the API returns the full transcript along with an AI-generated summary in the requested language:

{
  "success": true,
  "videoId": "36dUbDtwZEI",
  "title": "年輕人躺平，不捱苦不婚不生！...",
  "subtitleLanguage": "Cantonese (auto-generated)",
  "summaryLanguage": "cantonese",
  "transcript": "一定係一個好大嘅轉變會嚟緊就係話拆翻開 ...",
  "summary": "呢條片係一個關於 Gen Z 嘅深入訪談 ..."
}

Response Fields

Field	Type	Description
success	boolean	`true` when a summary was produced; `false` with a `message` field on failure.
videoId	string	The 11-character YouTube video ID resolved from the input.
title	string	YouTube video title (when available).
subtitleLanguage	string	The caption track that was actually used.
summaryLanguage	string	Echoes the requested output language.
transcript	string	Full plain-text transcript downloaded from the chosen subtitle track.
summary	string	Plain-text AI-generated summary in the requested language. No Markdown formatting is emitted.

Quota

Each successful request consumes one YouTube Summary credit from your monthly quota. Free tier includes 5 requests/month; paid tiers scale up to 400. Track usage via /api/youtube-summary/get-usage or the dashboard.

Status Codes

Status Code	Description
200	Returned for both successful summaries and recoverable application errors. Always check the `success` field. `message` values include `Invalid YouTube URL or video ID`, `No subtitles available`, `Failed to fetch caption tracks`, `Failed to download transcript`, `Empty transcript`, `quota_exceeded`, and `Failed to summarize`.
401	Unauthorized — missing/invalid API key, or the user is blocked.