# Buenas prácticas de YouTube Download

Elige el formato de salida, controla lo que descargas y recupera un archivo privado utilizable a partir del trabajo completado.

Referencia canónica: https://flashdata.dev/es/docs/guides/youtube-download-guide
Revisado: 2026-11-04 por FlashData

<a id="choose"></a>

## Empieza con lo que tu tarea necesita

| Tu objetivo | Uso |
| --- | --- |
| Resumir contenido hablado o construir un índice de texto | Leer una transcripción existente primero. Descargar audio sólo cuando su flujo de trabajo necesita el audio en sí, como un paso de habla a texto separado. |
| Procesamiento de voz o audio | Solo salida de audio. Evite llevar una pista de vídeo que su aplicación no utiliza. |
| Mostrar un breve extracto | Establecer start_at y end_at. Compruebe que ambos están dentro de la duración del vídeo fuente. |
| Reproducción o proceso de vídeo | MP4 con audio y un límite de resolución adecuado para su aplicación; el ejemplo usa <=720. |

- [Resúmenes de las capciones](https://flashdata.dev/es/docs/guides/youtube-summary/reference.md)
- [Inspeccionar metadatos de vídeo](https://flashdata.dev/es/docs/guides/youtube-data-guide/reference.md#metadata)

<a id="formats"></a>

## Ahorre la salida que desee

Elija una pestaña y ahorre toda su solicitud como download-request.json. Cambiar video_id para su fuente. Los comandos de presentación a continuación leen este archivo, así que elegir audio o un clip cambia la solicitud real.

### MP4 / 720p

Un video completo con audio, capped a 720p.

#### download-request.json

```json
{
  "source": "youtube_download",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "download_type": "audio_video",
    "output_format": "mp4",
    "video_quality": "<=720"
  }
}
```


### MP3

Un archivo de audio para el procesamiento de audio o de audio.

#### download-request.json

```json
{
  "source": "youtube_download",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "download_type": "audio",
    "output_format": "mp3"
  }
}
```


### 5-segundo clip

Un extracto MP4 de 00:00:05 a 00:00:10. Utilice los tiempos que coincidan con su vídeo seleccionado.

#### download-request.json

```json
{
  "source": "youtube_download",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "download_type": "audio_video",
    "output_format": "mp4",
    "video_quality": "<=720",
    "start_at": "00:00:05",
    "end_at": "00:00:10"
  }
}
```


- [Todas las opciones de formato](https://flashdata.dev/es/docs/sources/youtube_download/reference.md#parameters)

<a id="prepare"></a>

## Consultar el acceso del propietario y precios basados en byte

Utilice Bash y jq, además de un perfil CLI guardado o FLASHDATA_API_KEY para HTTP. Las necesidades clave permiso youtube_download. Descarga requiere acceso propietario; acceso temporal a prueba no lo incluye. Los ejemplos CLI usan su perfil predeterminado; agregue --profile NAME a cada comando.

| Decisión | Aplicar de esta manera |
| --- | --- |
| Costo estimado | Utilice el creditsPerTb devuelto y bytesPerUnit con sus bytes de salida estimados. Los precios de descarga no son una carga fija por solicitud. |
| Alcance de control | Elija audio, un clip o una tapa de resolución antes de la presentación. Aplique la cuenta de trabajo y reglas de gasto en su aplicación. |
| Grabar la carga real | Lea el uso de la entrega completada. La admisión puede tener créditos antes de que la carga se resuelva; el saldo actual no es una tapa de gasto por trabajo. |

### Cheques gratis · CLI

```bash
flashdata account balance --json
flashdata account pricing --source youtube_download --json
flashdata account limits --json
```

- [Configuración de llave del propietario](https://flashdata.dev/es/docs/guides/api-keys-and-permissions/reference.md)
- [Equilibrio y precios HTTP](https://flashdata.dev/es/docs/guides/credits-and-billing/reference.md#balance)

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

## Utilice un destino privado para cada salida

Guardar storage.json en privado con tus valores de destino reales. Mantenerlo fuera de control de fuente. Usar un object_prefix distinto para cada versión de video/output; reutilizar un prefijo para diferentes salidas hace que los registros de aplicaciones sean más difíciles de conciliar.

| Credencial | Propósito |
| --- | --- |
| FlashData clave | Presentar la descarga y leer su trabajo y entrega JSON. |
| Subir almacenamiento credencial | Escribe medios al cubo y prefijo deseados. |
| Identidad de almacenamiento de aplicaciones | Lea el objeto privado o emita acceso a un usuario autorizado. |

### storage.json · S3

```json
{
  "storage_type": "s3",
  "storage_url": "YOUR_BUCKET",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "us-east-1",
  "object_prefix": "media/video-001/mp4-720p-v1"
}
```

### Linux / macOS · archivo privado

```bash
chmod 600 storage.json
```

- [permisos de archivo Windows](https://flashdata.dev/es/docs/guides/cli-automation/reference.md#storage)
- [Otros proveedores de almacenamiento](https://flashdata.dev/es/docs/sources/youtube_download/reference.md#storage)

<a id="submit"></a>

## Presentar la solicitud guardada una vez

Ejecute una pestaña después de guardar ambos archivos. storage.json a través de stdin y salva download-submission.jsonMantenga este recibo. CLI, mantener la misma carrera ID para una reingresación; utilizar un nuevo ID sólo para un nuevo producto intencional. HTTP las comunicaciones no utilizan el CLIEs un diario local.

### CLI

#### Presentar la salida elegida

```bash
(
set -eu
umask 077
test ! -e download-submission.json || { echo 'Inspect the saved submission first.' >&2; exit 1; }
PAYLOAD=$(jq -en --slurpfile request download-request.json --slurpfile storage storage.json '
  if ($request | length) != 1 or ($storage | length) != 1
      or ($storage[0] | type) != "object" or $request[0].source != "youtube_download"
  then error("Check download-request.json and storage.json")
  else $request[0] | .params.storage = $storage[0] end')
printf '%s' "$PAYLOAD" | flashdata query --input - --mode async \
  --run-id download-001 --output download-submission.json
)
```


### HTTP / cURL

#### Presentar la salida elegida

```bash
(
set -eu
umask 077
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e download-submission.json || { echo 'Inspect the saved submission first.' >&2; exit 1; }
PAYLOAD=$(jq -en --slurpfile request download-request.json --slurpfile storage storage.json '
  if ($request | length) != 1 or ($storage | length) != 1
      or ($storage[0] | type) != "object" or $request[0].source != "youtube_download"
  then error("Check download-request.json and storage.json")
  else $request[0] | .params.storage = $storage[0] end')
printf '%s' "$PAYLOAD" | curl --fail-with-body --silent --show-error --max-time 70 \
  --request POST 'https://data.flashdata.dev/v1/queries' \
  --header "X-API-Key: $FLASHDATA_API_KEY" --header 'Content-Type: application/json' \
  --data-binary @- --output download-submission.json
)
```


- [Contrato de solicitud de Async](https://flashdata.dev/es/docs/reference/realtime-and-async/reference.md#async)

<a id="dry-run"></a>

### Validar primero con el CLI

Espera bien: verdadero y data.dryRun: verdadero. Esto comprueba la entrada y el acceso FlashData sin enviar un trabajo; no prueba que las credenciales de carga pueden escribir a su cubo.

#### Corrección seca gratuita

```bash
(
set -eu
PAYLOAD=$(jq -en --slurpfile request download-request.json --slurpfile storage storage.json '
  if ($request | length) != 1 or ($storage | length) != 1
      or ($storage[0] | type) != "object" or $request[0].source != "youtube_download"
  then error("Check download-request.json and storage.json")
  else $request[0] | .params.storage = $storage[0] end')
printf '%s' "$PAYLOAD" | flashdata query --input - --mode async --dry-run --json
)
```


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

### Esperar el trabajo existente

El recibo de la presentación no es el archivo multimedia. CLI espera; el comando HTTP lee el estado una vez. Repita la lectura dentro de su plazo hasta que se haya completado o fallado. Un timeout local no cancela el trabajo del servidor.

#### CLI

##### Espera el trabajo salvado.

```bash
(
set -eu
JOB_ID=$(jq -er '.remoteId // .id' download-submission.json)
flashdata jobs wait "$JOB_ID"
)
```


#### HTTP / cURL

##### Leer estado una vez

```bash
(
set -eu
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
STATUS_URL=$(jq -er '.links[] | select(.rel == "self") | .href' download-submission.json)
curl --fail-with-body --silent --show-error --max-time 30 \
  --header "X-API-Key: $FLASHDATA_API_KEY" --header 'Accept: application/json' \
  "$STATUS_URL" --output job.json
jq '.job | {id, status, error}' job.json
)
```



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

## Lea el registro de entrega, luego acceda a los medios

Después de completarse, recuperar delivery.json utilizando el mismo camino que solía enviar. El resultado firmado URL recupera JSON; resultados[0].file_url identifica los medios en su almacenamiento. Un file_url privado necesita su identidad de lectura de almacenamiento o un enlace emitido por su aplicación.

### CLI

#### Guardar delivery.json

```bash
(
set -eu
JOB_ID=$(jq -er '.remoteId // .id' download-submission.json)
flashdata jobs result "$JOB_ID" --output delivery.json
jq '.results[0] | {file_url, file_size, md5, downloaded_bytes}' delivery.json
)
```


### HTTP / cURL

#### Entrega de embrague JSON · mantener la tecla API fuera de las solicitudes de almacenamiento

```bash
(
set -eu
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
jq -e '.job.status == "completed"' job.json >/dev/null
RESULTS_URL=$(jq -er '.links[] | select(.rel == "results") | .href' download-submission.json)
# Get the signed JSON URL without forwarding the API key to storage.
STORAGE_URL=$(curl --fail-with-body --silent --show-error --max-time 30 \
  --header "X-API-Key: $FLASHDATA_API_KEY" --header 'Accept: application/json' \
  --output /dev/null --write-out '%{redirect_url}' "$RESULTS_URL")
: "${STORAGE_URL:?No signed result URL was returned}"
curl --fail-with-body --silent --show-error --compressed --max-time 70 \
  "$STORAGE_URL" --output delivery.json
jq '.results[0] | {file_url, file_size, md5, downloaded_bytes}' delivery.json
)
```



<a id="inspect"></a>

### Revisa lo que se entregó

Espere una ubicación de archivo, un file_size positivo, un MD5 y el uso. Record file_size para el objeto entregado; downloaded_bytes es un campo de transferencia, no un reemplazo para la carga final en el uso.

#### Inspección delivery.json

```bash
(
set -eu
jq -e '.source == "youtube_download" and .status == "done"
  and (.results | length == 1) and (.results[0].file_size > 0)
  and (.results[0].md5 | test("^[a-fA-F0-9]{32}$"))' delivery.json >/dev/null
jq '{file: (.results[0] | {file_url, file_size, md5, duration, output_format}), usage}' delivery.json
)
```

- [Verificar y servir a un objeto privado](https://flashdata.dev/es/docs/guides/media-delivery-pipeline/reference.md#verify)

<a id="verify-media"></a>

### Verificar una copia local de S3

Establecer OBJECT_KEY a la clave de medios entregada de file_url, incluyendo su prefijo. Utilice AWS CLI con acceso de lectura, jq y OpenSSL. Esto ahorra media.mp4 o media.mp3 según su solicitud elegida y comprueba su tamaño y suma de comprobación sin sobreescribir un archivo local existente.

#### S3 read · ninguna nueva consulta FlashData

```bash
(
set -eu
# Requires AWS CLI configured for read access, jq and OpenSSL.
# Set OBJECT_KEY to the delivered media object's key from file_url.
: "${OBJECT_KEY:?Set the delivered S3 object key}"
BUCKET=$(jq -er '.storage_url' storage.json)
REGION=$(jq -er '.region' storage.json)
FORMAT=$(jq -er '.params.output_format' download-request.json)
case "$FORMAT" in mp4|mp3) ;; *) echo 'Choose a filename for this format.' >&2; exit 1 ;; esac
LOCAL_FILE="media.$FORMAT"
test ! -e "$LOCAL_FILE" || { echo 'Keep the existing local file.' >&2; exit 1; }
EXPECTED_BYTES=$(jq -er '.results[0].file_size' delivery.json)
EXPECTED_MD5=$(jq -er '.results[0].md5 | ascii_downcase' delivery.json)
aws s3 cp "s3://$BUCKET/$OBJECT_KEY" "$LOCAL_FILE" --region "$REGION" --only-show-errors
ACTUAL_BYTES=$(wc -c < "$LOCAL_FILE" | tr -d '[:space:]')
ACTUAL_MD5=$(openssl dgst -md5 "$LOCAL_FILE" | awk '{print $NF}')
test "$ACTUAL_BYTES" = "$EXPECTED_BYTES"
test "$ACTUAL_MD5" = "$EXPECTED_MD5"
echo 'Delivery verified'
)
```

- [Retención de resultados y medios almacenados](https://flashdata.dev/es/docs/guides/save-results/reference.md#media)

<a id="operations"></a>

## Recuperar desde el escenario que falló

| Qué pasó. | Siguiente acción |
| --- | --- |
| Presentación programada sin trabajo confirmado ID | Inspeccione el CLI guardado o historial de solicitud. Mantenga la entrada original y no vuelva a enviar automáticamente. |
| Trabajo aceptado; espera tiempo fuera | Lea o recupere el mismo trabajo. No cree otra descarga para continuar esperando. |
| Subida fallada | Lea el error de trabajo y fije los ajustes de destino o escriba el acceso antes de reintentar intencionalmente. |
| Medios de comunicación devueltos 403 | Compruebe los permisos de almacenamiento de lectura o el enlace con la aplicación. La tecla FlashData API no desbloquea S3. |
| Resultado firmado JSON expirado | Lea el punto final del resultado del trabajo de nuevo mientras se mantiene el resultado. Los medios almacenados siguen el ciclo de vida de su cubo. |

### CLI · inspeccionar la carrera salvada

```bash
flashdata runs show download-001 --json
```

- [Decisiones de recuperación](https://flashdata.dev/es/docs/guides/agent-recovery/reference.md)
- [Errores y códigos de estado](https://flashdata.dev/es/docs/errors/reference.md)
- [Tareas recurrentes](https://flashdata.dev/es/docs/guides/recurring-tasks/reference.md)

<a id="agent"></a>

## Dar a su agente los criterios de salida y entrega

### Tareas del agente · el suministro del vídeo, destino y presupuesto

```text
Utilice mi acceso del propietario guardado y almacenamiento privado configurado.
Lea download-request.json para el vídeo y la salida; no los cambie en silencio.
Compruebe los precios de descarga y los créditos disponibles en relación con el presupuesto de tareas aprobado.
Presentar una vez, guardar el run/job ID, luego leer ese trabajo para completarlo.
Ahorre el registro de entrega. Verifique el tamaño del objeto almacenado y MD5 antes de procesarlo.
Informar la ubicación del objeto, formato elegido, resultado de verificación y uso real.
Si la presentación es incierta, inspeccione el trabajo guardado; no cree el acceso de reemplazo u otra descarga.
Mantenga las credenciales de almacenamiento privadas. Compartir los medios sólo a través de los controles de acceso configurados de la aplicación.
```

- [Construir el oleoducto de aplicación](https://flashdata.dev/es/docs/guides/media-delivery-pipeline/reference.md)
