# Buenas prácticas de YouTube Data

Encuentra vídeos relevantes, selecciona pistas de subtítulos y procesa los nuevos vídeos de un canal sin repetir trabajo.

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

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

## Comience con la información que ya tiene

Cada fuente responde a una pregunta diferente. Saltar descubrimiento para un vídeo conocido ID o mango de canal, y enriquecer sólo los vídeos que su tarea necesita.

| Su tarea | Fuente | Decisión |
| --- | --- | --- |
| Encontrar vídeos sobre un tema | youtube_search | Comience con cinco candidatos, luego seleccione por relevancia. |
| Inspeccione un video conocido | youtube_metadata | Obtener el título, el canal, la duración y los lenguajes de la capción. |
| Summarizar o citar lo que se dijo | youtube_transcript / youtube_captions | Elija un idioma y una pista automática o manual. |
| Chequee las cargas recientes de canal | youtube_channel | Compare devuelto IDs con su IDs procesado. |

- [Buscar vídeos](https://flashdata.dev/es/docs/guides/youtube-data-guide/reference.md#discover)
- [Trabajar con un vídeo conocido](https://flashdata.dev/es/docs/guides/youtube-data-guide/reference.md#metadata)
- [Monitorear un canal](https://flashdata.dev/es/docs/guides/youtube-data-guide/reference.md#channel)

<a id="setup"></a>

## Ejecute los ejemplos de solicitud

Guardar cada cuerpo JSON usando su nombre de archivo mostrado. Python utiliza el ayudante query.py a continuación; cURL puede enviar el mismo archivo. Utilice una clave con los permisos de origen que necesita y los créditos disponibles. Cada presentación es una consulta, independientemente del número de vídeos devueltos.

### Python

Python 3.10+. Instalar solicitudes una vez, guardar query.py abajo, luego utilizar el comando junto a cada solicitud. Los productos existentes se reutilizan; la entrada cambia requiere un nuevo nombre de archivo de salida.

#### Instalar

```bash
python -m pip install requests
```


### cURL

Bash. Reemplazar REQUEST.json y RESULT.json con los nombres de archivo para su ejemplo elegido. Compruebe el resultado antes de repetir una solicitud; este comando guarda el cuerpo HTTP incluso para un error.

#### Enviar una solicitud JSON guardada

```bash
(
set -eu
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e RESULT.json || { echo 'Read RESULT.json first'; exit 1; }
curl --fail-with-body --silent --show-error --max-time 70 \
  --request POST 'https://data.flashdata.dev/v1/queries/realtime' \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @REQUEST.json --output RESULT.json
)
```



<a id="authenticate"></a>

### Establecer la tecla API

Reutiliza FLASHDATA_API_KEY desde tu terminal o tienda secreta. De lo contrario, introduce la clave usando un aviso oculto a continuación. Manténgalo en el proceso ejecutando estos ejemplos.

#### Bash

##### Establecer la clave

```bash
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY
```


#### PowerShell 7

##### Establecer la clave

```powershell
# PowerShell 7: paste the key into a hidden prompt.
$flashdataSecureKey = Read-Host "FlashData API key" -AsSecureString
$env:FLASHDATA_API_KEY = [System.Net.NetworkCredential]::new("", $flashdataSecureKey).Password
Remove-Variable flashdataSecureKey
```


- [Claves API](https://flashdata.dev/app/api-keys)
- [Prueba para agentes y vinculación](https://flashdata.dev/es/docs/guides/agent-onboarding/reference.md)

<a id="runner"></a>

### Guardar query.py para los ejemplos Python

Crear query.py en una nueva carpeta de trabajo y copiar el código completo a continuación en ella. Guardar la solicitud archivos JSON y otros scripts Python en esta carpeta, y ejecutar todos los comandos desde allí.

#### query.py

```python
# query.py — submit a saved request once, then reuse its response.
import json
import os
import sys
from pathlib import Path
import requests

if len(sys.argv) != 3:
    raise SystemExit("Usage: python query.py REQUEST.json RESULT.json")
payload = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8-sig"))
output = Path(sys.argv[2])
marker = output.with_name(output.name + ".request.json")
receipt = output.with_name(output.name + ".http.json")
if marker.exists():
    if json.loads(marker.read_text()) != payload:
        raise SystemExit("Changed request: choose a new output filename.")
    if not output.exists() or not receipt.exists():
        raise SystemExit("Outcome unknown: check History before resubmitting.")
    saved = json.loads(receipt.read_text())
    if saved["status"] != 200 or json.loads(output.read_text(encoding="utf-8")).get("status") != "done":
        raise SystemExit(f"Saved request failed or incomplete; Retry-After: {saved['retry_after']}. Inspect {output}.")
    print(f"Read the saved {output}; no new query submitted.")
    raise SystemExit(0)
if output.exists():
    raise SystemExit("Output already exists. Read it or choose a new filename.")
key = os.environ["FLASHDATA_API_KEY"]
with marker.open("x", encoding="utf-8") as file:
    json.dump(payload, file)
response = requests.post("https://data.flashdata.dev/v1/queries/realtime",
                         headers={"X-API-Key": key}, json=payload,
                         timeout=70, allow_redirects=False)
output.write_text(response.text, encoding="utf-8")
receipt.write_text(json.dumps({"status": response.status_code,
                               "retry_after": response.headers.get("Retry-After")}), encoding="utf-8")
if response.status_code != 200:
    raise SystemExit(f"HTTP {response.status_code}; Retry-After: {response.headers.get('Retry-After')}")
if response.json().get("status") != "done":
    raise SystemExit(f"Inspect {output} and History before retrying.")
print(json.dumps({"saved": str(output), "usage": response.json().get("usage")}, indent=2))
```


<a id="discover"></a>

## Encontrar candidatos antes de buscar detalles

El filtro de vídeo excluye otros tipos de resultados; subtítulos reduce el descubrimiento a vídeos con subtítulos. No selecciona un idioma de leyenda o garantiza la pista que necesita. Guardar como discover-request.json.

### discover-request.json

```json
{
  "source": "youtube_search",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 5,
    "filters": {
      "type": "video",
      "subtitles": true
    }
  }
}
```

### Presentar una vez con query.py

```bash
python query.py discover-request.json search.json
```


<a id="candidates"></a>

### Seleccione por relevancia, no el primer ID

Guardar candidates.py junto a query.py y search.json, luego ejecutarlo desde esa carpeta. Guarda el orden de búsqueda y elimina el vídeo duplicado IDs. Inspecciona los títulos, canales y duración, luego copiar un ID seleccionado en la siguiente solicitud. Una lista vacía es una búsqueda completa sin candidatos.

#### candidates.py

```python
# candidates.py — read a saved response; no API calls.
import json
import re
from pathlib import Path

data = json.loads(Path("search.json").read_text(encoding="utf-8"))
if data.get("status") != "done":
    raise SystemExit("Search did not complete; inspect search.json.")
candidates, seen = [], set()
for item in (data.get("results") or [{}])[0].get("results", []):
    video_id = item.get("videoId", "")
    if not re.fullmatch(r"[A-Za-z0-9_-]{11}", video_id) or video_id in seen:
        continue
    seen.add(video_id)
    candidates.append({"videoId": video_id, "title": item.get("title"),
                       "channel": item.get("channel"), "duration": item.get("duration"),
                       "url": "https://www.youtube.com/watch?v=" + video_id})
Path("candidates.json").write_text(json.dumps(candidates, indent=2), encoding="utf-8")
print(json.dumps(candidates, indent=2))
```

#### Lea la búsqueda guardada

```bash
python candidates.py
```


<a id="extended"></a>

### Ampliar sólo cuando la lista es insuficiente

Standard Search admite max_results hasta 20. Para una colección más amplia, cambie a youtube_search_extended, que soporta hasta 700 y tiene precios separados. Este ejemplo pide 50; compruebe si sus primeros resultados son útiles antes de enriquecerlos a todos.

#### extended-request.json

```json
{
  "source": "youtube_search_extended",
  "query": "battery recycling process explained",
  "params": {
    "max_results": 50,
    "filters": {
      "type": "video"
    }
  }
}
```

#### Corre una vez.

```bash
python query.py extended-request.json extended.json
```

- [Presentar una búsqueda más larga sincrónicamente](https://flashdata.dev/es/docs/reference/realtime-and-async/reference.md#async)
- [Enrich seleccionado IDs](https://flashdata.dev/es/docs/guides/enrich-youtube-videos/reference.md)

<a id="metadata"></a>

## Recuperar sólo los metadatos que su característica necesita

Reemplace la muestra video_id con su ID seleccionado. Mantenga formatos y capítulos desactivados para una simple tarjeta de vídeo o verificación de lenguaje de la leyenda. Habilitar include_chapters para un contorno, o include_formats al elegir un formato multimedia.

### metadata-request.json

```json
{
  "source": "youtube_metadata",
  "video_id": "FUfGcZ092b0",
  "params": {
    "include_formats": false,
    "include_chapters": false
  }
}
```

### Presentar una vez con query.py

```bash
python query.py metadata-request.json metadata.json
```

- [Campos de respuesta a los metadatos](https://flashdata.dev/es/docs/sources/youtube_metadata/reference.md#response)
- [Flujo de trabajo para la entrega de medios](https://flashdata.dev/es/docs/guides/media-delivery-pipeline/reference.md)

<a id="tracks"></a>

### Inspección de los idiomas disponibles

Lea los resultados[0].transcriptLanguages antes de elegir los títulos. Formatos, capítulos e idiomas son campos en el objeto de vídeo devuelto; el registro de uso pertenece a la respuesta externa.

| Configuración | Úsalo para |
| --- | --- |
| language | Un código de transcriptLanguages, como en o zh-Hans. Esta lista no distingue las pistas manuales y automáticas. |
| auto: true | Una pista generada automáticamente. |
| auto: false | Una pista disponible manualmente. No hay retroceso entre los dos tipos de pista. |

#### Lea metadata.json · ninguna consulta

```bash
python -m json.tool metadata.json
```


<a id="captions"></a>

## Elija el idioma y la pista explícitamente

Utilice el mismo video_id como su solicitud de metadatos y cambiar el idioma y el auto para que coincida con la pista elegida. youtube_transcript predetermina para auto: verdadero; youtube_captions predetermina para auto: falso. Ambos recuperan las subtítulos existentes, no de palabra a texto.

### captions-request.json

```json
{
  "source": "youtube_transcript",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": true
  }
}
```

### Presentar una vez con query.py

```bash
python query.py captions-request.json captions.json
```

- [Parámetros de captura](https://flashdata.dev/es/docs/sources/youtube_transcript/reference.md#parameters)
- [Construir un resumen completo](https://flashdata.dev/es/docs/guides/youtube-summary/reference.md)

<a id="citations"></a>

### Mantenga el timetamp con la evidencia

Guardar cite-segments.py al lado de captions.json y ejecutarlo desde esa carpeta. Use resultados[0].Ejemplos para citas: inicio y final son segundos. Preserve languageCode y isAutoGenerated con el texto. fullText es útil para la lectura, pero no reemplaza el tiempo de segmento.

#### cite-segments.py

```python
import json
from pathlib import Path

response = json.loads(Path("captions.json").read_text(encoding="utf-8"))
if response.get("status") != "done":
    raise SystemExit("Inspect captions.json before continuing.")
track = (response.get("results") or [{}])[0]
if not track.get("segments"):
    raise SystemExit("No caption evidence was returned.")
for segment in track["segments"][:3]:
    url = f"https://www.youtube.com/watch?v={track['videoId']}&t={int(segment['start'])}s"
    print(segment["text"], url)
```

#### Leer las capturas guardadas · sin llamada API

```bash
python cite-segments.py
```


<a id="channel"></a>

## Procesar sólo nuevos vídeos de un canal conocido

Utilice un mango de canal y un video_limit (1–100). resultados[0].videos es la lista reciente devuelta; videoCount es metadatos de canal, no el número de artículos devueltos. Elija un límite y un horario que cubre las cargas que necesita observar.

### channel-request.json

```json
{
  "source": "youtube_channel",
  "handle": "@TED",
  "params": {
    "video_limit": 10
  }
}
```

### Presentar una vez con query.py

```bash
python query.py channel-request.json channel.json
```


<a id="channel-diff"></a>

### Mantenga una cola y un puesto de control de terminación

Guardar channel-queue.py junto a query.py y channel.json, y ejecutarlo desde esa carpeta. Ejecutar sin argumentos para crear new-ids.json, luego procesar y guardar evidencia para esos IDs. Ejecutar --commit sólo después de que cada ID con cola tenga éxito; un fallo deja el control sin cambios.

#### channel-queue.py

```python
# channel-queue.py — plan first; commit only after every queued video is processed.
import json
import re
import sys
from pathlib import Path

checkpoint = Path("processed-ids.json")
processed = set(json.loads(checkpoint.read_text()) if checkpoint.exists() else [])
queue = Path("new-ids.json")
if sys.argv[1:] == ["--commit"]:
    processed.update(json.loads(queue.read_text()))
    temporary = checkpoint.with_suffix(".tmp")
    temporary.write_text(json.dumps(sorted(processed)), encoding="utf-8")
    temporary.replace(checkpoint)
    queue.unlink()
    print("Checkpoint saved.")
elif sys.argv[1:]:
    raise SystemExit("Usage: python channel-queue.py [--commit]")
else:
    data = json.loads(Path("channel.json").read_text(encoding="utf-8"))
    if data.get("status") != "done":
        raise SystemExit("Channel query did not complete.")
    ids = dict.fromkeys(video.get("videoId", "") for video in
                        (data.get("results") or [{}])[0].get("videos", []))
    new = [value for value in ids if re.fullmatch(r"[A-Za-z0-9_-]{11}", value)
           and value not in processed]
    if queue.exists() and json.loads(queue.read_text()) != new:
        raise SystemExit("Finish the existing queue before replacing it.")
    queue.write_text(json.dumps(new, indent=2), encoding="utf-8")
    print(json.dumps(new, indent=2))
```

#### Plan → proceso → commit

```bash
python channel-queue.py
# Process every ID in new-ids.json and save its result first.
python channel-queue.py --commit
```

- [Calendario y reutilización de credenciales](https://flashdata.dev/es/docs/guides/recurring-tasks/reference.md)
- [Enriquezca una lista de vídeos](https://flashdata.dev/es/docs/guides/enrich-youtube-videos/reference.md)

<a id="channel-checkpoint"></a>

### Iniciar un cheque de canal fresco deliberadamente

El ayudante de consulta reutiliza una respuesta guardada. Para el siguiente cheque programado, utilice un nuevo nombre de archivo de resultado, inspeccione, luego copiar que la respuesta completada a channel.json para el paso de cola. Mantenga processed-ids.json entre carreras. Esta lista reciente no es una exportación de canales completos o un flujo de eventos.

#### Siguiente cheque · elegir un nuevo nombre de archivo

```bash
python query.py channel-request.json channel-next.json
```

#### Después de confirmar el estado se hace

```bash
python -c "from shutil import copyfile; copyfile('channel-next.json', 'channel.json')"
```


<a id="suggestions"></a>

## Use sugerencias para mejorar la consulta

Sugerencias devuelve frases en los resultados[0], no en los registros de vídeo. Seleccione una frase útil y haga una solicitud youtube_search separada. Establece el idioma y la región para el público que está investigando.

### suggestions-request.json

```json
{
  "source": "youtube_suggestions",
  "query": "battery recycling",
  "params": {
    "language": "en",
    "region": "US"
  }
}
```

### Presentar una vez con query.py

```bash
python query.py suggestions-request.json suggestions.json
```


<a id="license"></a>

## Almacene etiquetas de licencia sin tratarlas como permiso

youtube_trainability devuelve una etiqueta de licencia para un vídeo. permitido: ["all"] mapas a Creative Commons; ["none"] también cubre los metadatos de licencia desaparecidos. Mantenga el vídeo ID, respuesta de origen y fecha de recuperación. Esta etiqueta no otorga derechos de descarga, reutilización o entrenamiento.

### license-request.json

```json
{
  "source": "youtube_trainability",
  "video_id": "FUfGcZ092b0"
}
```

### Presentar una vez con query.py

```bash
python query.py license-request.json license.json
```


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

## Buscar el trabajo para aplicaciones y agentes

| Artículo | Aplicación |
| --- | --- |
| Seleccione antes de enriquecer | Para una tarea de tema: una búsqueda, uno seleccionado metadatos de vídeo y una pista de captura elegida. Ejecute el presupuesto de llamada en su aplicación, y precio cada fuente por separado. |
| Reutilización por la entrada real | Metadatos: video ID + opciones. Capciones: video ID + idioma + pista. instantáneas de canales también necesitan un tiempo de recuperación o ejecutar ID. |
| Dejar de perder evidencia | No reingrese un resultado de descubrimiento vacío o cambie silenciosamente las pistas de capción. Devuelve la brecha para que el usuario o el flujo de trabajo puedan elegir la siguiente acción. |
| Preservar el uso y el trabajo fallido | Guardar el uso con respuestas exitosas. En 429, honor Retry-After; después de una presentación incierta, comprobar Historia antes de otra consulta pagada. |

- [Tiempo real y modo asíncrono](https://flashdata.dev/es/docs/reference/realtime-and-async/reference.md)
- [Batch y Bulk](https://flashdata.dev/es/docs/reference/batch-and-bulk/reference.md)
- [Errores y registros](https://flashdata.dev/es/docs/errors/reference.md#retries)
- [Actual fijación de precios y equilibrio](https://flashdata.dev/es/docs/guides/credits-and-billing/reference.md)
