# FlashData 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.

Referencia canónica: https://flashdata.dev/es/docs/sources/youtube_download
Reviewed: 2026-10-23

Punto final: POST https://data.flashdata.dev/v1/queries
Autenticación: X-API-Key: YOUR_API_KEY
Modos: [Asíncrono](https://flashdata.dev/es/docs/reference/realtime-and-async/reference.md#async) · [Batch](https://flashdata.dev/es/docs/reference/batch-and-bulk/reference.md#batch) · [Bulk](https://flashdata.dev/es/docs/reference/bulk-processing/reference.md)

Permiso de origen obligatorio: youtube_download

Reemplace YOUR_API_KEY con una tecla API que tiene este permiso de origen y créditos disponibles. Ejecute solicitudes en su servidor o host de agente.

[Configuración de autenticación](https://flashdata.dev/es/docs/guides/headers-and-authentication/reference.md)

[Descargar un vídeo y verificar la entrega](https://flashdata.dev/es/docs/guides/download-video-recipe/reference.md)

[API de descarga de vídeos de YouTube — ejemplos en Python](https://github.com/flashdatadev/youtube-video-download-api)

<a id="quickstart"></a>

## Enviar solicitud

### Python

```bash
python3 -m pip install requests
```

```python
import json

import requests

api_key = "YOUR_API_KEY"
payload = {
    "source": "youtube_download",
    "video_id": "jNQXAC9IVRw",
    "params": {
        "download_type": "audio_video",
        "video_quality": "<=720",
        "output_format": "mp4",
        "storage": {
            "storage_type": "s3",
            "storage_url": "your-media-bucket",
            "access_key": "YOUR_ACCESS_KEY",
            "secret_key": "YOUR_SECRET_KEY",
            "region": "us-east-1",
        },
    },
}

response = requests.post(
    "https://data.flashdata.dev/v1/queries",
    headers={"X-API-Key": api_key},
    json=payload,
    timeout=120,
)
response.raise_for_status()
print(json.dumps(response.json(), ensure_ascii=False, indent=2))
```

### Bash / cURL

```bash
api_key="YOUR_API_KEY"
curl --fail-with-body --max-time 120 --request POST "https://data.flashdata.dev/v1/queries" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $api_key" \
  --data-binary @- <<'FLASHDATA_JSON'
{
  "source": "youtube_download",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "download_type": "audio_video",
    "video_quality": "<=720",
    "output_format": "mp4",
    "storage": {
      "storage_type": "s3",
      "storage_url": "your-media-bucket",
      "access_key": "YOUR_ACCESS_KEY",
      "secret_key": "YOUR_SECRET_KEY",
      "region": "us-east-1"
    }
  }
}
FLASHDATA_JSON
```

<a id="parameters"></a>

## Parámetros

<a id="parameters-group-0"></a>

### Solicitud de cuerpo

| Parámetro | Tipo | Obligatorio | Default | Descripción |
| --- | --- | --- | --- | --- |
| <a id="parameter-source"></a> source | string | Sí. | — | Listo para youtube_download.  |
| <a id="parameter-video_id"></a> video_id | string | Sí. | Sin definir | El 11-character YouTube video ID, como FUfGcZ092b0. Acepta letras, números, subrayados e hifénes. Longitud mínima: 11. Longitud máxima: 11. Patrón: ^[A-Za-z0-9_-]{11}$ |
| <a id="parameter-params"></a> params | object | Sí. | — | Ajustes para esta solicitud.  |
| <a id="parameter-callback_url"></a> callback_url | string · nullable | No. | Sin definir | 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.  |

<a id="parameters-group-1"></a>

### Video &amp; audio

| Parámetro | Tipo | Obligatorio | Default | Descripción |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-download_type"></a> params.download_type | string | No. | "audio_video" | audio_video fusiona el vídeo y el audio; el vídeo solo selecciona el vídeo; el audio selecciona el audio solamente. Permitido: "audio_video", "video", "audio". Longitud mínima: 1. Longitud máxima: 11. |
| <a id="parameter-params-video_quality"></a> params.video_quality | string | No. | "<=720" | Selección de resolución de vídeo. Omit para descargas solo de audio. Permitido: "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", ">=4320". Longitud mínima: 1. Longitud máxima: 40. |
| <a id="parameter-params-fps"></a> params.fps | string | No. | Sin definir | Limitación de la tasa de franqueo: не=, не= o == seguido de un valor de 1 a 240. Omit para descargas de audio solamente. Longitud mínima: 1. Longitud máxima: 6. Patrón: ^(?:>=\|<=\|==)(?:[1-9]\d?\|1\d\d\|2[0-3]\d\|240)$ |
| <a id="parameter-params-audio_language"></a> params.audio_language | string | No. | "default" | Selección de pistas de audio. Aplica a audio_video y audio. Permitido: "default", "original". Longitud mínima: 1. Longitud máxima: 8. |
| <a id="parameter-params-audio_quality"></a> params.audio_quality | string | No. | "best" | Solo bitrate de audio en kbps, o mejor. Numeric opciones deben ser enviadas como cadenas. Omit para descargas de vídeo. Permitido: "best", "320", "256", "192", "128". Longitud mínima: 1. Longitud máxima: 10. |
| <a id="parameter-params-output_format"></a> params.output_format | string | No. | mp4 (video) / m4a (audio) | Video: mp4, webm o mkv. Audio: m4a, mp3 o pulpo. Permitido: "mp4", "webm", "mkv", "m4a", "mp3", "opus". Longitud mínima: 1. Longitud máxima: 10. |
| <a id="parameter-params-yt_dlp_format"></a> params.yt_dlp_format | string | No. | Sin definir | 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. Longitud mínima: 1. Longitud máxima: 1024. |
| <a id="parameter-params-upload_metadata"></a> params.upload_metadata | boolean | No. | false | Cargue un archivo de metadatos JSON junto con el archivo multimedia en su almacenamiento.  |

<a id="parameters-group-2"></a>

### Clipping

| Parámetro | Tipo | Obligatorio | Default | Descripción |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-start_at"></a> params.start_at | string | No. | Sin definir | 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. Longitud mínima: 1. Longitud máxima: 8. Patrón: ^\d{1,2}:[0-5]\d:[0-5]\d$ |
| <a id="parameter-params-end_at"></a> params.end_at | string | No. | Sin definir | Fin de clip en H:MM:SS o HH:MM:SS formato, hasta 12:00:00. Debe ser más tarde que start_at. Longitud mínima: 1. Longitud máxima: 8. Patrón: ^\d{1,2}:[0-5]\d:[0-5]\d$ |

<a id="parameters-group-3"></a>

### Destino de almacenamiento

| Parámetro | Tipo | Obligatorio | Default | Descripción |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-storage"></a> params.storage | object | Sí. | — | Destino para los archivos multimedia completados. Sólo se aceptan los campos de almacenamiento listados.  |
| <a id="parameter-params-storage-storage_type"></a> params.storage.storage_type | string | Sí. | — | Proveedor de almacenamiento: s3, s3_compatible, oss, gcs, azure, porque, bos o tos.  |
| <a id="parameter-params-storage-storage_url"></a> params.storage.storage_url | string | Sí. | — | 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.  |
| <a id="parameter-params-storage-object_prefix"></a> params.storage.object_prefix | string | No. | "YYYYMMDD" | 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.  |
| <a id="parameter-params-storage-access_key"></a> params.storage.access_key | string | No. | — | llave de acceso para S3, S3-compatible, OSS, COS, BOS o TOS; emparejado con secret_key.  |
| <a id="parameter-params-storage-secret_key"></a> params.storage.secret_key | string | No. | — | Clave secreta para S3, S3-compatible, OSS, COS, BOS o TOS.  |
| <a id="parameter-params-storage-endpoint_url"></a> params.storage.endpoint_url | string | No. | — | Public HTTPS endpoint for S3-compatible storage or OSS. COS, BOS y TOS derivan de la región.  |
| <a id="parameter-params-storage-region"></a> params.storage.region | string | No. | — | 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.  |
| <a id="parameter-params-storage-service_account"></a> params.storage.service_account | object | No. | — | Cuenta de servicio GCS: project_id, client_email y PEM private_key.  |
| <a id="parameter-params-storage-account_name"></a> params.storage.account_name | string | No. | — | Nombre de la cuenta de almacenamiento Azure. Utilice el nombre del contenedor en storage_url.  |
| <a id="parameter-params-storage-sas_token"></a> params.storage.sas_token | string | No. | — | Contenedor Azure SAS con expiración y firma.  |

<a id="response"></a>

## 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.

### read-response.py

```python
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))
```

## Presentación de muestras

Ejemplo registrado; campos y conteos dependen de la fuente y la entrada solicitada.
```json
{
  "id": "job_d265c693-950e-40bf-a13e-a432044d99ba",
  "source": "youtube_download",
  "status": "pending",
  "usage": {
    "credits": 0
  },
  "created_at": "2026-09-16T07:51:13.139Z",
  "links": [
    {
      "rel": "self",
      "href": "https://api.flashdata.dev/v2/jobs/job_d265c693-950e-40bf-a13e-a432044d99ba",
      "method": "GET"
    },
    {
      "rel": "results",
      "href": "https://api.flashdata.dev/v2/jobs/job_d265c693-950e-40bf-a13e-a432044d99ba/results",
      "method": "GET"
    }
  ]
}
```

## Campos de respuesta

| Campo | Tipo | Descripción |
| --- | --- | --- |
| id | string | Descargar trabajo ID. |
| source | string | youtube_download. |
| status | string | pendiente cuando se acepta el trabajo. |
| created_at | string | Tiempo de creación de empleo en formato ISO 8601. |
| usage.credits | number | 0 en la presentación. Las descargas se cargan mediante el volumen de datos entregado después de la terminación. |
| links | array | Siga el enlace propio para el estado de trabajo y el enlace de resultados para la salida finalizada. |
| links[].rel | string | auto o resultados. |
| links[].href | string | URL para consultar con la misma tecla API. |
| links[].method | string | GET. |

- Descargas ejecutadas como trabajos de fondo. La respuesta de la presentación contiene un trabajo ID; no contiene el archivo multimedia. Siga el estado de trabajo hasta la terminación, y luego recupere el resultado describiendo los archivos entregados a su almacenamiento. Presentar descargas a /v1/queries o /v1/queries/batch; /v1/queries/realtime no acepta solicitudes de descarga.

## Formatos de respuesta

Las respuestas utilizan JSON por defecto. Elige otro formato con estos encabezados opcionales.

- Accept: application/json (por defecto) o text/plain. El texto sencillo presenta los mismos campos en un diseño legible e indentado.
- X-Respond-With: markdown. Deja unset para campos originales. Markdown funciona con formato de respuesta.

Markdown formatea el manifiesto de descarga; los archivos multimedia mantienen su formato original. Receipts y soporte de estado de trabajo Accept solamente.

Los campos de abajo describen la respuesta JSON predeterminada.

[Ejemplos de formularios de solicitud y respuesta](https://flashdata.dev/es/docs/guides/response-formats/reference.md#completed-results)

<a id="storage"></a>

## Destino de almacenamiento

Las descargas de un solo trabajo y Batch requieren params.storage; Bulk Las descargas usan options.storage. storage_url es el nombre de cubo o contenedor. Suministrar credenciales con acceso a escritura y mantenerlas en su servidor.

### s3

Suministro access_key y secret_key con acceso a escritura. Establecer región a la región de AWS de su cubo.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "storage_type": "gcs",
  "storage_url": "your-media-bucket",
  "service_account": {
    "project_id": "your-project-id",
    "client_email": "uploader@your-project-id.iam.gserviceaccount.com",
    "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.

```json
{
  "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.

```json
{
  "storage_type": "tos",
  "storage_url": "your-media-bucket",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "cn-beijing"
}
```

<a id="job-lifecycle"></a>

<a id="async-batch"></a>

## Conceptos básicos de la API

El constructor de solicitudes y los ejemplos anteriores utilizan los parámetros de esta fuente. Use los ejemplos Python y cURL a continuación para la presentación compartida, estado y pasos de resultado. Un cuerpo Batch es un objeto JSON que contiene consultas; cada artículo devuelve su propio trabajo ID.

- [Solicitud y recepción de Async](https://flashdata.dev/es/docs/reference/realtime-and-async/reference.md#async)

<a id="job-status"></a>

- [Consultar el estado del trabajo](https://flashdata.dev/es/docs/reference/realtime-and-async/reference.md#status)

<a id="job-results"></a>

- [Recuperar los resultados](https://flashdata.dev/es/docs/reference/realtime-and-async/reference.md#results)
- [Batch JSON peticiones](https://flashdata.dev/es/docs/reference/batch-and-bulk/reference.md#batch)
- [API de procesamiento Bulk](https://flashdata.dev/es/docs/reference/bulk-processing/reference.md)
- [Construir un flujo de trabajo Bulk para esta fuente](https://flashdata.dev/es/docs/reference/bulk-processing/reference.md?source=youtube_download#playground)
- [Cliente OpenAPI](https://flashdata.dev/docs/openapi.json)

<a id="webhooks"></a>

<a id="callbacks"></a>

## Notificaciones de terminación

- [Recibir y verificar los juegos web de terminación](https://flashdata.dev/es/docs/guides/async-batch/reference.md#webhooks)

<a id="troubleshooting"></a>

## Solución de problemas

- [Errores y códigos de estado](https://flashdata.dev/es/docs/errors/reference.md#status-codes)
- [Cuándo volver a entrar](https://flashdata.dev/es/docs/errors/reference.md#retries)

<a id="delivery"></a>

## Entrega de archivos

Download no admite en tiempo real.

Los medios se cargan en su almacenamiento configurado; resultado JSON describe esos archivos. Los medios privados utilizan su autenticación de almacenamiento. Los resultados de JSON expiran horas después de la terminación 24; los medios siguen su política de retención de almacenamiento.

## API relacionadas

- [YouTube Metadatos de vídeo API](https://flashdata.dev/es/docs/sources/youtube_metadata/reference.md)
- [YouTube Transcript API](https://flashdata.dev/es/docs/sources/youtube_transcript/reference.md)
