Explorar documentación
Referencia de la API
YouTube Descargar API
Descargar el vídeo YouTube o el audio a su almacenamiento en la nube. Elija la resolución, formato y duración del clip, luego siga el trabajo asincrónico a través de la terminación.
API de descarga de vídeos de YouTube — ejemplos en Python
Prepara una solicitud
El 11-character ID del vídeo URL, no el URL completo.
Opciones de medios avanzados
Un selector de formato supera la calidad, la velocidad de marco y la selección de audio-idioma. El formato de salida y los límites de clip todavía se aplican.
Destino de almacenamiento
Blank utiliza la fecha de carga UTC (YYYYYMMDD).
Añade tus credenciales de almacenamiento en tu servidor antes de ejecutar el código. Necesitan permiso para subir archivos.
Credenciales del proveedor y requisitos de almacenamientoCompletion webhook
Carga de pago Webhook, verificación y retriesMarkdown se aplica a los resultados completados. Los receipts y el estado de trabajo mantienen sus campos originales.
https://data.flashdata.dev/v1/queriesPará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_download.
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 / Obligatorio- Ajustes para esta solicitud.
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
Video & audio
params.download_typestring / Opcional- audio_video fusiona el vídeo y el audio; el vídeo solo selecciona el vídeo; el audio selecciona el audio solamente.1 a 11 personajesValores:
audio_video / video / audioDefault:"audio_video" params.video_qualitystring / Opcional- Selección de resolución de vídeo. Omit para descargas solo de audio.1 a 40 personajesValores:
best / worst / <=144 / ==144 / >=144 / <=360 / ==360 / >=360 / <=480 / ==480 / >=480 / <=720 / ==720 / >=720 / <=1080 / ==1080 / >=1080 / <=1440 / ==1440 / >=1440 / <=2160 / ==2160 / >=2160 / <=4320 / ==4320 / >=4320Default:"<=720" params.fpsstring / Opcional- Limitación de la tasa de franqueo: не=, не= o == seguido de un valor de 1 a 240. Omit para descargas de audio solamente.1 a 6 personajesDefault:
Sin definirFormato aceptado
^(?:>=|<=|==)(?:[1-9]\d?|1\d\d|2[0-3]\d|240)$ params.audio_languagestring / Opcional- Selección de pistas de audio. Aplica a audio_video y audio.1 a 8 personajesValores:
default / originalDefault:"default" params.audio_qualitystring / Opcional- Solo bitrate de audio en kbps, o mejor. Numeric opciones deben ser enviadas como cadenas. Omit para descargas de vídeo.1 a 10 personajesValores:
best / 320 / 256 / 192 / 128Default:"best" params.output_formatstring / Opcional- Video: mp4, webm o mkv. Audio: m4a, mp3 o pulpo.1 a 10 personajesValores:
mp4 / webm / mkv / m4a / mp3 / opusDefault:mp4 (video) / m4a (audio) params.yt_dlp_formatstring / Opcional- Selector de formato avanzado, desde 1 a caracteres 1,024 después de recortar el espacio blanco. Los caracteres de control son rechazados. Sobrescribe video_quality, fps y audio_language, cuyos valores son ignorados; el formato de salida y el recortado todavía se aplican.1 a 1024 personajesDefault:
Sin definir params.upload_metadataboolean / Opcional- Cargue un archivo de metadatos JSON junto con el archivo multimedia en su almacenamiento.
trueofalseDefault:false
Clipping
params.start_atstring / Opcional- Inicio de Clip en H:MM:SS o HH:MM:SS formato, desde 00:00:00 a 12:00:00. Predeterminados a 00:00:00 cuando sólo se suministra end_at.1 a 8 personajesDefault:
Sin definirFormato aceptado
^\d{1,2}:[0-5]\d:[0-5]\d$ params.end_atstring / Opcional- Fin de clip en H:MM:SS o HH:MM:SS formato, hasta 12:00:00. Debe ser más tarde que start_at.1 a 8 personajesDefault:
Sin definirFormato aceptado
^\d{1,2}:[0-5]\d:[0-5]\d$
Destino de almacenamiento
params.storageobject / Obligatorio- Destino para los archivos multimedia completados. Sólo se aceptan los campos de almacenamiento listados.
params.storage.storage_typestring / Obligatorio- Proveedor de almacenamiento: s3, s3_compatible, oss, gcs, azure, porque, bos o tos.
params.storage.storage_urlstring / Obligatorio- Bote no vacío o nombre de contenedor, hasta caracteres 1,024. El espacio blanco circundante se elimina. Para s3, utilice un nombre de cubo AWS válido sin un URL o ruta de carpeta; las carpetas pertenecen a object_prefix.
params.storage.object_prefixstring / Opcional- Prefijo de la llave del objeto, 1 a 512 caracteres. Cada segmento separado acepta letras, dígitos, puntos, puntos, subrayados e hifénes; segmentos vacíos, y .. son rechazados. No hay barras líderes. Alrededor del espacio blanco y una barra de seguimiento son eliminados. YYYYYYMMDD utiliza la fecha de carga de UTC, incluyendo en archivo/YYYYMMDD.Default:
"YYYYMMDD" params.storage.access_keystring / Opcional- llave de acceso para S3, S3-compatible, OSS, COS, BOS o TOS; emparejado con secret_key.
params.storage.secret_keystring / Opcional- Clave secreta para S3, S3-compatible, OSS, COS, BOS o TOS.
params.storage.endpoint_urlstring / Opcional- Public HTTPS endpoint for S3-compatible storage or OSS. COS, BOS y TOS derivan de la región.
params.storage.regionstring / Opcional- Necesario para COS, BOS y TOS; también suministro para S3 y descargas compatibles con S3. Los nombres de los cubos de COS incluyen el APPID.
params.storage.service_accountobject / Opcional- Cuenta de servicio GCS: project_id, client_email y PEM private_key.
params.storage.account_namestring / Opcional- Nombre de la cuenta de almacenamiento Azure. Utilice el nombre del contenedor en storage_url.
params.storage.sas_tokenstring / Opcional- Contenedor Azure SAS con expiración y firma.
Respuesta
El constructor de solicitudes envía descargas con Async o Batch y requiere params.storage. HTTP 200 con status: pending confirma aceptación, no entrega. Batch devuelve un recibo de trabajo por vídeo ID.
Submission usage.credits es 0. Las descargas son facturadas por el volumen de medios entregados después de la entrega exitosa; los archivos de metadatos opcionales no se añaden a los cargos de descarga.
Poll job.status hasta completed, luego recuperar el resultado JSON. Lea los detalles de los medios en results[0], incluyendo el objeto cargado file_url, tamaño de archivo y suma de comprobación.
Lea el resultado
Después de completar el trabajo, guardar el JSON de su enlace de resultados como response.json. Guardar esto como read-response.py y ejecutar python read-response.py. Lee los detalles de archivo sin descargar los medios o hacer otra solicitud.
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 = {name: result.get(name) for name in (
"file_url", "file_size", "md5", "duration", "output_format"
)}
# Use your storage credentials to access the media at file_url.
print(json.dumps(output, ensure_ascii=False, indent=2))El estado puede incluir detalles de los medios de comunicación job.result. Los flujos de trabajo predeterminados JSON los utilizan cuando están disponibles y siguen de otro modo rel: results enlace; no asuma un resultado en línea siempre está presente.
All submission response fields
| Campo | Descripción |
|---|---|
idstring | Descargar trabajo ID. |
sourcestring | youtube_download. |
statusstring | pendiente cuando se acepta el trabajo. |
created_atstring | Tiempo de creación de empleo en formato ISO 8601. |
usage.creditsnumber | 0 en la presentación. Las descargas se cargan mediante el volumen de datos entregado después de la terminación. |
linksarray | Siga el enlace propio para el estado de trabajo y el enlace de resultados para la salida finalizada. |
links[].relstring | auto o resultados. |
links[].hrefstring | URL para consultar con la misma tecla API. |
links[].methodstring | GET. |
Campos de archivos multimedia completados
| Campo | Descripción |
|---|---|
results[0].file_urlstring | Ubicación del archivo multimedia en su almacenamiento. |
results[0].file_sizeinteger | Tamaño del archivo multimedia en bytes. |
results[0].downloaded_bytesinteger | Entregar bytes de medios usados para facturación. |
results[0].md5string | MD5 checksum del archivo multimedia. |
results[0].resolutionstring · nullable | Resolución de vídeo, o nula para la salida audio-sólo o la altura no disponible. |
results[0].durationnumber · nullable | Duración en segundos cuando esté disponible. |
results[0].output_formatstring | Formato de archivo de salida. |
results[0].fpsnumber · nullable | Tasa de franqueo cuando esté disponible. |
results[0].video_codecstring · nullable | Video codec cuando esté disponible. |
results[0].audio_codecstring · nullable | Audio codec cuando esté disponible. |
results[0].dynamic_rangestring · nullable | Gama dinámica de vídeo cuando esté disponible. |
results[0].metadataobject · optional | Metadata file_url, file_size y md5 cuando upload_metadata es cierto. Los bytes de metadatos están excluidos de los cargos de descarga. |
Los campos arriba describen la respuesta predeterminada JSON. Las opciones de formato se aplican al registro de entrega, no al archivo multimedia. JSON, texto plano y formatos Markdown.
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
Presentar una descarga con Async, o poner múltiples solicitudes de descarga dentro de una matriz de consultas Batch. Cada entrada necesita params.storage. Guardar 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.
El JSON describe los medios entregados a su almacenamiento. Acceso al archivo multimedia.
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.
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_download",
"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_download. Las opciones compartidas se aplican a cada ID en el archivo.
Ponga el destino de almacenamiento requerido en options.storage y configuración de los medios en options. Las descargas de un solo trabajo y Batch usan params.storage en su lugar.
Los archivos multimedia se entregan a su almacenamiento en la nube. El resultado Bulk completado incluye un manifiesto y partes de resultados que describen las descargas. 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
Destino de almacenamiento
Incluido params.storage en cada solicitud de descarga. storage_url a su nombre de cubo o contenedor y proporcionar credenciales con acceso a escritura. Mantenga las credenciales de almacenamiento en su servidor.
{
"storage_type": "s3_compatible",
"storage_url": "your-media-bucket",
"object_prefix": "archive/YYYYMMDD",
"endpoint_url": "https://your-s3-endpoint.example.com",
"region": "your-provider-region",
"access_key": "<storage-access-key>",
"secret_key": "<storage-secret-key>"
}object_prefix predeterminados a YYYYMMDD, reemplazado por la fecha de carga de UTC. Utilice un directorio fijo o una plantilla como archive/YYYYMMDD.
s3- Suministro access_key y secret_key con acceso a escritura. Establecer región a la región de AWS de su cubo.
s3 ejemplo
{ "storage_type": "s3", "storage_url": "your-media-bucket", "access_key": "YOUR_ACCESS_KEY", "secret_key": "YOUR_SECRET_KEY", "region": "us-east-1" } s3_compatible- Suministro access_key, secret_key y un HTTPS público endpoint_url. Establecer la región según lo requiera su proveedor; Cloudflare R2 utiliza auto.
s3_compatible ejemplo
{ "storage_type": "s3_compatible", "storage_url": "your-media-bucket", "access_key": "YOUR_ACCESS_KEY", "secret_key": "YOUR_SECRET_KEY", "endpoint_url": "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com", "region": "auto" } azure- Suministro account_name y sas_token, un contenedor SAS con permiso de escritura (sp incluye w), recurso sr=c, vencimiento se, versión sv y sig de firma. storage_url es el nombre del contenedor. No enviar endpoint_url, access_key o secret_key.
azure ejemplo
{ "storage_type": "azure", "storage_url": "your-media-container", "account_name": "yourstorageaccount", "sas_token": "sv=2023-11-03&sr=c&sp=w&se=2099-01-01T00%3A00%3A00Z&sig=YOUR_SAS_SIGNATURE" } bos- Suministro access_key, secret_key y región: bj, su o hkg. El punto final se deriva de la región cuando se omite. Utilice un nombre de cubo sin puntos.
bos ejemplo
{ "storage_type": "bos", "storage_url": "your-media-bucket", "access_key": "YOUR_ACCESS_KEY", "secret_key": "YOUR_SECRET_KEY", "region": "bj" } Porque...- Suministro access_key, secret_key y una región ap-*, como ap-hongkong. storage_url debe incluir el sufijo APPID. No enviar endpoint_url; se deriva de la región.
Porque... ejemplo
{ "storage_type": "cos", "storage_url": "your-media-bucket-1234567890", "access_key": "YOUR_ACCESS_KEY", "secret_key": "YOUR_SECRET_KEY", "region": "ap-hongkong" } gcs- Suministro service_account con project_id, client_email (una dirección .gserviceaccount.com), y el PEM private_key desde su cuenta de servicio. La cuenta debe tener acceso a la cuenta de escritura. No enviar access_key, secret_key, región o endpoint_url.
gcs ejemplo
{ "storage_type": "gcs", "storage_url": "your-media-bucket", "service_account": { "project_id": "your-project-id", "client_email": "[email protected]", "private_key": "-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY\n-----END PRIVATE KEY-----\n" } } Oss- Suministro access_key, secret_key y el HTTPS público de la región de cubos endpoint_url.
Oss ejemplo
{ "storage_type": "oss", "storage_url": "your-media-bucket", "access_key": "YOUR_ACCESS_KEY", "secret_key": "YOUR_SECRET_KEY", "endpoint_url": "https://oss-cn-hongkong.aliyuncs.com" } tos- Suministro access_key, secret_key y región con un prefijo cn-, ap-, eu- o us-. El punto final se deriva de la región cuando se omite. Utilice un nombre de cubo sin puntos.
tos ejemplo
{ "storage_type": "tos", "storage_url": "your-media-bucket", "access_key": "YOUR_ACCESS_KEY", "secret_key": "YOUR_SECRET_KEY", "region": "cn-beijing" }
El resultado es file_url Identifica un objeto en su almacenamiento. Los objetos privados requieren la autorización de su proveedor de almacenamiento o un URL firmado; la tecla FlashData API no otorga acceso a su cubo.
Para una presentación completa, votación y descarga de flujo de trabajo, ver Descargar YouTube audio a Amazon S3.
Entrega de archivos
El trabajo. rel: results endpoint defaults to a redirect to resultado JSON, no una descarga MP4. FlashData sube los medios reales al cubo o contenedor que proporcionó. La retención de medios sigue la política de su cubo; el resultado del trabajo JSON expira las horas 24 después de la terminación.
results[0].file_url Identifica el objeto pero no es automáticamente un URL público o firmado. Acceda a los medios privados con su almacenamiento SDK, o genere un URL firmado a corto plazo en su propio servidor. No envíe la tecla FlashData API a su proveedor de almacenamiento.
Habilitación upload_metadata para subir un {video_id}_meta.json compañero en el mismo prefijo. Su ubicación y suma de comprobación aparecen bajo results[0].metadata.
El modo de descarga del navegador de la consola es separado. Las descargas públicas API usan su propio almacenamiento; no incluyen consola solo browser_delivery Ajustes.
Recuperación de errores
Para fallos de carga o almacenamiento 403, verifique el proveedor, cubo, región, punto final y permisos de escritura de objeto. file_url no significa por sí mismo que la carga falló: verifique el objeto a través de su proveedor de almacenamiento.
Un vídeo eliminado o no disponible no puede ser recuperado por la encuesta. Para formatos no disponibles, inspeccionar Formatos de metadatos, relajar las limitaciones de calidad o eliminar el selector avanzado. m4a, mp3 o opus; solicitudes de vídeo mp4, webm o mkv.
Si el resultado JSON ha expirado, primero compruebe su cubo para los medios entregados. La presentación crea una nueva descarga y puede incurrir en otro cargo; no recupera el resultado antiguo JSON.
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: Descargar un vídeo y verificar la entrega
Precios
| Planes | Tarifas de usopor GB | Suscripciones | Créditos incluidos por período de facturación |
|---|---|---|---|
| Pago por uso | 0,10 US$ | Sin cuota mensual | Añade créditos cuando los necesites |
| Micro | 0,08 US$ | 49,00 US$ / mes | Créditos 1000 (50,00 US$ de uso API) incluidos |
| Starter | 0,07 US$ | 199,00 US$ / mes | Créditos 4000 (200,00 US$ de uso API) incluidos |
| Pro | 0,06 US$ | 499,00 US$ / mes | Créditos 10.000 (500,00 US$ de uso API) incluidos |
| Scale | 0,05 US$ | 999,00 US$ / mes | Créditos 20.000 (1000,00 US$ de uso API) incluidos |
| Business | 0,04 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