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:

Create an account at https://yt2text.cc/auth/signup
Choose a plan at https://yt2text.cc/pricing
Open https://yt2text.cc/dashboard/api-keys
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 is the minimum plan.

API-first workflow

Recommended flow:

Read https://yt2text.cc/skill.md
Store the key in an environment variable such as YT2TEXT_API_KEY
Submit a video with POST /api/v1/videos/process
Poll GET /api/v1/videos/status/{job_id}
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

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_.... The server forwards that key to the public yt2text API for the call. No server-side key storage.

That means MCP setup uses the same key a user creates in https://yt2text.cc/dashboard/api-keys. The key should live in the MCP client's secret store, environment variables, or local MCP config. Do not paste API keys into prompts, public repos, shared chat logs, or frontend code.

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 in the runtime secret store and attach it as the Bearer token for MCP requests.

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 for embedded use:

{
  "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).

REST API and public skill files — live
Remote MCP server at mcp.yt2text.cc/mcp — live
First-party SDKs — planned
Native n8n node — planned

See Agents roadmap.

Agents

Agents

Who this is for

Human setup

API-first workflow

Authentication

Example request

Agent-specific guidance

Public documentation

MCP server

How MCP tool behavior works

Client setup

Claude

OpenClaw

Hermes agents

Codex and other MCP-capable clients

MCP FAQ

Does every user need their own API key?

Does the MCP server call an LLM?

Can free users use MCP?

Should agents use REST or MCP?

What comes next