# Tubescribe

> YouTube → Markdown, in any language. Free, fast, no signup. Designed for both humans and AI agents.

Tubescribe fetches a transcript for any public YouTube video and returns it as a clean Markdown document, optionally translated into a target language. Captions are fetched from YouTube (where available); translation, when needed, is performed by Claude Haiku.

## API

Endpoint: `POST https://tubescribe.watch/api/transcribe`

Headers:
- `Content-Type: application/json`
- `Authorization: Bearer tsk_…` (optional) — an API key. Without it, you're rate-limited per IP. With it, you get your own per-key daily quota (and it's the identity used for future paid tiers). Required for the MCP server (see below).

Body (JSON):
- `url` (string, required) — Any public YouTube URL: `https://www.youtube.com/watch?v=…`, `https://youtu.be/…`, `https://youtube.com/shorts/…`
- `targetLang` (string, required) — Two-letter ISO 639-1 code: `en`, `he`, `es`, `fr`, `de`, `pt`, `it`, `ru`, `ja`, `ko`, `zh`, `ar`, `hi`, `tr`, `nl`, `pl`, `sv`, `id`, `vi`, `th`, `uk`, `ro`, `cs`, `el`, `fa`

CORS: open (`Access-Control-Allow-Origin: *`). Auth is optional for this endpoint.

Successful response (`200`):
```
{
  "markdown": "---\nvideo_id: ...\n---\n\n# <video title>\n\n…",
  "filename": "<video-title-slug>-<lang>.md",
  "filenameBase": "<video-title-slug>-<lang>",
  "videoId": "…",
  "title": "Video title" | null,
  "author": "Channel name" | null,
  "thumbnailUrl": "https://i.ytimg.com/…" | null,
  "sourceLang": "en",
  "targetLang": "he",
  "translated": true,
  "availableLangs": ["en", "de"],
  "segments": [{ "text": "…", "offset": 0, "duration": 4200 }],
  "cached": false,
  "note": null
}
```

`segments` contains timestamped caption chunks (milliseconds) in the **source** captions language — use them to build `.srt`/`.vtt` files without another call. `cached: true` means the result came from Tubescribe's 30-day cache and did not consume any quota.

Rate-limit response (`429`):
```
{
  "error": "rate_limit_ip" | "rate_limit_key" | "rate_limit_daily" | "rate_limit_monthly",
  "message": "...",
  "contactEmail": "tiranyas@gmail.com",
  "reset": <unix-ms-timestamp>
}
```

## Quotas (free, no API key)

- 3 transcripts per IP per day
- 80 transcripts per day across the whole site
- 90 transcripts per month across the whole site
- Cache hits are free and unlimited — repeating a (video, language) pair someone already requested costs nothing.

Check your remaining quota anytime: `GET https://tubescribe.watch/api/quota` →
```
{ "enabled": true, "you": { "used": 1, "limit": 3, "remaining": 2 }, "site": { "remainingToday": 64 } }
```

When a quota is exhausted, the API returns `429` with a `contactEmail` so users can reach the owner if they need expanded access.

## API keys

Keys are optional for the HTTP API and **required for MCP**. They give each user their own daily quota bucket and are the identity for future paid tiers. Free tier: 3 transcripts/day per key.

Get a key: create a free account (email + password) at `https://tubescribe.watch/login`, then generate and manage keys at `https://tubescribe.watch/account`. The key is shown in full once — save it. Each account may hold up to 5 keys.

Inspect a key's remaining quota: `GET https://tubescribe.watch/api/keys?key=tsk_…` (or send it as a Bearer token) →
```
{ "valid": true, "plan": "free", "dailyLimit": 3, "usedToday": 1, "remaining": 2 }
```

Use the key on `/api/transcribe` via `Authorization: Bearer tsk_…`. The global daily/monthly site caps still apply on top of any per-key limit.

## MCP

Tubescribe is also a remote MCP server (Model Context Protocol) over streamable HTTP.

- Endpoint: `https://tubescribe.watch/api/mcp`
- Transport: streamable HTTP
- Auth: required — `Authorization: Bearer tsk_…` (mint one at `/api/keys`)

Client config (Claude Desktop / Claude Code `.mcp.json`):
```
{
  "mcpServers": {
    "tubescribe": {
      "type": "http",
      "url": "https://tubescribe.watch/api/mcp",
      "headers": { "Authorization": "Bearer tsk_your_key" }
    }
  }
}
```

Tools:
- `transcribe_youtube` — inputs `url` (string), `targetLang` (ISO 639-1 string). Returns the transcript as Markdown plus a metadata summary. Counts 1 against the key's daily quota unless cached.
- `check_quota` — returns the key's used/remaining transcripts for today. No quota cost.
- `list_languages` — returns the supported target language codes.

Calls without a valid key are rejected with `401`.

## Use cases

- Research assistants that need a video's text content for summarization or Q&A
- Building knowledge bases from YouTube channels
- Translating educational content for non-native speakers
- Generating subtitles, study notes, or blog posts from talks

## Notes for AI agents

- Do not retry aggressively on `429`. Respect the `reset` timestamp.
- For long videos (> 60,000 chars of transcript), translation will fail with `too_long`. Fall back to the original language by setting `targetLang` to the video's native language (see `availableLangs`).
- The endpoint is idempotent, and results are cached for 30 days per (video, language) pair — repeated identical requests are fast and free.

## Contact

Owner: Tiran ([tiranyas@gmail.com](mailto:tiranyas@gmail.com))