Spoken

Obtén transcripciones publicadas de podcasts como Markdown limpio con nombres reales de los oradores: busca episodios y extrae transcripciones a través de la API de Spoken.

GitHub

Prueba este MCPPatrocinado

Documentación

Spoken — API de transcripción de podcasts y servidor MCP, Markdown limpio con nombres reales de hablantes

Spoken es una API de transcripción que convierte cualquier podcast publicado en Markdown limpio con nombres reales de hablantes — no "Hablante 1." Una sola llamada a la API devuelve texto con nombres y marcas de tiempo, listo para LLMs, pipelines de RAG, resumidores y búsqueda. Este repositorio también incluye spoken-mcp, un servidor MCP que ofrece a Claude Desktop, Claude Code, Cursor y Cline las mismas transcripciones como herramientas — ver Uso como servidor MCP.

Es una API de recuperación de transcripciones, no un servicio de voz a texto: funciona con podcasts ya publicados, así que te ahorras subir audio, ejecutar diarización y mapear etiquetas anónimas de hablantes manualmente. Para programas ya publicados, esto suele ser 5–10× más barato que pasar el audio por un servicio de transcripción.

🎙️ Nombres reales de hablantes, resueltos automáticamente
📄 Markdown limpio con marcas de tiempo, optimizado para ventanas de contexto de LLMs y fragmentación para RAG
🔎 Búsqueda por consulta de texto o pegando una URL de Spotify/YouTube
💳 Créditos de pago por uso — sin suscripción, las llamadas fallidas nunca se cobran, las consultas repetidas son gratis
🤖 Nativo para agentes — incluye una Habilidad de Agente, agents.md, llms.txt y una especificación OpenAPI

Obtén una clave en spoken.md — o pruébalo gratis con la clave demo pt_demo (la búsqueda funciona por completo; las transcripciones están limitadas al episodio demo).

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

La transcripción se devuelve como Markdown con nombres de hablantes y marcas de tiempo:

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

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

Endpoints

Método y ruta	Qué hace	Créditos
`GET /search?q={query or URL}`	Encuentra episodios; devuelve `id`, `title`, `podcast`, `podcastId`, `date`	0
`GET /podcasts/{podcastId}/episodes`	Lista el catálogo completo de un programa; devuelve el `id`, `title`, `date` de cada episodio	0
`GET /transcripts/{id}`	Devuelve la transcripción en Markdown	1 en la primera consulta, 0 en repetidas
`GET /balance`	Saldo de créditos actual + historial de uso	0
`GET /following`	Los programas que esta clave sigue (inferidos de las consultas, o declarados con `PUT` / eliminados con `DELETE /following/{podcastId}`)	0
`GET /new`	Episodios nuevos de esos programas que aún no se han consultado, cada uno con una URL de transcripción; `?format=atom` para un feed	0
`POST /buy`	Alta de clave nueva (Stripe)	—
`POST /top-up?key={key}`	Recarga para clientes existentes (Stripe)	—

La autenticación es el encabezado x-api-key. Las respuestas incluyen X-Credits-Remaining y X-Credits-Charged. Ver agents.md para la tabla completa de errores y las formas de las respuestas.

Ejemplos

examples/podcast_summarizer.py — consulta una transcripción y resúmela
examples/rag_pipeline.py — fragmenta una transcripción para un almacén vectorial / RAG
examples/quickstart.sh — búsqueda → transcripción en dos llamadas curl
examples/archive-show.sh — archiva el catálogo completo de un programa, un archivo por episodio

Uso desde Python

El paquete spoken-md envuelve la API sin dependencias fuera de la biblioteca estándar, e instala un 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=...) recorre un programa completo y es reanudable; los errores se tipifican por estado (PaymentRequired lleva la URL de recarga, NotFound significa que no hay transcripción). Ver python/README.md.

Uso como servidor MCP

Este repositorio incluye spoken-mcp, un servidor de Protocolo de Contexto de Modelos que expone Spoken a agentes compatibles con MCP (Claude Desktop, Cursor, Cline, …). Proporciona ocho herramientas:

Herramienta	Descripción
`search_podcasts`	Encuentra episodios por texto o una URL pegada de Spotify/YouTube
`list_episodes`	Lista el catálogo completo de un programa a partir de un `podcast_id`
`get_transcript`	Consulta la transcripción de un episodio como Markdown con nombres reales de hablantes
`get_balance`	Consulta los créditos restantes
`list_following`	Los programas que esta clave mantiene al día, inferidos de las consultas o declarados
`follow_podcast`	Declara un seguimiento de un programa (o elimina un silenciamiento)
`unfollow_podcast`	Silencia un programa para que salga de la lista y las consultas no lo vuelvan a añadir
`list_new_episodes`	Episodios nuevos de programas seguidos que aún no se han consultado, con enlaces a transcripciones

Mantener una base de conocimiento al día es list_new_episodes en un horario y get_transcript en lo que lista: cada consulta eleva el mínimo de ese programa.

Añádelo a la configuración de tu cliente MCP (por ejemplo, el claude_desktop_config.json de Claude Desktop):

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

SPOKEN_API_KEY por defecto es pt_demo (la búsqueda funciona por completo; las transcripciones están limitadas al episodio demo). Obtén una clave real en spoken.md.

Ejecuta desde el código fuente en su lugar:

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

Uso con agentes de IA

Spoken está diseñado para ser llamado por agentes. Apunta tu agente a la Habilidad de Agente (también disponible en https://spoken.md/.well-known/skills/spoken-md/SKILL.md), o entrégale agents.md. La especificación OpenAPI facilita envolverlo como herramienta para cualquier cliente de llamada de funciones o compatible con MCP (Claude, GPT, Cursor).

Precios

Créditos de pago por uso, sin suscripción. Claves nuevas: 100 por $15, 500 por $50, 2,000 por $160. Legible por máquina en spoken.md/pricing.md.

Enlaces

Sitio web y documentación: https://spoken.md
Instrucciones para agentes: https://spoken.md/agents.md
Especificación OpenAPI: https://spoken.md/.well-known/openapi.json
Resumen apto para LLMs: https://spoken.md/llms.txt

Spoken está construido y mantenido en spoken.md.