Agents

YT2Text is usable from AI agents today through the public REST API at

https://api.yt2text.cc/api/v1

The public onboarding files are:

• https://yt2text.cc/skill.md

• https://yt2text.cc/skill.json

• https://yt2text.cc/skill.jsonl

• https://yt2text.cc/agents

Who this is for

This guide is for agent systems that can:

• read Markdown instructions
• store API keys securely
• make authenticated HTTPS requests
• poll asynchronous jobs and fetch results later

That includes common agent/operator environments such as:

• Codex
• GPT-based agents
• Claude
• Claude Code
• OpenClaw
• Hermes agents
• internal orchestration agents

Human setup

Before an agent can call the API, a human must:

1. Create an account at

   https://yt2text.cc/auth/signup

2. Choose a plan at

   https://yt2text.cc/pricing

3. Open

   https://yt2text.cc/dashboard/api-keys

4. Create an API key and copy it immediately

Plan gates:

• free

  : no API keys,

  tldr

  only

• plus

  : API keys enabled, all summary modes

• pro

  : batch processing, webhooks, custom prompts, PDF export, infographics, AI chat, priority queue

If the goal is external agent usage,

plus

API-first workflow

Recommended flow:

1. Read

   https://yt2text.cc/skill.md

2. Store the key in an environment variable such as

   YT2TEXT_API_KEY

3. Submit a video with

   POST /api/v1/videos/process

4. Poll

   GET /api/v1/videos/status/{job_id}

5. Fetch

   GET /api/v1/videos/result/{job_id}

Authentication

Preferred header:

Authorization: Bearer <api_key>

Also supported:

X-API-Key: <api_key>

Query parameter authentication is not supported.

Example request

curl -X POST https://api.yt2text.cc/api/v1/videos/process \
  -H "Authorization: Bearer $YT2TEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "options": {
      "summary_modes": ["tldr", "detailed"],
      "language": "en"
    },
    "service_name": "agent-platform",
    "agent_name": "research-agent",
    "client_reference": "job-123"
  }'

Agent-specific guidance

• Prefer async processing, not synchronous assumptions
• Keep keys server-side only
• Use

  service_name

  ,

  agent_name

  , and

  client_reference

  for correlation
• Treat

  /api/v1/usage/*

  as diagnostic today, not billing truth
• Back off on

  429

  responses using

  Retry-After

Public documentation

• Getting Started
• Authentication
• Videos API
• Batch API
• Webhooks
• Rate Limits
• SDK roadmap
• Agents roadmap

MCP server

YT2Text now exposes a remote Model Context Protocol server.

Endpoint:

https://mcp.yt2text.cc/mcp

Public setup page:

https://yt2text.cc/mcp

Auth is per-request: send the user's yt2text API key as

Authorization: Bearer sk_...

That means MCP setup uses the same key a user creates in

https://yt2text.cc/dashboard/api-keys

How MCP tool behavior works

YT2Text does not need a separate behavior definition for every LLM. MCP defines the callable tools, their names, descriptions, and input schemas. The client model decides when to call a tool based on the user request and the tool metadata.

Practical guidance:

• Ask the client to use YT2Text when a task needs a YouTube transcript, summary, video notes, or Markdown export.
• Prefer

  summarize_youtube_video

  when the agent should complete the whole flow in one step.
• Prefer

  process_youtube_video

  plus

  get_video_job_status

  plus

  get_video_result

  when the agent needs explicit async control.
• Use

  export_video_markdown

  when the next step is research notes, documentation, publishing, or handoff to another agent.
• Keep the YT2Text API key out of model-visible instructions whenever the client supports secret headers or environment variables.

Tools exposed:

• process_youtube_video

  — queue a video, return a job id

• get_video_job_status

  — check job status

• get_video_result

  — fetch completed transcript and summaries

• summarize_youtube_video

  — queue + poll until complete

• export_video_markdown

  — convert a result to Markdown

Client setup

Claude

Example remote HTTP config:

{
  "mcpServers": {
    "yt2text": {
      "url": "https://mcp.yt2text.cc/mcp",
      "headers": {
        "Authorization": "Bearer sk_..."
      }
    }
  }
}

OpenClaw

Use the same remote server URL and configure the YT2Text key as a secret header:

URL: https://mcp.yt2text.cc/mcp
Header: Authorization: Bearer sk_...

Hermes agents

Hermes or other orchestrators should keep

YT2TEXT_API_KEY

MCP_URL=https://mcp.yt2text.cc/mcp
YT2TEXT_API_KEY=sk_...

Codex and other MCP-capable clients

Use remote HTTP MCP when the client supports URL-based MCP servers. Use the local stdio adapter when the client expects a command.

A local stdio adapter is also published in

mcp/yt2text-mcp

{
  "mcpServers": {
    "yt2text": {
      "command": "node",
      "args": ["/absolute/path/to/yt2text/mcp/yt2text-mcp/dist/index.js"],
      "env": {
        "YT2TEXT_API_KEY": "sk_...",
        "YT2TEXT_API_BASE": "https://api.yt2text.cc"
      }
    }
  }
}

The MCP server respects the same plan limits as the REST API (Plus minimum, Pro for batch / custom prompts / PDF / chat / infographics).

MCP FAQ

Does every user need their own API key?

Yes. The remote MCP server is stateless for credentials. Each user sends their own YT2Text API key as a Bearer token.

Does the MCP server call an LLM?

No. The MCP server exposes tools and forwards authenticated requests to the YT2Text public API. The MCP client and its LLM decide when to call tools.

Can free users use MCP?

No. API keys start at Plus, so Plus is the minimum plan for MCP. Pro unlocks higher-volume and automation features.

Should agents use REST or MCP?

Use REST when you are building your own integration code and want full request control. Use MCP when your client can discover and call tools directly.

What comes next

The current state of YT2Text agent support:

1. REST API and public skill files — live
2. Remote MCP server at

   mcp.yt2text.cc/mcp

   — live
3. First-party SDKs — planned
4. Native n8n node — planned

See Agents roadmap.