Spoken

Spoken — ポッドキャストの文字起こし API と MCP サーバー。実際の話者名を含む、整った Markdown

Spoken は、公開済みのポッドキャストを、実際の話者名（「Speaker 1」ではありません）を含む整った Markdown に変換する文字起こし API です。API を 1 回呼び出すだけで、話者名とタイムスタンプ付きのテキストが返され、LLM、RAG パイプライン、要約ツール、検索にすぐ利用できます。このリポジトリには spoken-mcp も含まれており、MCP サーバーとして Claude Desktop、Claude Code、Cursor、Cline で同じ文字起こしをツールとして利用できます。詳しくは「MCP サーバーとして利用する」をご覧ください。

これは音声をテキストに変換するサービスではなく、文字起こしの取得 API です。すでに公開されているポッドキャストを対象としているため、音声のアップロード、話者分離の実行、匿名の話者ラベルの手作業による割り当てが不要です。公開済みの番組であれば、通常は音声を文字起こしサービスにかける場合と比べて5～10 倍安価です。

• 🎙️ 実際の話者名を自動的に特定
• 📄 タイムスタンプ付きの整った Markdown。LLM のコンテキストウィンドウと RAG のチャンク分割に最適化
• 🔎 テキスト検索、または Spotify／YouTube の URL を貼り付けて検索
• 💳 従量制クレジット — サブスクリプション不要。失敗した呼び出しは課金されず、再取得は無料
• 🤖 エージェント向け — 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 — 2 回の curl 呼び出しで検索から文字起こし取得まで実行する
• examples/archive-show.sh — 番組の全バックカタログを、エピソードごとに 1 ファイルで保存する

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 でホストされているものと、サーバーをローカルで実行するクライアント（Claude Desktop、Cursor、Cline、…）向けの、このリポジトリ内のパッケージである spoken-mcp の2つの方法で利用できます。どちらも、次の8つのツールを提供します。

ツール	説明
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 をヘッダーとして自分で送信してください。

ChatGPT の開発者モードのように OAuth でしかサインインできないクライアントの場合は、キーを一度貼り付けるページに転送されます。各アプリの手順については、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 エージェントで使用する

Spoken はエージェントから呼び出されるように設計されています。エージェントに Agent Skill（https://spoken.md/.well-known/skills/spoken-md/SKILL.md でも提供）を指定するか、agents.md を渡してください。OpenAPI spec を使えば、関数呼び出しまたは MCP 対応の任意のクライアント（Claude、GPT、Cursor）向けに、ツールとして簡単にラップできます。

料金

サブスクリプションなしの従量課金制クレジットです。新規キーは、15 ドルで 100、50 ドルで 500、160 ドルで 2,000 です。機械可読形式は spoken.md/pricing.md をご覧ください。

リンク

• ウェブサイトとドキュメント：https://spoken.md
• エージェント向けの説明：https://spoken.md/agents.md
• OpenAPI spec：https://spoken.md/.well-known/openapi.json
• LLM 向け概要：https://spoken.md/llms.txt

---

Spoken は spoken.md で開発・保守されています。