Spoken — podcast transcripts as clean Markdown, built for AI agents

Spoken is a transcript API that turns any published podcast into clean Markdown with real speaker names — not "Speaker 1." One API call returns named, timestamped text, ready for LLMs, RAG pipelines, summarizers, and search.

It's a transcript *retrieval* API, not a speech-to-text service: it works on already-published podcasts, so you skip uploading audio, running diarization, and mapping anonymous speaker labels by hand. For published shows that's typically 5–10× cheaper than running the audio through a transcription service.

• 🎙️ Real speaker names, resolved automatically
• 📄 Clean Markdown with timestamps, tuned for LLM context windows and RAG chunking
• 🔎 Search by text query or paste a Spotify/YouTube URL
• 💳 Pay-per-use credits — no subscription, failed calls never charged, repeat fetches free
• 🤖 Agent-native — ships with an Agent Skill, `agents.md`, `llms.txt`, and an OpenAPI spec

Get a key at **spoken.md** — or try it free with the demo key `pt_demo` (search works fully; transcripts limited to the demo episode).

Quickstart

# 1. Find an episode (by text, or paste a Spotify/YouTube URL)
curl -s 'https://spoken.md/search?q=huberman+sleep' \
  -H 'x-api-key: pt_demo'

# 2. Fetch the transcript as Markdown
curl -s 'https://spoken.md/transcripts/1000651996090' \
  -H 'x-api-key: pt_demo'

The transcript comes back as Markdown with named speakers and timestamps:

**John Smith** (0:00)
Welcome to the show. Today we're talking about...

**Jane Doe** (0:15)
Thanks for having me.

Endpoints

Auth is the `x-api-key` header. Responses include `X-Credits-Remaining` and `X-Credits-Charged`. See `agents.md` for the full error table and response shapes.

Examples

• `examples/podcast_summarizer.py` — fetch a transcript and summarize it
• `examples/rag_pipeline.py` — chunk a transcript for a vector store / RAG
• `examples/quickstart.sh` — search → transcript in two curl calls
• `examples/archive-show.sh` — archive a show's entire back catalogue, one file per episode

Use as an MCP server

This repo includes `spoken-mcp`, a Model Context Protocol server that exposes Spoken to MCP-compatible agents (Claude Desktop, Cursor, Cline, …). It provides four tools:

Add it to your MCP client config (e.g. Claude Desktop's `claude_desktop_config.json`):

{
  "mcpServers": {
    "spoken": {
      "command": "npx",
      "args": ["-y", "spoken-mcp"],
      "env": { "SPOKEN_API_KEY": "pt_your_key" }
    }
  }
}

`SPOKEN_API_KEY` defaults to `pt_demo` (search works fully; transcripts limited to the demo episode). Get a real key at spoken.md.

Run from source instead:

npm install && npm run build
SPOKEN_API_KEY=pt_your_key node dist/index.js

Use with AI agents

Spoken is designed to be called by agents. Point your agent at the Agent Skill (also served at `https://spoken.md/.well-known/skills/spoken-md/SKILL.md`), or hand it `agents.md`. The OpenAPI spec makes it easy to wrap as a tool for any function-calling or MCP-compatible client (Claude, GPT, Cursor).

Pricing

Pay-per-use credits, no subscription. New keys: 100 for $15, 500 for $50, 2,000 for $160. Machine-readable at spoken.md/pricing.md.

Links

• Website & docs: https://spoken.md
• Agent instructions: https://spoken.md/agents.md
• OpenAPI spec: https://spoken.md/.well-known/openapi.json
• LLM-friendly overview: https://spoken.md/llms.txt

Spoken is built and maintained at spoken.md.