All guides
API

YouTube transcripts and summaries with the API

Submit a YouTube link, poll its job ID, then retrieve the generated summary and original saved transcript through separate authenticated API endpoints.

A transcript contains saved caption or speech-recognition text. A summary explains it for a specific question. tldw.sh saves both, so you can check the analysis against the source. The saved text retains any caption or transcription errors.

The workflow is submit → poll → retrieve. Send a YouTube link and optional instructions to POST /v1/analyses. Save the returned job ID, check its progress, then use the completed job's summary ID to read either output.

Prepare a scoped API key

Create your account, complete activation and create an API key in Developers. Grant jobs:write, jobs:read and summaries:read. Add account:read if your integration needs usage checks.

Provide the key as TLDW_API_TOKEN through your runtime's environment or secret manager. Keep it out of URLs, source control and model conversations. The following shell examples require curl, jq and Python 3. Use an accessible captioned video within your plan's source-length limit.

Save this body as analysis.json, replacing the example URL with your source if needed:

json
{
  "media": "https://www.youtube.com/shorts/af3oL9JMA1g",
  "instructions": "Explain the main point and the most useful takeaway. Avoid repetition.",
  "max_credits": 30
}

Create a request ID once and save it with the exact request body. Reuse both if the submission response is lost.

bash
set -euo pipefail
: "${TLDW_API_TOKEN:?Set TLDW_API_TOKEN privately before running these commands.}"
export TLDW_REQUEST_ID="$(python3 -c 'import uuid; print(uuid.uuid4())')"
curl --fail-with-body 'https://api.tldw.sh/v1/analyses' \
  -H "Authorization: Bearer $TLDW_API_TOKEN" \
  -H "Idempotency-Key: $TLDW_REQUEST_ID" \
  -H 'Content-Type: application/json' \
  --data-binary @analysis.json > receipt.json
JOB_ID="$(jq -er '.job_id' receipt.json)"
printf 'Accepted job: %s\n' "$JOB_ID"

A successful submission returns HTTP 202 with a job receipt. The summary is available after processing finishes. The receipt includes job_id, status_url and progress fields. max_credits limits spending for this request; account and source-length limits still apply.

Check progress using the job ID

bash
curl --fail-with-body "https://api.tldw.sh/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $TLDW_API_TOKEN" > job.json
jq '{id, status, progress, summary_id, error, next_poll_after_ms}' job.json

Repeat that status request while processing is active. Honor the returned next_poll_after_ms and any Retry-After header rather than polling continuously. Stop on completed, failed or canceled; inspect the structured error for a failure. The SDK quickstart provides bounded polling helpers.

A local timeout ends your wait; the server job keeps running. Save the job ID before waiting so you can resume it.

Read the summary

Only continue once the status is completed and summary_id is present:

bash
SUMMARY_ID="$(jq -er 'select(.status == "completed") | .summary_id | select(. != null)' job.json)"
curl --fail-with-body "https://api.tldw.sh/v1/summaries/$SUMMARY_ID" \
  -H "Authorization: Bearer $TLDW_API_TOKEN" > summary.json
jq '.content' summary.json

This response contains the generated analysis in content, plus source and transcript metadata. Transcript metadata is not the full transcript body.

Read the original transcript

bash
curl --fail-with-body "https://api.tldw.sh/v1/summaries/$SUMMARY_ID/transcript" \
  -H "Authorization: Bearer $TLDW_API_TOKEN" > transcript.json
jq '{source, language, timed, segments, blocks, text}' transcript.json

For timestamped video captions, inspect segments, whose timing is expressed as start_ms and end_ms. Text-oriented sources use blocks and text. Branch on timed rather than assuming every source has the same representation.

Submit one link to POST /v1/analyses or MCP analyze_media. The job saves both a summary and its original transcript. Poll the accepted job, then read GET /v1/summaries/SUMMARY_ID and GET /v1/summaries/SUMMARY_ID/transcript, or MCP get_summary and get_transcript, with the same summary ID. Reading saved results starts no new processing or model call. Use list_transcripts and get_saved_transcript to browse saved source pages.

Browse saved sources

Use list_transcripts and get_saved_transcript through MCP, or the saved-source REST endpoints, to read source pages already in your account. These reads require summaries:read and ownership. They start no processing job or model call.

For a known transcript ID, read GET /v1/transcripts/TRANSCRIPT_ID/page?offset=0&limit=100 and follow next_offset. Pages contain at most 500 source items. The API returns normalized saved text and timestamps, not the original caption file or a separate “exact transcript” representation.

SDK extractTranscript / extract_transcript and CLI extract are convenience helpers for the same analysis, wait and saved-source flow. They create an analysis and use normal processing credits. There is no separate customer transcript-only submission.

Captions, cost and failures

Omit transcription and force_asr: legacy controls are ignored and do not enable audio. The service uses usable saved source or accessible captions, at 1 credit per billable minute. Fresh audio transcription is unsupported on every plan. CAPTIONS_UNAVAILABLE releases the failed job hold without a processing-credit charge; stop or supply authorized source text rather than retrying automatically. Free includes 100 monthly caption/text credits and a 30-minute per-source limit. Reading a generated translation does not translate the saved original captions.

Fresh audio transcription is unavailable on every plan; no legacy request control enables it. Retrieval can still fail; the service does not guess missing speech from the title or description. Authentication, quota and unsupported-source errors need a change in input or configuration; retrying them rapidly will not help.

Use the OpenAPI contract for schemas and the error reference for recovery. The same submit, poll and separate-read workflow is available through MCP and the JavaScript/Python clients.

Connect your agent

Follow the setup steps for Claude, your coding assistant or your own API client.

Create an account to save summaries and connect your agents.

Connect your agent