Spoken

Obtenha transcrições de podcasts publicados como Markdown limpo com nomes reais dos palestrantes — pesquise episódios e extraia transcrições via a API do Spoken.

GitHub
5
Experimente este MCPPatrocinado

Documentação

Spoken — API de transcrição de podcasts e servidor MCP, Markdown limpo com nomes reais de palestrantes

Spoken é uma API de transcrição que transforma qualquer podcast publicado em Markdown limpo com nomes reais de palestrantes — não "Palestrante 1". Uma única chamada de API retorna texto nomeado e com timestamps, pronto para LLMs, pipelines de RAG, sumarizadores e busca. Este repositório também inclui spoken-mcp, um servidor MCP que oferece ao Claude Desktop, Claude Code, Cursor e Cline as mesmas transcrições como ferramentas — veja Uso como servidor MCP.

É uma API de recuperação de transcrições, não um serviço de fala para texto: ela funciona com podcasts já publicados, então você evita enviar áudio, executar diarização e mapear rótulos anônimos de palestrantes manualmente. Para programas já publicados, isso é tipicamente 5–10× mais barato do que processar o áudio em um serviço de transcrição.

  • 🎙️ Nomes reais de palestrantes, resolvidos automaticamente
  • 📄 Markdown limpo com timestamps, otimizado para janelas de contexto de LLMs e chunking de RAG
  • 🔎 Busca por consulta de texto ou cole um URL do Spotify/YouTube
  • 💳 Créditos pagos por uso — sem assinatura, chamadas com falha nunca são cobradas, buscas repetidas são gratuitas
  • 🤖 Nativo para agentes — inclui uma Agent Skill, agents.md, llms.txt e uma especificação OpenAPI

Obtenha uma chave em spoken.md — ou experimente gratuitamente com a chave de demonstração pt_demo (a busca funciona totalmente; as transcrições são limitadas ao episódio de demonstração).

Início rápido

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

A transcrição retorna como Markdown com palestrantes nomeados e timestamps:

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

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

Endpoints

Método e caminhoO que fazCréditos
GET /search?q={query or URL}Encontra episódios; retorna id, title, podcast, podcastId, date0
GET /podcasts/{podcastId}/episodesLista o catálogo completo de um programa; retorna o id, title, date de cada episódio0
GET /transcripts/{id}Retorna a transcrição em Markdown1 na primeira busca, 0 em repetições
GET /balanceSaldo atual de créditos + histórico de uso0
GET /followingOs programas que esta chave acompanha (inferidos de buscas, ou declarados com PUT / removidos com DELETE /following/{podcastId})0
GET /newNovos episódios desses programas que ainda não foram buscados, cada um com um URL de transcrição; ?format=atom para um feed0
POST /buyCheckout de nova chave (Stripe)—
POST /top-up?key={key}Recarga para clientes existentes (Stripe)—

A autenticação é o cabeçalho x-api-key. As respostas incluem X-Credits-Remaining e X-Credits-Charged. Veja agents.md para a tabela completa de erros e formatos de resposta.

Exemplos

Uso a partir do Python

O pacote spoken-md encapsula a API sem dependências além da biblioteca padrão e instala um comando 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=...) percorre um programa inteiro e é retomável; erros são tipados por status (PaymentRequired carrega o URL de recarga, NotFound significa que não há transcrição). Veja python/README.md.

Uso como servidor MCP

Este repositório inclui spoken-mcp, um servidor Model Context Protocol que expõe o Spoken a agentes compatíveis com MCP (Claude Desktop, Cursor, Cline, …). Ele fornece oito ferramentas:

FerramentaDescrição
search_podcastsEncontra episódios por texto ou um URL colado do Spotify/YouTube
list_episodesLista todo o catálogo de um programa a partir de um podcast_id
get_transcriptBusca a transcrição de um episódio como Markdown com nomes reais de palestrantes
get_balanceVerifica créditos restantes
list_followingOs programas que esta chave mantém atualizados, inferidos de buscas ou declarados
follow_podcastDeclara um acompanhamento para um programa (ou remove um silenciamento)
unfollow_podcastSilencia um programa para que ele saia da lista e buscas não o readicionem
list_new_episodesNovos episódios de programas acompanhados que ainda não foram buscados, com links de transcrição

Manter uma base de conhecimento atualizada é list_new_episodes em um cronograma e get_transcript no que ela lista: cada busca eleva o piso daquele programa.

Adicione-o à configuração do seu cliente MCP (por exemplo, o claude_desktop_config.json do Claude Desktop):

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

SPOKEN_API_KEY usa como padrão pt_demo (a busca funciona totalmente; as transcrições são limitadas ao episódio de demonstração). Obtenha uma chave real em spoken.md.

Execute a partir do código-fonte:

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

Uso com agentes de IA

O Spoken foi projetado para ser chamado por agentes. Aponte seu agente para a Agent Skill (também servida em https://spoken.md/.well-known/skills/spoken-md/SKILL.md), ou entregue a ele agents.md. A especificação OpenAPI facilita o encapsulamento como ferramenta para qualquer cliente compatível com function-calling ou MCP (Claude, GPT, Cursor).

Preços

Créditos pagos por uso, sem assinatura. Novas chaves: 100 por $15, 500 por $50, 2.000 por $160. Legível por máquina em spoken.md/pricing.md.

Links

O Spoken é construído e mantido em spoken.md.