Перейти к содержимому
RU
Ключ API
Обзор документации

Примеры

Восстановление метаданных одного видео

Превратите видео YouTube ID в сохраненную запись его названия, канала, продолжительности и доступных подсчетов. Сохраняйте первоначальный ответ и использование вместе с ним.

На этой странице

Прежде чем начать

Используйте ключ с разрешением youtube_metadata и доступными кредитами. Выберите Python 3.10+ с запросами или Bash с cURL 7.76+ и jq. В Windows используйте Git Bash для версии Bash.

1. Выберите одно видео

Создайте папку видео-метаданные и сохраните там request.json. Откройте терминал в этой папке. Замените video_id на 11-символ ID из часов URL или YouTube Search; не пропустите полный URL.

Установите оба факультативных флага явно: этот первый запрос опускает медиа-форматы и главы. Он извлекает метаданные без загрузки видео или его подписей.

video-metadata/request.json
{
  "source": "youtube_metadata",
  "video_id": "FUfGcZ092b0",
  "params": {
    "include_formats": false,
    "include_chapters": false
  }
}

2. Получить и сохранить метаданные

Выберите одну версию и сохраните ее сценарий рядом с request.json. Он считывает FLASHDATA_API_KEY или запрашивает ваш ключ в скрытом запросе. Агенты должны загрузить эту переменную из своего секретного магазина.

Запустите с помощью snapshot-001 в качестве выходной папки. Новая папка отправляет один запрос метаданных и сохраняет его заявленное использование. Сценарий проверяет успешность ответа, содержащего ровно одно видео с запрошенным ID перед написанием video.json.

Установка в среде Python
python -m pip install requests
video-metadata/metadata.py
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")
Бег от видео-метаданные/
python metadata.py snapshot-001

3. Прочитайте видеозапись

Успешные принты Saved <video ID> в snapshot-001/video.json. Прочитайте этот файл для полного объекта метаданных и record.json для точного отправленного запроса, requested_at и использования. Чтение этих файлов не вызывает API.

Читать локально
python -m json.tool snapshot-001/video.json
python -m json.tool snapshot-001/record.json

Примерный выход

Сокращенно, иллюстративно video.json. Возвращаемые значения различаются. Скрипт сохраняет все доступные поля, включая значения null, и сохраняет полный ответ в result.json.

video-metadata/snapshot-001/video.json
{
  "videoId": "FUfGcZ092b0",
  "title": "Example research video",
  "channel": "Example channel",
  "duration": 120,
  "viewCount": null,
  "transcriptLanguages": [
    "en"
  ]
}

Читать поля

ПолеИспользуйте его для
videoIdСтабильный ключ к рекорду. Имена заголовков и каналов могут меняться.
durationДлина видео в секундах. Сохранить отсутствующие или null значения как неизвестные.
viewCount / likeCount / commentCountГрафики доступны в этом снимке. Нулевой или отсутствующий неизвестен; ноль - это число, о котором сообщают.
transcriptLanguagesЯзыковые коды кандидатов для отдельного запроса подписи. Этот список не определяет, является ли трек автоматическим или ручным.

Повторно использовать снимок или запросить другой

Запустите ту же команду, чтобы восстановить video.json и record.json из сохраненного ответа. Ключевой или сетевой запрос не требуется. Редактирование request.json верхнего уровня не изменяет вход, сохраненный с помощью snapshot-001.

Использовать сохраненные данные
python metadata.py snapshot-001

Включите доступные главы

Чтобы включить маркеры глав, замените request.json этой версией и используйте новую папку вывода. include_chapters: true возвращает главы, когда они доступны; он не создает их. Как include_chapters, так и include_formats по умолчанию не соответствуют true при опущении.

video-metadata/request.json
{
  "source": "youtube_metadata",
  "video_id": "FUfGcZ092b0",
  "params": {
    "include_formats": false,
    "include_chapters": true
  }
}
Запросить еще один снимок
python metadata.py snapshot-002

Если метаданные недоступны

Что случилось?Что делать
Инвалидный video_idИспользуйте только символ 11 ID. Проверка ввода прекращается перед отправкой запроса.
Частное, удаленное или ограниченное видеоСохраните неудачу для этого ID. Проверьте ошибку источника и выберите доступное видео вместо того, чтобы повторно отправлять один и тот же элемент.
Пустой результат или другой videoIdСценарий заканчивается без написания video.json. Проверьте сохраненный запрос и ответ перед использованием записи.
Недостающие счета, главы или языкиСоответствующая запись метаданных может быть успешной. Сохраняйте недоступные поля как неизвестные, не наполняйте их выдуманными значениями.
401 / 403 / 402Проверьте ключ, разрешение youtube_metadata и баланс, соответственно, перед новой попыткой.
429Читайте Retry-After в response-headers.txt и ждите. Сценарий никогда не перезаписывается автоматически.
Тайм-аут, 5xx, недействительный JSON или неполная папкаСохраните попытку и проверьте History, прежде чем отправлять снова. Повторное использование папки не делает нового запроса.

Сохраните inspect_metadata.py рядом с metadata.py, затем запустите его.

video-metadata/inspect_metadata.py
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")
Проверить локально
python inspect_metadata.py

Используйте видео в своем рабочем процессе

Используйте videoId, чтобы присоединиться к этой записи в результатах поиска или наборе данных. Для разговорного контента, добавьте определенный трек подписи. Для нескольких IDs используйте руководство по обогащению. Это отдельные запросы с их собственными разрешениями и сборами.