# Metadata van één video ophalen

Zet een YouTube video ID om in een opgeslagen record van zijn titel, kanaal, duur en beschikbare nummers. Houd de oorspronkelijke reactie en het gebruik ernaast.

Canonische referentie: https://flashdata.dev/nl/docs/guides/video-metadata-recipe
Beoordeeld: 2026-11-05 door FlashData

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

## Voordat u begint

Gebruik een sleutel met youtube_metadata toestemming en beschikbare credits. Kies Python 3.10+ met verzoeken, of Bash met cURL 7.76+ en jq. Gebruik Git Bash op Windows voor de Bash versie.

- [Een API-sleutel aanmaken](https://flashdata.dev/app/api-keys)
- [Proefgebruik en accountkoppeling](https://flashdata.dev/nl/docs/guides/agent-onboarding/reference.md)
- [Kredieten en prijzen](https://flashdata.dev/nl/docs/guides/credits-and-billing/reference.md)

<a id="input"></a>

## 1. Kies één video

Maak een video-metadatamap en sla request.json daar op. Open een terminal in die map. Vervang video_id door het 11-karakter ID van een horloge URL of een YouTube Search-resultaat; passeer niet het volledige URL.

Stel beide optionele vlaggen expliciet in: dit eerste verzoek laat mediaformaten en hoofdstukken weg. Het haalt metadata op zonder de video of de bijschriften te downloaden.

### video-metadata/request.json

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


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

## 2. De metadata ophalen en opslaan

Kies één versie en sla het script op naast request.json. Het leest FLASHDATA_API_KEY of vraagt om uw sleutel op een verborgen prompt. Agenten moeten die omgevingsvariabele uit hun geheime winkel laden.

Uitvoeren met snapshot-001 als uitvoermap. Een nieuwe map stuurt een metadata-query en slaat het gerapporteerde gebruik op. Het script controleert op een succesvol antwoord met precies één video met de gevraagde ID voordat u video.json schrijft.

### Python

#### Installeer in uw Python omgeving

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

#### video-metadata/metadata.py

```python
import argparse
import getpass
import json
import os
import re
from datetime import datetime, timezone
from pathlib import Path

import requests

parser = argparse.ArgumentParser()
parser.add_argument("folder", help="New output folder, or an existing saved snapshot")
out = Path(parser.parse_args().folder)

if not out.exists():
    body = Path("request.json").read_bytes()
    request = json.loads(body)
    if (not isinstance(request, dict) or request.get("source") != "youtube_metadata"
            or not isinstance(request.get("video_id"), str)
            or not re.fullmatch(r"[A-Za-z0-9_-]{11}", request["video_id"])):
        raise SystemExit("Use youtube_metadata and an 11-character video_id, not a URL")
    key = os.environ.get("FLASHDATA_API_KEY") or getpass.getpass("FlashData API key: ")
    if not key.strip():
        raise SystemExit("An API key is required")
    out.mkdir()
    (out / "request.json").write_bytes(body)
    (out / "requested-at.txt").write_text(
        datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), encoding="utf-8"
    )
    try:
        response = requests.post(
            "https://data.flashdata.dev/v1/queries/realtime",
            headers={"X-API-Key": key, "Content-Type": "application/json",
                     "Accept": "application/json"},
            data=body, timeout=120, allow_redirects=False,
        )
    except requests.RequestException:
        raise SystemExit(f"Request interrupted. Keep {out} and check History before retrying.")
    (out / "result.json").write_bytes(response.content)
    (out / "response-headers.txt").write_text(
        "\n".join(f"{k}: {v}" for k, v in response.headers.items()), encoding="utf-8"
    )
    (out / "http-status.txt").write_text(str(response.status_code), encoding="utf-8")
else:
    print(f"Reading saved response from {out}; no API call.")

if not (out / "http-status.txt").exists():
    raise SystemExit("Incomplete attempt. Keep the folder and check History before retrying.")
status = (out / "http-status.txt").read_text().strip()
if status != "200":
    raise SystemExit(f"HTTP {status}: inspect {out}/result.json and response-headers.txt")
try:
    data = json.loads((out / "result.json").read_bytes())
except ValueError:
    raise SystemExit("Invalid JSON; inspect the saved result.json")
request = json.loads((out / "request.json").read_bytes())
if not isinstance(data, dict) or data.get("source") != "youtube_metadata" or data.get("status") != "done":
    raise SystemExit("Metadata request did not finish successfully; inspect result.json")
videos = data.get("results")
if (not isinstance(videos, list) or len(videos) != 1 or not isinstance(videos[0], dict)
        or videos[0].get("videoId") != request["video_id"]):
    raise SystemExit("Expected one metadata object matching the requested video_id")
record = {
    "request": request,
    "requested_at": (out / "requested-at.txt").read_text().strip(),
    "usage": data.get("usage"), "result_file": "result.json",
}
for filename, value in (("video.json", videos[0]), ("record.json", record)):
    (out / filename).write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
print(f"Saved {videos[0]['videoId']} to {out}/video.json")
```

#### Uitvoeren van video-metadata/

```bash
python metadata.py snapshot-001
```


### Bash

#### Controleer uw gereedschap

```bash
curl --version
jq --version
```

#### video-metadata/metadata.sh

```bash
#!/usr/bin/env bash
set -euo pipefail
out="${1:?Usage: bash metadata.sh OUTPUT_FOLDER}"

if [[ ! -e "$out" ]]; then
  jq -e '.source == "youtube_metadata" and
    (.video_id | if type == "string" then length == 11 and test("^[A-Za-z0-9_-]{11}$")
     else false end)' request.json > /dev/null
  if [[ -z "${FLASHDATA_API_KEY:-}" ]]; then
    read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
    printf '\n'
  fi
  : "${FLASHDATA_API_KEY:?An API key is required}"
  mkdir -- "$out"
  cp request.json "$out/request.json"
  date -u +'%Y-%m-%dT%H:%M:%SZ' > "$out/requested-at.txt"
  curl --fail-with-body --silent --show-error --max-time 120 \
    --request POST 'https://data.flashdata.dev/v1/queries/realtime' \
    --header "X-API-Key: $FLASHDATA_API_KEY" \
    --header 'Content-Type: application/json' --header 'Accept: application/json' \
    --data-binary "@$out/request.json" \
    --dump-header "$out/response-headers.txt" --output "$out/result.json" \
    --write-out '%{http_code}' > "$out/http-status.txt" || {
      printf 'Request failed. Keep %s and inspect its saved files before retrying.\n' "$out" >&2
      exit 1
    }
else
  printf 'Reading saved response from %s; no API call.\n' "$out"
fi

if [[ ! -f "$out/http-status.txt" ]] || [[ "$(cat "$out/http-status.txt")" != 200 ]]; then
  printf 'Incomplete or failed attempt. Inspect the saved files and History before retrying.\n' >&2
  exit 1
fi
video=$(jq -e --slurpfile request "$out/request.json" '
  if .source != "youtube_metadata" or .status != "done"
  then error("Expected a successful youtube_metadata response") else . end
  | .results
  | if type != "array" then error("Expected a metadata array")
    elif length != 1 then error("Expected exactly one video") else .[0] end
  | if type != "object" then error("Expected a metadata object")
    elif .videoId != $request[0].video_id then error("Returned videoId does not match the request")
    else . end' "$out/result.json")
printf '%s\n' "$video" > "$out/video.json"
jq --slurpfile request "$out/request.json" \
  --arg requested_at "$(tr -d '\r\n' < "$out/requested-at.txt")" \
  '{request: $request[0], requested_at: $requested_at, usage, result_file: "result.json"}' \
  "$out/result.json" > "$out/record.json"
printf 'Saved %s to %s/video.json\n' "$(jq -r .videoId "$out/video.json")" "$out"
```

#### Uitvoeren van video-metadata/

```bash
bash metadata.sh snapshot-001
```



<a id="output"></a>

## 3. Lees het videorecord

Opgeslagen <video ID> naar snapshot-001/video.json. Lees dat bestand voor het volledige metadata object en record.json voor het exacte ingediende verzoek, requested_at en gebruik. Het lezen van deze bestanden maakt geen API oproep.

### Python

#### Lezen lokaal

```bash
python -m json.tool snapshot-001/video.json
python -m json.tool snapshot-001/record.json
```


### Bash

#### Lezen lokaal

```bash
cat snapshot-001/video.json
cat snapshot-001/record.json
```



<a id="expected"></a>

### Voorbeelduitvoer

Afgekort, illustratief video.json. Teruggegeven waarden variëren. Het script bewaart elk beschikbaar veld, inclusief null waarden, en houdt de volledige respons in result.json.

#### video-metadata/snapshot-001/video.json

```json
{
  "videoId": "FUfGcZ092b0",
  "title": "Example research video",
  "channel": "Example channel",
  "duration": 120,
  "viewCount": null,
  "transcriptLanguages": [
    "en"
  ]
}
```


<a id="fields"></a>

### Lees de velden

| Veld | Gebruik het voor |
| --- | --- |
| videoId | Het record is stabiel. Titel- en kanaalnamen kunnen veranderen. |
| duration | Videolengte in seconden. Bewaar ontbrekende of null-waarden als onbekend. |
| viewCount / likeCount / commentCount | Telt beschikbaar in deze snapshot. Null of ontbrekende is onbekend; nul is een gerapporteerde telling. |
| transcriptLanguages | Kandidaattaalcodes voor een afzonderlijk bijschriftverzoek. Deze lijst geeft niet aan of een track automatisch of handmatig is. |


<a id="reuse"></a>

## Hergebruik de snapshot of vraag een andere

Voer hetzelfde commando uit om video.json en record.json te herbouwen vanuit het opgeslagen antwoord. Er is geen sleutel of netwerkverzoek nodig. Het bewerken van de top-level request.json verandert de invoer die is opgeslagen met snapshot-001 niet.

### Python

#### Opgeslagen gegevens hergebruiken

```bash
python metadata.py snapshot-001
```


### Bash

#### Opgeslagen gegevens hergebruiken

```bash
bash metadata.sh snapshot-001
```


- [Resultaten opslaan en hergebruiken](https://flashdata.dev/nl/docs/guides/save-results/reference.md)

<a id="chapters"></a>

### Beschikbare hoofdstukken toevoegen

Om hoofdstukmarkeringen op te nemen, vervang request.json met deze versie en gebruik een nieuwe uitvoermap. include_chapters: true geeft hoofdstukken terug indien beschikbaar; het maakt ze niet aan. Zowel include_chapters als include_formats standaard naar true indien weggelaten.

#### video-metadata/request.json

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

#### Python

##### Nog een snapshot aanvragen

```bash
python metadata.py snapshot-002
```


#### Bash

##### Nog een snapshot aanvragen

```bash
bash metadata.sh snapshot-002
```


- [Metadatavelden en opties](https://flashdata.dev/nl/docs/sources/youtube_metadata/reference.md)

<a id="recover"></a>

## Als metadata niet beschikbaar zijn

| Wat is er gebeurd? | Wat je moet doen |
| --- | --- |
| Ongeldige video_id | Gebruik alleen het 11-karakter ID. De invoervalidatie stopt voordat het verzoek wordt verzonden. |
| Privé-, verwijderde of beperkte video | Houd de storing voor die ID. Controleer de bronfout en kies een toegankelijke video in plaats van herhaaldelijk hetzelfde item in te dienen. |
| Leeg resultaat of een andere videoId | Het script stopt zonder video.json te schrijven. Controleer het opgeslagen verzoek en antwoord voordat u de record gebruikt. |
| Ontbrekende nummers, hoofdstukken of talen | Een overeenkomstige metadata record kan nog steeds succesvol zijn. Bewaar niet-beschikbare velden als onbekend; vul ze niet met uitgevonden waarden. |
| 401 / 403 / 402 | Controleer de sleutel, youtube_metadata permissie en balans, respectievelijk, voordat een nieuwe poging. |
| 429 | Lees Retry-After in response-headers.txt en wacht. Het script wordt nooit automatisch opnieuw gebruikt. |
| Timeout, 5xx, ongeldige JSON of een onvolledige map | Houd de poging en controleer History alvorens opnieuw te verzenden. Het hergebruik van de map maakt geen nieuwe aanvraag. |

### Python

Bewaar inspect_metadata.py naast metadata.py, voer het dan uit.

#### video-metadata/inspect_metadata.py

```python
from pathlib import Path

for name in ("http-status.txt", "response-headers.txt", "result.json"):
    path = Path("snapshot-001") / name
    print(f"--- {name} ---")
    print(path.read_text(encoding="utf-8", errors="replace") if path.exists() else "Not saved")
```

#### Lokaal controleren

```bash
python inspect_metadata.py
```


### Bash

#### Lokaal controleren

```bash
for name in http-status.txt response-headers.txt result.json; do
  printf '\n--- %s ---\n' "$name"
  if [[ -f "snapshot-001/$name" ]]; then cat "snapshot-001/$name"; else printf 'Not saved\n'; fi
done
```


- [Geschiedenis aanvragen](https://flashdata.dev/app/jobs)
- [Fouten en statuscodes](https://flashdata.dev/nl/docs/errors/reference.md)

<a id="next"></a>

## Gebruik de video in je workflow

Gebruik videoId om deze record aan te sluiten bij uw zoekresultaten of dataset. Voor gesproken inhoud, haal een specifieke titel track volgende. Gebruik voor meerdere IDs de verrijkingsgids. Dit zijn afzonderlijke verzoeken met hun eigen permissies en kosten.

- [Tijdstempel bijschriften ophalen](https://flashdata.dev/nl/docs/guides/timestamped-captions-recipe/reference.md)
- [Verrijk geselecteerde video IDs](https://flashdata.dev/nl/docs/guides/enrich-youtube-videos/reference.md)
