Descargar a mano una transcripción de YouTube es fácil. Construir un flujo de trabajo confiable para cientos o miles de videos públicos es un problema distinto: puede que los videos no tengan subtítulos, que el idioma solicitado no esté disponible, que el texto generado automáticamente contenga errores, y cada resultado debe seguir vinculado a su fuente.
Esta guía muestra cómo obtener el texto disponible de las transcripciones públicas de YouTube con la SocQ YouTube Transcripts API, procesar varias URL de video mediante una tarea asíncrona y preparar los resultados normalizados para búsqueda, resumen, investigación o generación aumentada por recuperación (RAG).
Respuesta rápida: Envíe URL públicas de videos de YouTube y, opcionalmente, un idioma BCP-47 a
POST /v1/youtube/transcripts. Guarde eltask_iddevuelto, consulte el endpoint de la tarea y lea los registros completados endata.results.items. SocQ devuelve el texto plano de la transcripción y el contexto del video cuando hay subtítulos públicos utilizables. No genera nuevo reconocimiento de voz cuando faltan los subtítulos.
¿La API oficial de YouTube puede descargar cualquier transcripción pública?
No. La API oficial YouTube Data API tiene recursos de subtítulos, pero su método de descarga está pensado para las pistas de subtítulos que el usuario autenticado tiene permiso de administrar. La documentación actual de Google indica que captions.download requiere autorización OAuth y que el usuario debe tener permiso para editar el video. El método además cuesta 200 unidades de cuota por llamada.
Eso funciona cuando usted es dueño del canal o lo administra. No ofrece una forma general de descargar el texto de los subtítulos de videos públicos arbitrarios. Consulte la documentación oficial de Google sobre la descarga de subtítulos para conocer los requisitos de autorización.
Conviene distinguir tres casos de uso:
| Requisito | Enfoque adecuado |
|---|---|
| Administrar los subtítulos de videos propios | YouTube Data API con OAuth |
| Obtener el texto de subtítulos ya disponibles de videos públicos seleccionados | Un endpoint administrado de transcripciones como SocQ |
| Transcribir el audio cuando no existen subtítulos | Un pipeline independiente de voz a texto o ASR |
SocQ cubre el segundo caso. Obtiene el texto de transcripción disponible; no afirma que todos los videos públicos tengan una transcripción y no sustituye en silencio el texto con ASR recién generado.
Envíe una solicitud de transcripción de YouTube
El endpoint acepta una o más URL públicas de videos. También puede enviar un idioma preferido, como en o zh-CN.
curl -X POST "https://api.socq.ai/v1/youtube/transcripts" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.youtube.com/watch?v=arj7oStGLkU"
],
"language": "en"
}'
El envío inicia una tarea asíncrona. Guarde el task_id devuelto; no envíe el mismo lote otra vez solo porque el procesamiento no sea inmediato.
Consulte la tarea hasta que llegue a un estado terminal:
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
-H "Authorization: Bearer $SOCQ_API_KEY"
queued y running son estados intermedios normales. Cuando la tarea termina con éxito, lea data.results.items. Si la página de resultados indica has_more: true, solicite la página siguiente con el next_cursor devuelto.
Cómo es la respuesta de la transcripción
Un registro normalizado de transcripción tiene una estructura estable que se puede almacenar sin analizar una página de YouTube:
{
"id": "arj7oStGLkU",
"platform": "youtube",
"resource": "transcripts",
"type": "transcript",
"url": "https://www.youtube.com/watch?v=arj7oStGLkU",
"title": "Inside the Mind of a Master Procrastinator",
"text": "A plain-text transcript snapshot.",
"language": "en",
"available_languages": ["en"],
"format": "plaintext",
"transcript_source": "auto_generated",
"author": {
"id": "UCAuUUnT6oDeKwE6v1NGQxug",
"username": "TED",
"name": "TED",
"url": "https://www.youtube.com/@TED"
},
"created_at": "2016-04-06T00:00:00",
"collected_at": "2026-07-16T08:00:00Z",
"extra": {
"duration_seconds": 843
}
}
Los campos más importantes para el procesamiento posterior son:
text: la transcripción seleccionada en texto plano.language: el idioma que realmente se devolvió, que puede diferir del solicitado.available_languages: los idiomas de transcripción no vacíos encontrados para el video.transcript_source: la clasificación del origen de los subtítulos, cuando se conoce.id,url,titleyauthor: contexto de la fuente para la trazabilidad.created_atycollected_at: fechas de publicación y de recopilación.extra.duration_seconds: útil para verificaciones de calidad y estimaciones de carga de trabajo.
La respuesta es texto plano de forma deliberada. No contiene marcas de tiempo confiables por segmento ni etiquetas de hablantes. No invente horas precisas para las citas ni convierta la respuesta a SRT como si existieran datos de tiempo.
Obtenga las transcripciones en el idioma correcto
El idioma de la solicitud es una preferencia, no una garantía. Un flujo de trabajo en producción debe guiarse siempre por el language devuelto.
Por ejemplo, si solicita en:
- Puede seleccionarse una pista en inglés.
- Puede seleccionarse una pista compatible del idioma base.
- Puede devolverse otra pista disponible como alternativa de respaldo.
- Puede no generarse ningún registro si no hay una transcripción pública utilizable.
Guarde language y available_languages con cada transcripción. Si la cobertura exacta de idiomas es obligatoria, rechace o revise los resultados de respaldo en lugar de enviarlos directamente a traducción, búsqueda o un LLM.
Conserve también transcript_source. Los subtítulos generados automáticamente pueden ser valiosos a escala, pero YouTube señala que el audio deficiente, los idiomas no admitidos, los silencios largos, las voces superpuestas y la mezcla de idiomas pueden impedir o reducir la calidad de los subtítulos automáticos. Consulte la guía de YouTube para solucionar problemas de subtítulos automáticos.
Procese transcripciones de YouTube en bloque
El procesamiento en bloque debe diseñarse como un pipeline de datos, no como un bucle que supone que todas las URL funcionan.
Video URLs
↓
Validate and deduplicate
↓
Submit transcript batches
↓
Persist task IDs
↓
Poll with backoff
↓
Read every result page
↓
Validate language and source
↓
Store, chunk, index, or export
Aplique estas prácticas:
- Normalice las URL antes de enviarlas. Reduzca las URL duplicadas de visualización, de compartir y de inserción al mismo ID de video.
- Mantenga los lotes recuperables. Guarde cada lote, sus URL de entrada, el ID de tarea, la hora de envío y el estado terminal.
- Consulte con espera progresiva. Evite un bucle de consulta muy ajustado. Aumente la demora mientras la tarea siga en cola o en ejecución.
- Considere normal la salida parcial. Una tarea exitosa puede contener menos registros que las URL enviadas porque algunos videos no tienen subtítulos utilizables.
- Pagine hasta completar. Continúe hasta que
has_moresea false. - Haga idempotentes las escrituras. Use upsert por ID de video más idioma de la transcripción para que los reintentos no creen duplicados.
- Registre la hora de recopilación. Una transcripción es una instantánea; los subtítulos pueden editarse o eliminarse más adelante.
Este es un patrón mínimo de consulta en Node.js:
const headers = {
Authorization: `Bearer ${process.env.SOCQ_API_KEY}`,
"Content-Type": "application/json"
};
const submitted = await fetch(
"https://api.socq.ai/v1/youtube/transcripts",
{
method: "POST",
headers,
body: JSON.stringify({
urls: [
"https://www.youtube.com/watch?v=arj7oStGLkU",
"https://www.youtube.com/watch?v=dQw4w9WgXcQ"
],
language: "en"
})
}
).then(response => response.json());
let task;
do {
await new Promise(resolve => setTimeout(resolve, 3000));
task = await fetch(
`https://api.socq.ai/v1/tasks/${submitted.task_id}?limit=50`,
{ headers }
).then(response => response.json());
} while (["queued", "running"].includes(task.data.status));
if (task.data.status !== "succeeded") {
throw new Error(`Transcript task ended with ${task.data.status}`);
}
const transcripts = task.data.results.items;
Antes de usarlo en producción, agregue verificaciones del estado HTTP, reintentos acotados, paginación por cursor, registros estructurados y cancelación.
Maneje los subtítulos faltantes y los resultados parciales
Un resultado faltante no significa automáticamente que todo el lote haya fallado. Las causas más comunes son:
- El creador no proporcionó subtítulos y los subtítulos automáticos no están disponibles.
- Los subtítulos todavía se están procesando en un video publicado recientemente.
- El idioma hablado no es compatible o no fue reconocido.
- La calidad del audio es deficiente, las voces se superponen o el video contiene varios idiomas.
- El video es privado, fue eliminado, tiene restricciones o no está disponible en el entorno de recopilación.
- El idioma solicitado no existe y no hay una alternativa de respaldo utilizable.
Clasifique los fallos en lugar de reintentarlos indefinidamente:
| Tipo de fallo | Acción recomendada |
|---|---|
| Sin subtítulos utilizables | Marcar como no disponible; opcionalmente, derivar a un flujo ASR independiente |
| Falta el idioma solicitado | Revisar available_languages o aceptar una alternativa de respaldo controlada |
| Error temporal de la tarea o de la red | Reintentar con espera exponencial y un límite |
| Video privado, eliminado o con restricciones | Dejar de reintentar y registrar el motivo |
| Transcripción vacía o sospechosa | Poner en cuarentena para validación |
No presente la salida de ASR como un subtítulo de YouTube sin identificar la fuente. La distinción importa para las revisiones de exactitud y las citas.
Exporte los datos de las transcripciones de forma segura
Los resultados en texto plano se pueden exportar a TXT, JSON o CSV.
Para TXT, escriba el campo text y conserve un registro de metadatos aparte. Para JSON, conserve el objeto normalizado completo. Para CSV, use una fila por video con campos como id, url, title, language, transcript_source, text y collected_at.
SRT y VTT requieren segmentos con tiempos. Como el endpoint de transcripciones de SocQ devuelve texto plano y no segmentos, no es posible generar una exportación fiel de subtítulos con tiempos solo a partir de esta respuesta.
Para archivos con capacidad de búsqueda, no guarde solamente el cuerpo de la transcripción. Conserve el ID del video, la URL canónica, el título, el canal, el idioma, la fuente, la fecha de publicación y la fecha de recopilación en cada registro derivado.
Prepare las transcripciones para búsqueda y RAG
Las transcripciones sin procesar suelen ser demasiado grandes y ruidosas para enviarlas a un modelo como un solo bloque. Un mejor flujo de trabajo es:
- Normalizar los espacios en blanco sin reescribir la fuente.
- Detectar texto inesperadamente corto o vacío.
- Dividir el texto en fragmentos semánticos con solapamiento.
- Adjuntar los metadatos de la fuente a cada fragmento.
- Crear embeddings.
- Guardar los fragmentos en un índice de búsqueda o vectorial.
- Devolver la URL del video y los metadatos de la transcripción con cada respuesta.
Un registro de fragmento útil se ve así:
{
"video_id": "arj7oStGLkU",
"video_url": "https://www.youtube.com/watch?v=arj7oStGLkU",
"title": "Inside the Mind of a Master Procrastinator",
"language": "en",
"transcript_source": "auto_generated",
"chunk_index": 12,
"text": "The transcript text for this chunk...",
"collected_at": "2026-07-16T08:00:00Z"
}
Como la respuesta de origen no tiene marcas de tiempo por segmento, cite el video en lugar de afirmar un intervalo de tiempo exacto. Si las citas a nivel de tiempo son esenciales, elija una fuente que ofrezca segmentos verificados o agregue un paso de alineación independiente.
Elija la API de YouTube adecuada antes de obtener transcripciones
La recopilación de transcripciones suele ser el último paso de un flujo de descubrimiento más amplio:
- Use YouTube Search API para encontrar videos públicos relevantes y filtrar por disponibilidad de subtítulos.
- Use YouTube Videos API para obtener metadatos normalizados de videos.
- Use YouTube Channel Videos API para armar el inventario de un canal seleccionado.
- Use YouTube Transcripts API solo para los videos cuyo texto realmente necesita.
Esto reduce las solicitudes de transcripción innecesarias y mantiene el conjunto de datos final vinculado a criterios de descubrimiento explícitos.
Mantenga actualizado un conjunto de datos de transcripciones
Un archivo de transcripciones debe tener una política de actualización explícita. Los subtítulos pueden corregirse después de la publicación, pueden aparecer nuevas pistas de idioma, y un video disponible antes puede eliminarse o restringirse. Volver a obtener todo cada día es un desperdicio, pero tratar la primera respuesta como permanente puede dejar un índice de búsqueda con texto desactualizado o imposible de rastrear.
Elija un intervalo de actualización según el caso de uso:
- Para un conjunto de datos de investigación puntual, guarde la hora de recopilación y evite las actualizaciones automáticas, salvo que el análisis las requiera.
- Para un archivo de canal con capacidad de búsqueda, revise con más frecuencia los videos recientes, porque los subtítulos suelen editarse poco después de la publicación.
- Para flujos de cumplimiento o de citas textuales, vuelva a validar la fuente antes de publicar una cita o tomar una decisión de alto impacto.
- Para sistemas RAG de larga duración, conserve un hash del contenido para que una transcripción sin cambios no active trabajo innecesario de nueva fragmentación y de embeddings.
Cuando una transcripción actualizada cambie, cree una nueva versión o conserve un registro de auditoría en lugar de sobrescribir en silencio la única copia. Como mínimo, guarde el ID del video, el idioma de la transcripción, el origen de los subtítulos, la hora de recopilación, el hash del texto y la versión del pipeline. Si un video deja de producir un resultado, marque el registro existente como no disponible en la última verificación; no suponga que la transcripción histórica fue siempre inválida.
Lista de verificación para producción
Antes de ejecutar un trabajo de alto volumen, verifique que:
- Las entradas sean URL públicas de videos de YouTube.
- Las URL se hayan normalizado y deduplicado.
- Los ID de tarea y las entradas originales estén guardados.
- La consulta use demoras y reintentos acotados.
- La paginación por cursor continúe hasta que
has_moresea false. - Los resultados faltantes se traten por separado de los fallos de tareas.
- Se valide el idioma devuelto.
- Los subtítulos generados automáticamente estén etiquetados.
- Cada fragmento o exportación conserve los metadatos de la fuente.
- Su uso del contenido respete los derechos aplicables, las expectativas de privacidad y los términos de la plataforma.
Preguntas frecuentes (FAQ)
¿Existe una API oficial de transcripciones de YouTube?
YouTube tiene una Captions API oficial, pero descargar una pista de subtítulos requiere OAuth y permiso para editar el video. No es una API general de transcripciones para videos públicos arbitrarios.
¿Se puede descargar una transcripción de YouTube sin OAuth?
La SocQ YouTube Transcripts API usa una clave de API de SocQ en lugar de una autorización OAuth de YouTube. Obtiene el texto de transcripción disponible de URL públicas de videos seleccionados.
¿SocQ puede generar una transcripción cuando un video no tiene subtítulos?
No. El endpoint devuelve el texto de transcripción pública disponible. Un video sin subtítulos utilizables puede no producir ningún resultado. Use un flujo de voz a texto declarado por separado si necesita una alternativa de respaldo con ASR.
¿Se puede solicitar un idioma específico?
Sí. Puede enviar un idioma BCP-47 opcional, como en o zh-CN, pero el idioma que realmente se devuelva puede ser distinto. Revise siempre language y available_languages.
¿La respuesta incluye marcas de tiempo y etiquetas de hablantes?
No. El formato de la respuesta es texto plano normalizado y no incluye marcas de tiempo por segmento ni etiquetas de hablantes garantizadas.
¿Se pueden obtener varias transcripciones en una sola solicitud?
Sí. Envíe varias URL públicas de videos en urls, guarde el ID de la tarea y lea todas las páginas de resultados completadas después de que la tarea asíncrona termine con éxito.
¿Cuánto cuesta la YouTube Transcripts API?
La documentación actual del endpoint indica 0.5 créditos por resultado de transcripción normalizado. Consulte la página en vivo del endpoint antes de estimar una carga de trabajo en producción, porque los precios pueden cambiar.
YOUTUBE API
Probar el flujo de trabajo con una URL pública de YouTube
Envíe entradas públicas y reciba registros normalizados con contexto de origen rastreable.
Ver las API de YouTube