Transcripciones y búsqueda de YouTube
El video es una fuente primaria que la mayoría de los agentes de investigación no pueden leer. Esta habilidad convierte cualquier video, canal o consulta de búsqueda de YouTube en texto que puedes citar, con marcas de tiempo.
Todo funciona a través de una API REST. Sin yt-dlp, sin navegador sin cabeza, sin binarios que instalar.
Configuración
La API necesita una clave en el entorno. Añade una línea al archivo .env de FrontierAgent:
echo 'TRANSCRIPT_API_KEY=sk_tu_clave_aqui' >> .env
Obtén una clave en https://transcriptapi.com. El nivel gratuito te da 100 créditos y no pide tarjeta.
FrontierAgent carga .env al inicio y los comandos de shell lo heredan, por lo que $TRANSCRIPT_API_KEY
se resuelve dentro de cada comando a continuación.
Si la variable está vacía, detente y dile al usuario que la agregue. No adivines una clave ni imprimas el valor de vuelta al usuario.
Cada solicitud necesita ambos encabezados
Authorization: Bearer $TRANSCRIPT_API_KEY y un User-Agent real. Si falta el User-Agent o es el predeterminado, se responde con un Cloudflare 403, código de error 1010.
Obtener una transcripción
Un crédito. video_url acepta una URL completa de YouTube o un ID de video de 11 caracteres.
curl -sS -G "https://transcriptapi.com/api/v2/youtube/transcript" \
--data-urlencode "video_url=$VIDEO" \
--data-urlencode "format=text" \
--data-urlencode "send_metadata=true" \
-H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
-H "User-Agent: FrontierAgent/1.0"
Usa format=json en su lugar cuando necesites valores por segmento de start y duration, por ejemplo para
citar una marca de tiempo. La estructura JSON es
{"video_id": "...", "language": "en", "transcript": [{"text": "...", "start": 18.0, "duration": 3.5}]}.
Buscar videos o canales
Un crédito. type puede ser video o channel, limit va de 1 a 50.
curl -sS -G "https://transcriptapi.com/api/v2/youtube/search" \
--data-urlencode "q=$CONSULTA" \
--data-urlencode "type=video" \
--data-urlencode "limit=20" \
-H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
-H "User-Agent: FrontierAgent/1.0"
Resolver un handle de canal
Gratis, sin crédito. Acepta un @handle, una URL de canal o un ID UC....
curl -sS -G "https://transcriptapi.com/api/v2/youtube/channel/resolve" \
--data-urlencode "input=@TED" \
-H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
-H "User-Agent: FrontierAgent/1.0"
Los otros endpoints de canal aceptan el mismo valor channel directamente, por lo que rara vez necesitas
resolver primero.
Script auxiliar
scripts/transcript.sh envuelve la llamada de transcripción y falla de forma clara cuando falta la clave.
bash plugins/skills/youtube-transcripts/scripts/transcript.sh "https://www.youtube.com/watch?v=nm1TxQj9IsQ"
Cuando una llamada falla
| Estado | Qué significa | Qué hacer |
|---|---|---|
| 401 | La clave es incorrecta o falta | Pedir al usuario que verifique TRANSCRIPT_API_KEY en .env |
| 403 | Cloudflare bloqueó la solicitud | Omitiste el encabezado User-Agent. Añádelo y reintenta |
| 404 | El video no tiene subtítulos | Dilo claramente. No inventes una transcripción |
| 422 | El ID o URL del video está mal formado | Vuelve a leer el ID del enlace del usuario |
| 429 | Sin créditos o límite de velocidad alcanzado | Repórtalo. No reintentes en un bucle |
Una transcripción larga puede exceder el presupuesto de salida de la herramienta. Pide format=text, escribe el cuerpo a un
archivo con > outputs/transcript.txt, luego lee las partes que necesites.
Trabajando con lo que devuelve
Cita la transcripción en lugar de parafrasear cuando el texto exacto contiene la afirmación. Los subtítulos automáticos pueden tener errores de reconocimiento, por lo que trata un término técnico extraño como sospechoso y verifícalo contra el título o la descripción del video antes de construir un argumento sobre él.