Spoken

Spoken — 播客文字稿 API 和 MCP 服务，提供带真实说话人姓名的整洁 Markdown

Spoken 是一款文字稿 API，可将任何已发布的播客转换为整洁的 Markdown，并标注真实说话人姓名，而不是“说话人 1”。一次 API 调用即可返回带姓名和时间戳的文本，可直接用于大模型、RAG 流水线、摘要工具和搜索。本仓库还提供 spoken-mcp，这是一款 MCP 服务，可让 Claude Desktop、Claude Code、Cursor 和 Cline 将相同的文字稿作为工具使用 — 请参阅作为 MCP 服务使用。

这是文字稿检索 API，而非语音转文字服务：它处理的是已发布的播客，因此无需上传音频、运行说话人分离，也无需手动为匿名说话人标签匹配姓名。对于已发布的节目，这种方式通常比通过转录服务处理音频便宜 5–10 倍。

• 🎙️ 真实说话人姓名，自动匹配
• 📄 整洁的 Markdown，带时间戳，针对大模型上下文窗口和 RAG 分块进行了优化
• 🔎 按文本查询搜索，或粘贴 Spotify/YouTube URL
• 💳 按使用量付费的额度 — 无需订阅，失败的调用绝不扣费，重复获取免费
• 🤖 原生支持 Agent — 随附 Agent Skill、agents.md、llms.txt 和 OpenAPI 规范

在 spoken.md 获取密钥 — 或使用演示密钥 pt_demo 免费试用（搜索功能完整可用；文字稿仅限演示集中的播客）。

快速开始

# 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'

返回的文字稿为 Markdown 格式，带有说话人姓名和时间戳：

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

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

端点

方法和路径	功能	额度
GET /search?q={query or URL}	查找节目；返回 id、title、podcast、podcastId、date	0
GET /podcasts/{podcastId}/episodes	列出节目的完整历史目录；返回每集的 id、title、date	0
GET /transcripts/{id}	返回 Markdown 文字稿	首次获取扣 1，重复获取扣 0
GET /balance	当前额度余额和使用记录	0
GET /following	此密钥关注的节目（根据获取记录推断，或通过 PUT 声明／通过 DELETE /following/{podcastId} 移除）	0
GET /new	这些节目尚未获取的新播客集，每集附有文字稿 URL；使用 ?format=atom 获取订阅源	0
POST /buy	新密钥结账（Stripe）	—
POST /top-up?key={key}	回头客充值（Stripe）	—

通过 x-api-key 标头进行身份验证。响应中包含 X-Credits-Remaining 和 X-Credits-Charged。完整的错误表和响应格式请参阅 agents.md。

示例

• examples/podcast_summarizer.py — 获取文字稿并生成摘要
• examples/rag_pipeline.py — 将文字稿分块，以用于向量存储／RAG
• examples/quickstart.sh — 用两次 curl 调用完成搜索 → 获取文字稿
• examples/archive-show.sh — 归档某节目的完整历史目录，每集保存为一个文件

在 Python 中使用

spoken-md 包通过标准库以外无其他依赖的方式封装了 API，并会安装 spoken-md 命令。

pip install spoken-md

from spoken_md import Spoken

spoken = Spoken()                                  # SPOKEN_API_KEY, or the demo key
episode = spoken.search("huberman sleep")[0]
print(spoken.transcript(episode.id))               # Markdown with real speaker names

archive(podcast_id, skip=...) 会遍历整个节目，并支持断点续传；错误按状态分类（PaymentRequired 包含充值 URL，NotFound 表示没有文字稿）。请参阅 python/README.md。

用作 MCP 服务

Spoken 通过两种方式提供 Model Context Protocol 服务：托管在 https://spoken.md/mcp，以及作为本仓库中的软件包 spoken-mcp，供在本地运行服务的客户端使用（Claude Desktop、Cursor、Cline 等）。两种方式都提供相同的八种工具：

工具	描述
search_podcasts	按文本或粘贴的 Spotify/YouTube URL 查找单集
list_episodes	根据 podcast_id 列出某个节目的全部往期单集
get_transcript	获取单集的 Markdown 格式文字稿，包含真实发言者姓名
get_balance	查看剩余额度
list_following	列出此密钥持续跟踪的节目，依据抓取记录推断或由用户声明
follow_podcast	声明关注某个节目（或取消屏蔽）
unfollow_podcast	屏蔽某个节目，使其不再显示在列表中，且抓取时不会重新添加
list_new_episodes	列出已关注节目中尚未抓取的新单集，并提供文字稿链接

要保持知识库内容更新，可按计划调用 list_new_episodes，再对其列出的单集调用 get_transcript：每次抓取都会提高该节目的抓取基准。

托管服务

无需安装。将能连接 URL 的客户端指向 https://spoken.md/mcp（Streamable HTTP）：

claude mcp add --transport http spoken https://spoken.md/mcp

首次有工具需要使用你的密钥时，客户端会要求你登录。若要跳过此步骤，可自行在请求头中发送密钥：Authorization: Bearer pt_your_key。

对于只能通过 OAuth 登录的客户端（例如开发者模式下的 ChatGPT），系统会将你引导至一个页面，让你粘贴一次密钥。各应用的具体步骤见：spoken.md/mcp-server。即使没有密钥，也可以搜索、列出某个节目的单集并使用演示单集。

本地运行

将其添加到 MCP 客户端配置中（例如 Claude Desktop 的 claude_desktop_config.json）：

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

SPOKEN_API_KEY 默认为 pt_demo（搜索功能完整可用；文字稿仅限演示单集）。前往 spoken.md 获取真实密钥。

也可以改为从源码运行：

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

与 AI Agent 配合使用

Spoken 专为由 Agent 调用而设计。将 Agent Skill（也可通过 https://spoken.md/.well-known/skills/spoken-md/SKILL.md 获取）提供给你的 Agent，或将 agents.md 交给它。OpenAPI 规范便于将其封装为工具，供任何支持函数调用或兼容 MCP 的客户端使用（Claude、GPT、Cursor）。

定价

按次使用额度，无需订阅。新密钥套餐：15 美元可购买 100 个额度，50 美元可购买 500 个额度，160 美元可购买 2,000 个额度。机器可读版本见 spoken.md/pricing.md。

链接

• 网站和文档：https://spoken.md
• Agent 使用说明：https://spoken.md/agents.md
• OpenAPI 规范：https://spoken.md/.well-known/openapi.json
• 适合大模型阅读的概览：https://spoken.md/llms.txt

---

Spoken 由 spoken.md 构建并维护。