API & MCP Documentation

VideoToNotes API

Turn any video link into structured notes and a transcript — asynchronously. Create a task, receive a task_id immediately, then poll until the note is ready. The same capabilities are also exposed as an MCP server for AI agents.

Base URL

https://videotonotes.dev

Availability

API and MCP access is included with Pro and Ultimate subscriptions (monthly or yearly). Each task consumes 1 credit from your subscription balance.

Authentication

All endpoints use Bearer-token authentication. Generate keys under Settings → API keys; every call is listed there under Usage records.

Authorization: Bearer sk_your_api_key

Keep keys secret. A key can be deleted at any time from Settings, which immediately revokes it.

Create a note task

POST/api/v1/tasks

Accepts a video URL (YouTube, Bilibili, TikTok, Vimeo and 50+ other platforms) and starts processing in the background. Responds 202 Accepted with the task id.

curl -X POST https://videotonotes.dev/api/v1/tasks \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=..."}'

{
  "task_id": "9f2c1c3e-…",
  "status": "processing",
  "cached": false,
  "poll_url": "/api/v1/tasks/9f2c1c3e-…"
}

If the same URL was processed before, the API returns the cached note instantly with "status": "completed" and charges nothing.

Get task status

GET/api/v1/tasks/{task_id}

Poll every few seconds. While running, status is "processing"; when finished it becomes "completed" and the note is included — both as rendered Markdown and as the full structured JSON (summary, chapters, quotes, insights and transcript).

curl https://videotonotes.dev/api/v1/tasks/9f2c1c3e-… \
  -H "Authorization: Bearer sk_your_api_key"

{
  "task_id": "9f2c1c3e-…",
  "status": "completed",
  "created_at": "2026-07-30T08:15:00.000Z",
  "title": "Intro to Large Language Models",
  "result": {
    "title": "Intro to Large Language Models",
    "duration_sec": 3504,
    "language": "en",
    "platform": "youtube",
    "markdown": "# Intro to Large Language Models\n\n## 📼 智能总结 …",
    "note": { "structured": { … }, "transcript": [ … ] }
  }
}

MCP server

POST/api/mcp

A stateless Model Context Protocol endpoint over HTTP JSON-RPC 2.0 — point any MCP-capable agent at it. Two tools are exposed:

Tool	Arguments	Returns
create_note_from_url	url	task_id + status (async)
get_task_status	task_id	status, markdown + note JSON when done

curl -X POST https://videotonotes.dev/api/mcp \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "create_note_from_url",
      "arguments": { "url": "https://www.youtube.com/watch?v=..." }
    }
  }'

MCP client config example:

{
  "mcpServers": {
    "videotonotes": {
      "type": "http",
      "url": "https://videotonotes.dev/api/mcp",
      "headers": { "Authorization": "Bearer sk_your_api_key" }
    }
  }
}

Errors

Errors use the appropriate HTTP status code and a consistent body:

{ "error": { "code": 403, "message": "API access requires an active Pro or Ultimate subscription…" } }

400	Invalid request body (missing/invalid url)
401	Missing or invalid API key
402	Insufficient subscription credits
403	API access requires Pro or Ultimate
404	Task not found (or owned by another user)

Online tester

Try the full flow without leaving the browser: paste an API key and a video URL, create a task, and watch it complete.