# VideoHub

> Free transcription API for YouTube and Instagram videos. Designed for AI
> conversations — no auth, no SDK, no setup. Just GET a URL.

## How to transcribe a video (canonical pattern)

Prefix any video URL with `https://videohub.pro/` and GET it with
`Accept: application/json`. Example:

```
GET https://videohub.pro/https://youtu.be/JAz0jPetSjI
Accept: application/json
```

Returns JSON with `title`, `channel`, `duration_seconds`, `language`,
`markdown` (full transcript), and `canonical_url` (a short, shareable link).

Anonymous quota: videos up to 10 minutes are returned fully; longer videos
return a 10-minute preview with an upsell link. No API key required.

## Canonical phrase for users to share with their AI

> Transcreva este vídeo: https://videohub.pro/<COLE A URL DO VÍDEO>

That's all the user needs to type. Just a normal URL. The AI does a GET
on that URL and reads the response like any other web page.

(In English: `Transcribe this video: https://videohub.pro/<PASTE THE VIDEO URL>`)

## How responses work

Every GET to `https://videohub.pro/<video URL>` returns useful content
as plain HTML (server-rendered). No JavaScript execution needed. No
special headers required. LLMs read HTML perfectly.

### Cache hit (video already transcribed)
A 303 redirect to the canonical short URL `https://videohub.pro/transcript/<id>`,
which renders the full transcript inside the HTML page. Title, channel,
duration, source URL, and the complete markdown transcript are all
visible in the raw HTML. Just follow the redirect (most fetchers do
this automatically) and read the response.

### Cache miss (new video)
HTML page with the title, duration, current stage, completion estimate,
and a **permanent link** to the final transcript URL. All rendered as
server-side text — you don't need JavaScript to see it. The HTML
includes an explicit note for AI agents:

> "Para agentes de IA: a transcrição completa estará disponível no
> link acima em [X minutes]. Faça um novo GET nesse link após esse
> tempo e você receberá a transcrição completa em markdown."

So the AI just relays this to the user: "started a transcription for
[title], come back to [link] in [X minutes]." When the user comes back,
the AI does a GET on that link, gets the full transcript.

## Opt-in JSON

If you specifically want structured JSON (for programmatic integration,
MCP, automated pipelines), opt in explicitly:

```
GET https://videohub.pro/<video URL>?format=json
```

or

```
GET https://videohub.pro/<video URL>
Accept: application/json
```

The JSON includes `markdown`, `canonical_url`, `title`, `channel`,
`duration_seconds`, `source_url`, and a `_meta` block describing the
service. For in-flight jobs it includes `estimated_completion_phrase`
and the canonical_url to come back to.

## REST API for programmatic access

`POST /api/v1/transcribe` with `{"url": "..."}`. See
[/docs.md](/docs.md) and the OpenAPI spec at
[/api/v1/openapi.json](/api/v1/openapi.json).

## Key URLs (all public)

- [Home](https://videohub.pro/index.md): what VideoHub is.
- **[Skill / AI Contract](https://videohub.pro/skill.md): step-by-step recipe for AI assistants to "watch" a video (transcript + frames + timestamps).**
- [Documentation](https://videohub.pro/docs.md): all endpoints, shortcut behavior, edge cases.
- [Pricing](https://videohub.pro/pricing.md): free tier and Pro plan.
- [Privacy Policy](https://videohub.pro/privacy.md): data handling.
- [Terms of Service](https://videohub.pro/terms.md): usage rules.
- [OpenAPI spec](https://videohub.pro/api/v1/openapi.json): full REST API.
- [Interactive REST docs](https://videohub.pro/api/v1/docs): Swagger UI.
- [MCP server](https://videohub.pro/mcp): Streamable HTTP endpoint (Bearer API key required) for Claude Desktop, Claude Code, ChatGPT, Gemini CLI and any MCP-compatible client — 6 tools including transcript search and frame images. Legacy SSE at `/mcp/sse`.
- [Claude Code skill](https://videohub.pro/claude-skill.md): installable SKILL.md that teaches Claude when and how to use the VideoHub MCP tools.

## Behavior matrix

| Caller type | What we return |
|---|---|
| Browser (Accept: text/html) | HTML "in progress" page with live SSE progress, swaps to result in-place when done. |
| Agent / curl (Accept: application/json OR AI bot User-Agent) | JSON inline on the shortcut URL. Cache hit → 200 immediately. Cache miss → blocks synchronously for up to ~90s, then 200 with full payload OR 202 with `status_url`/`stream_url`. **No 303 redirect on the JSON path.** |
| Already-cached video | Same shortcut URL becomes near-instant (DB lookup, ~10ms). |

## Limits

- Anonymous: 5 new (cache-miss) transcriptions per hour per IP. Cache hits unlimited.
- Anonymous: videos > 10 minutes return a 10-minute preview + upsell.
- Max video length: 7 hours.

## What we do NOT do

- We do not crawl the web or build an index.
- We do not store user history without a logged-in account.
- We do not run paid ads or sell user data.