Explorar documentación
Referencia de la API
YouTube Capciones API
Recuperar las capciones YouTube como texto de timetamped y una transcripción completa. Las subscripciones proporcionadas por el cargador se seleccionan por defecto.
Prepara una solicitud
El 11-character ID del vídeo URL, no el URL completo.
Deje en blanco para probar en-orig, luego en, y devuelva una pista. O introduzca un código o hasta 10 códigos distintos separados separados por comas.
https://data.flashdata.dev/v1/queries/realtimeParámetros
Enviar source y video_id en el nivel superior. Las opciones de fuentes pertenecen a params. Se pueden omitir campos opcionales.
Solicitud de cuerpo
sourcestring / Obligatorio- Listo para youtube_captions.
video_idstring / Obligatorio- El 11-character YouTube video ID, como FUfGcZ092b0. Acepta letras, números, subrayados e hifénes.Exactamente 11 personajesDefault:
Sin definirFormato aceptado
^[A-Za-z0-9_-]{11}$ paramsobject / Opcional- Ajustes para esta solicitud.Default:
{} callback_urlstring · nullable / Opcional- Solo Async y lote. Public HTTPS completion URL en port 443, hasta caracteres 2,048. No hay credenciales de usuario o fragmento URL. Omitir, usar null o una cadena vacía para ninguna notificación. En un lote, establece esto en cada consulta, fuera de los params.Default:
Sin definir
Selección de la capa
params.languagestring | array / Opcional- Omit for English (en-orig, then en). Con auto=true, cada código prueba su -orig track primero, luego el código solicitado. Explicit -orig codes and auto=false stay exact. Arrays request 1-10 distinct languages.Default:
en-orig → en params.autoboolean / Opcional- true selecciona las subtítulos generados por YouTube; falsos selecciona las subidas proporcionadas por subidor. Esto selecciona el origen de la capción, no la detección del lenguaje o la nueva transcripción.
trueofalseDefault:false
Respuesta
Realtime devuelve status: done. Lea la salida de la fuente en results[0]; usage.credits registra la carga.
Lea los segmentos para el texto de la capción con los tiempos de start/end en segundos y fullText para el texto unido. languageCode y isAutoGenerated reportan la pista seleccionada.
Lea el resultado
Guardar la respuesta JSON exitosa como response.json. Guardar esto como read-response.py y ejecutar python read-response.py. Utiliza sólo la biblioteca estándar de Python y no hace ninguna nueva petición.
import json
from pathlib import Path
response = json.loads(Path("response.json").read_text(encoding="utf-8-sig"))
if response.get("status") not in ("done", "completed") or not isinstance(response.get("results"), list):
raise SystemExit("Expected completed result JSON; inspect the response or job status.")
if not response["results"]:
print("[]")
raise SystemExit(0)
result = response["results"][0]
output = {
"tracks": result.get("tracks", [result]),
"errors": result.get("errors", []),
}
print(json.dumps(output, ensure_ascii=False, indent=2))Omit language to prefer en-orig and fall back to en, returning one track. Con auto=true, cada código solicitado prefiere su pista -orig, luego el código llano; explicit -orig y auto=false stay exact. Arrays prueba cada idioma solicitado y devuelve pistas y errores en orden. languageCode identifica la pista seleccionada; requestedLanguageCode se incluye cuando difiere.
Para las listas de idiomas, consulta errors para identificar las pistas que fallaron. Si no se recupera ninguna pista, la solicitud falla y se reembolsan los créditos reservados. Los errores de extracción de vídeo y el vencimiento del plazo también provocan un fallo.
auto predeterminado a falso para subidor-provided captions. Se establece fiel para las subtítulos automáticos. El API nunca cambia fuentes de capción.
El API lee las versiones YouTube existentes; no genera nuevas transcripciones. La respuesta predeterminada contiene segmentos JSON normalizados; Accept puede seleccionar texto plano y X-Respond-With: marcador selecciona Markdown. languageName puede ser nulo; los tiempos de segmento se conservan.
Idiomas múltiples
Envíe un array de idiomas para recibir pistas y errores por idioma. Este ejemplo muestra inglés disponible y español no disponible.
{
"source": "youtube_captions",
"video_id": "jNQXAC9IVRw",
"params": {
"language": [
"en",
"es"
],
"auto": false
}
}{
"videoId": "jNQXAC9IVRw",
"isAutoGenerated": false,
"tracks": [
{
"videoId": "jNQXAC9IVRw",
"languageCode": "en",
"languageName": null,
"isAutoGenerated": false,
"segments": [
{
"start": 0,
"end": 1.5,
"text": "Hello world."
}
],
"fullText": "Hello world."
}
],
"errors": [
{
"languageCode": "es",
"code": "language_unavailable",
"message": "Uploader-provided subtitles not available for language: es"
}
]
}Todos los campos de respuesta
| Campo | Descripción |
|---|---|
sourcestring | La fuente API solicitada. |
statusstring | hecho cuando la solicitud en tiempo real tiene éxito. |
created_atstring | Tiempo de creación de respuestas en formato ISO 8601. |
usage.creditsnumber | Créditos cobrados para la solicitud, basado en su plan. |
results[0].videoIdstring | El vídeo solicitado ID. |
results[0].languageCodestring | Actual código de pista seleccionado, como en-orig. |
results[0].languageNamestring · nullable | Nombre de la pantalla del idioma cuando esté disponible. |
results[0].requestedLanguageCodestring · optional | El código solicitado cuando difiere de languageCode, por ejemplo en cuando se selecciona en-orig. |
results[0].isAutoGeneratedboolean | Ya sea que se generaran automáticamente las subtítulas seleccionadas. |
results[0].segmentsarray | Segmentos de captura en orden cronológico. |
results[0].segments[].startnumber | Segment comienza el tiempo en segundos. |
results[0].segments[].endnumber | Segmento final en segundos. |
results[0].segments[].textstring | Texto de captura. |
results[0].fullTextstring | Todo el texto del segmento se unió a una transcripción. |
results[0].tracksarray · optional | Solo para arrays de idiomas. Pistas disponibles en pedido; cada uno tiene los campos de una sola pista enumerados anteriormente. |
results[0].errorsarray · optional | Para los arrays de idiomas solamente. Lenguas fallidas en el orden de solicitud. Vacíe cuando cada pista tenga éxito. |
results[0].errors[].languageCodestring | El lenguaje solicitado que falló. |
results[0].errors[].codestring | language_unavailable cuando la pista seleccionada no existe; retrieval_failed cuando no puede ser descargado o analizado. |
results[0].errors[].messagestring | Descripción del fallo del idioma. |
Los campos arriba describen la respuesta predeterminada JSON. JSON, texto plano y formatos Markdown.
Async devuelve un recibo de trabajo; el lote devuelve uno por video ID. Compruebe el estado de cada trabajo y recuperar sus resultados utilizando los enlaces devueltos.
Ciclo de vida de solicitudes asíncronas y por lotes
La presentación devuelve un recibo, no resultados. Async crea un trabajo; lote devuelve un trabajo separado en queries[] para cada consulta aceptada. Rastrear y recuperar cada trabajo de forma independiente.
Presentarse data.flashdata.dev; read job status and results from api.flashdata.dev con el mismo X-API-Key. Los ejemplos relacionados API utilizan Python y cURL.
1. Guardar el trabajo IDs
Mantenga los campos de solicitud de esta fuente al cambiar a Async. Para Batch, ponga cada solicitud dentro de la matriz de consultas de un objeto JSON. Ahorre cada trabajo devuelto ID.
2. Compruebe el estado
GET https://api.flashdata.dev/v2/jobs/{jobId}pending/processing: encuesta con un retraso y respetoRetry-Aftercuando esté presente.completed: resultados de búsqueda.failed: inspectivajob.error.Lea job.status, no el estado del recibo de la comunicación.
Estado de comprobación · Python y cURL
Estado de trabajo API referencia3. Resultados de los embragues
GET https://api.flashdata.dev/v2/jobs/{jobId}/resultsDespués de la finalización, autentique el resultado leído, después busque el almacenamiento 302 URL sin su llave API. Guarde el JSON dentro de las horas de terminación 24.
Resultados de búsqueda · Python y cURL · Formatos de respuesta
Resultado de la descarga API
Votar y buscar los resultados existentes no consumen créditos de consulta. Un tiempo de votación no cancela el trabajo: mantener su ID en lugar de enviar trabajo facturable duplicado. Códigos de error y comportamiento de reingreso.
Completion webhooks
Suscríbete por consulta
Set callback_url en el nivel superior de una solicitud de asinc, o dentro de cada consulta en un lote, afuera paramsNo se requiere ninguna solicitud de registro de webhook separada. Las solicitudes Realtime no envían llamadas.
Utilice un HTTPS URL público en el puerto 443. FlashData POSTs una notificación para cada trabajo que alcance completed o failed; el evento contiene enlaces, no el resultado mismo.
Reconocimiento y verificación
Regreso 2xx después de aceptar duramente el evento. Deduplicado delivery_id, también enviado como X-Delivery-IdNo se siguen las redirecciones.
Entregas fallidas de nuevo con retroceso exponencial, hasta 8 intentos totales y en la mayoría 24 horas después de la terminaciónSigue sondeando como un retroceso.
Los callbacks no son firmados. Confirme el trabajo ID, fuente y estado terminal a través del punto final de estado autenticado antes de procesar la notificación. La entrega ID es para la deduplicación, no prueba de autenticidad.
Ejemplo de evento webhook y campos
{
"delivery_id": "completion:job_example0001",
"id": "job_example0001",
"source": "youtube_captions",
"status": "completed",
"links": [
{
"rel": "self",
"href": "https://api.flashdata.dev/v2/jobs/job_example0001",
"method": "GET"
},
{
"rel": "results",
"href": "https://api.flashdata.dev/v2/jobs/job_example0001/results",
"method": "GET"
}
]
}| Campo | Descripción |
|---|---|
delivery_idstring | Identificador de entrega estable. Notificaciones deduplicadas utilizando este valor; también se envía en el encabezado X-Delivery-Id. |
idstring | Job ID. |
sourcestring | Solicitud de fuente de datos. |
statusstring | completado o fallado. |
linksarray | Enlaces de estado y resultados. Las notificaciones no incluyen el contenido de resultados o una clave API. |
links[].relstring | auto o resultados. |
links[].hrefstring | Gestión Absoluta API URL; autentique con su llave API. |
links[].methodstring | GET. |
Procesa archivos con Bulk
Subir un vídeo ID por línea y crear el trabajo Bulk con fuente: youtube_captions. Las opciones compartidas se aplican a cada ID en el archivo.
Opciones de origen: idioma, auto. Ponlos en opciones al crear el trabajo Bulk.
Recuperar la colección completa como un manifiesto y las partes de resultados de NDJSON. Las fuentes de datos también pueden entregar partes de resultados a su almacenamiento en la nube estableciendo options.result_storage al crear el trabajo Bulk. Guarde el manifiesto y las partes dentro de las horas 24 después de que todo el trabajo Bulk complete.
Bulk procesamiento API · Python y cURL · Batch JSON peticiones
Construir un flujo de trabajo Bulk para esta fuente · Pausa, reanudación y recuperación
Recuperación de errores
Un vídeo puede tener capciones automáticas pero sin pista manual, o carecer de su idioma solicitado. Compruebe la disponibilidad de la capción utilizando Metadata y elegir el idioma y el origen deliberadamente antes de una nueva presentación.
Consultar idiomas disponibles con metadatos. Una nueva solicitud utiliza créditos de consulta; cambiar una pista no modifica un trabajo existente.
Para la autenticación, equilibrio, formato de solicitud y fallos de tipo límite, utilice la referencia de error compartido. Un tiempo de presentación puede todavía haber creado un trabajo; comprobar el trabajo existente antes de volver a iniciar.
Errores y códigos de estado · Cuándo volver a entrar · Límites de solicitudes
Guía paso a paso: Obtén subtítulos con marcas de tiempo
Precios
| Planes | Tarifas de usosolicitudes estándar 1,000 | Suscripciones | Créditos incluidos por período de facturación |
|---|---|---|---|
| Pago por uso | 0,50 US$ | Sin cuota mensual | Añade créditos cuando los necesites |
| Micro | 0,40 US$ | 49,00 US$ / mes | Créditos 1000 (50,00 US$ de uso API) incluidos |
| Starter | 0,35 US$ | 199,00 US$ / mes | Créditos 4000 (200,00 US$ de uso API) incluidos |
| Pro | 0,30 US$ | 499,00 US$ / mes | Créditos 10.000 (500,00 US$ de uso API) incluidos |
| Scale | 0,25 US$ | 999,00 US$ / mes | Créditos 20.000 (1000,00 US$ de uso API) incluidos |
| Business | 0,20 US$ | 1999,00 US$ / mes | Créditos 40.000 (2000,00 US$ de uso API) incluidos |
Un plan de cuenta. Créditos compartidos en los tres productos. El uso cubierto por créditos incluidos no se cobra de nuevo.
Precios actuales y límites de los planes