Transcription for AI agents.

Three ways to install

One repo ships all three: an agent skill, a Claude Code plugin, and a CLI. Pick the one that matches your agent runtime. Each needs a TRANSCRIBE_API_KEY from your settings.

npx skills add shsunmoonlee/transcribe-agent

/plugin marketplace add shsunmoonlee/transcribe-agent
/plugin install transcribe-so@transcribe-agent

npm install -g transcribe-so
export TRANSCRIBE_API_KEY=tsk_live_...

The core flow

Quote first (free), create (charges the wallet), wait, then read the result. Every command prints pure JSON to stdout, so the output pipes straight into jqor your agent's tool loop. The job id is the one returned by create.

$ transcribe-so quote --source youtube --url https://youtu.be/RdAY3DjSr3A
{ "retail_usd": 0.35, "billed_minutes": 21, "pipeline_code": "standard", ... }

$ transcribe-so create --source youtube --url https://youtu.be/RdAY3DjSr3A
{ "id": 4821, "status": "processing", "stage": "queued", ... }

$ transcribe-so wait 4821
{ "id": 4821, "status": "completed", ... }

$ transcribe-so result 4821 > transcript.json

Or do all four in one call with a spend cap: transcribe-so run --source youtube --url ... --max-usd 2. The CLI refuses locally if the quote exceeds the cap, before any money moves.

What your agent actually runs

You ask in plain language. The agent turns it into the calls below, with a hard price ceiling: run quotes first and refuses to create the job if the quote is over --max-usd. Captions are the one endpoint the CLI does not wrap yet, so the last line is a plain HTTP call.

You: Transcribe this episode and give me Instagram captions, under $3.

$ transcribe-so quote --source youtube --url https://youtu.be/RdAY3DjSr3A
$ transcribe-so run --source youtube --url https://youtu.be/RdAY3DjSr3A --max-usd 3
$ curl -sS -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
    "https://transcribe.so/api/v1/transcriptions/4821/timestamps?format=instagram_caption"

Ask for the output you actually want

The transcript itself is one endpoint. Beyond it, three different things get called "captions", and they are three different endpoints with three different bodies. Pick the one your task needs.

• Transcript text — GET /api/v1/transcriptions/:id/transcript returns the raw body as text/plain or text/markdown. Speaker labels and timestamps are both on by default; pass speaker_labels=false or timestamps=false to strip them. Nothing is truncated.
• Social post text — GET /api/v1/transcriptions/:id/timestamps drafts the caption or chapter list you paste into a post.
• Timed subtitles — GET /api/v1/transcriptions/:id/subtitles returns an SRT or VTT file for a video editor or player.
• Captioned video — POST /api/v1/transcriptions/:id/clips renders a shareable MP4 with the captions burned in.
• Who said what — GET /api/v1/search?q=... returns matching segments with speaker, start and end times, and a deep link.

# the transcript text, speaker-labelled, with timestamps
curl -sS -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
  "https://transcribe.so/api/v1/transcriptions/4821/transcript?format=txt&speaker_labels=true&timestamps=true"

# who said what, and when
curl -sS -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
  "https://transcribe.so/api/v1/search?q=pricing&limit=10"

Command reference

Destructive and re-charging commands require an explicit --yes. Exit codes separate auth, payment, and spend-cap failures so an agent knows whether to fix the key, top up, or raise --max-usd.

Every agent surface

The skill, plugin, and CLI sit on the same public API as everything else. If your agent speaks MCP or plain HTTP, connect directly.

Connect by runtime

Claude Code

Plugin or one MCP command.

claude mcp add --transport http transcribe https://transcribe.so/mcp

Codex

One MCP command.

codex mcp add transcribe --url https://transcribe.so/mcp

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global). OAuth on first use.

{"mcpServers":{"transcribe":{"url":"https://transcribe.so/mcp"}}}

ChatGPT

Use the public transcribe.so GPT, or add https://transcribe.so/mcp under Settings, Connectors, Developer mode (paid ChatGPT plans). Open the GPT.

Gemini CLI

One MCP command, or settings.json {"mcpServers":{"transcribe":{"httpUrl":"https://transcribe.so/mcp"}}}.

gemini mcp add --transport http transcribe https://transcribe.so/mcp

OpenClaw and skills.sh agents

Install the skill.

npx skills add shsunmoonlee/transcribe-agent

Any MCP client

Streamable HTTP at https://transcribe.so/mcp. OAuth, or an Authorization: Bearer tsk_live_... key.

• MCP server: https://transcribe.so/mcp (streamable HTTP; OAuth or API key). Per-runtime connect lines are above.
• OpenAPI spec: /openapi.json (also served as YAML at /api/v1/openapi.yaml)
• Site overview for LLMs: /llms.txt
• Skill, plugin, and CLI source: github.com/shsunmoonlee/transcribe-agent
• Human-oriented docs: /developers/docs