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

Примеры

Загрузите видео в ваше хранилище

Доставьте один MP4 в корзину Amazon S3, затем извлеките и проверьте файл с помощью Python или Bash.

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

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

Используйте доступ владельца с разрешения youtube_download и доступные кредиты. Загрузка не включена в пробный доступ временного агента. Вам нужно существующее ведро Amazon S3 и видео, которое вы можете загрузить.

Выберите Python 3.10+ с запросами и boto3, или Bash с cURL, jq, OpenSSL и AWS CLI v2. В Windows используйте Git Bash для версии Bash.

ПолномочияИспользуется для
FLASHDATA_API_KEYОтправьте работу и получите ее статус и запись о доставке.
FLASHDATA_STORAGE_ACCESS_KEY / FLASHDATA_STORAGE_SECRET_KEYИдентификатор загрузки S3, отправленный в FlashData для записи в выбранное вами ведро и префикс.
Ваш локальный профиль AWS или рольПрочитайте частный объект с помощью boto3 или AWS CLI в шаге 4. Требуется s3:GetObject.

1. Выберите видео и пункт назначения

Создайте приватную папку для загрузки видео вне вашего репозитория. Сохраните request.json там и откройте терминал в этой папке. Замените storage_url на имя ведра и регион на регион AWS; используйте видео 11-символ ID.

Этот рецепт обеспечивает видео с аудио как MP4, до 720p, под recipes/clip-001/.. Держите ведро в секрете. Используйте свежий префикс для отдельной загрузки, чтобы другая работа не могла переписать путь этого объекта.

download-video/request.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",
      "region": "us-east-1",
      "object_prefix": "recipes/clip-001"
    }
  }
}

2. Скачать One download job

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

Новая папка Job-001 отправляет один запрос на асинхронизацию. Он сохраняет запрос без загрузки учетных данных, метки времени, ответа HTTP и задания ID. Повторное использование этой папки останавливает отправку; это не создает вторую работу.

Установка в среде Python
python -m pip install requests boto3
download-video/submit.py
# Save as download-video/submit.py.
import getpass
import json
import os
import re
import sys
from datetime import datetime, timezone
from pathlib import Path

import requests

ROOT = Path(__file__).resolve().parent


def read_json(path):
    return json.loads(path.read_text(encoding="utf-8-sig"))


def secret(name):
    value = os.environ.get(name) or getpass.getpass(name + ": ")
    if not value.strip():
        raise ValueError("Missing " + name)
    return value


def main():
    os.umask(0o077)
    folder = sys.argv[1]
    if not re.fullmatch(r"[A-Za-z0-9_-]+", folder):
        raise ValueError("Use a simple output folder name, such as job-001.")
    directory = ROOT / folder
    if directory.exists():
        raise ValueError("Keep this attempt. Run collect.py with the same folder.")
    request = read_json(ROOT / "request.json")
    storage = request["params"]["storage"]
    if (request["source"] != "youtube_download"
            or not re.fullmatch(r"[A-Za-z0-9_-]{11}", request["video_id"])
            or request["params"]["download_type"] != "audio_video"
            or request["params"]["output_format"] != "mp4"
            or storage["storage_type"] != "s3"
            or set(storage) != {"storage_type", "storage_url", "region", "object_prefix"}
            or not re.fullmatch(r"[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]", storage["storage_url"])
            or not re.fullmatch(r"[a-z0-9-]+", storage["region"])
            or not re.fullmatch(r"[A-Za-z0-9_-]+(/[A-Za-z0-9_-]+)*", storage["object_prefix"])):
        raise ValueError("Check the video, MP4 options and Amazon S3 destination.")
    key = secret("FLASHDATA_API_KEY")
    access = secret("FLASHDATA_STORAGE_ACCESS_KEY")
    secret_key = secret("FLASHDATA_STORAGE_SECRET_KEY")
    directory.mkdir(mode=0o700)
    # Save the plan BEFORE sending. Keep upload credentials out of this file.
    (directory / "request.json").write_text(json.dumps(request, indent=2), encoding="utf-8")
    (directory / "submitted-at.txt").write_text(
        datetime.now(timezone.utc).isoformat(), encoding="utf-8")
    storage.update(access_key=access, secret_key=secret_key)
    response = requests.post(
        "https://data.flashdata.dev/v1/queries", json=request,
        headers={"X-API-Key": key, "Accept": "application/json"},
        timeout=(10, 120), allow_redirects=False)
    (directory / "submission.json").write_bytes(response.content)
    (directory / "submission-headers.txt").write_text(
        "\n".join(f"{k}: {v}" for k, v in response.headers.items()), encoding="utf-8")
    (directory / "submission-http.txt").write_text(str(response.status_code))
    if response.status_code not in (200, 201, 202):
        raise ValueError(f"HTTP {response.status_code}. Inspect the saved attempt.")
    receipt = response.json()
    if (receipt.get("source") != "youtube_download"
            or not re.fullmatch(r"[A-Za-z0-9_-]+", receipt.get("id", ""))):
        raise ValueError("Missing job ID. Check History before submitting again.")
    print("Submitted:", receipt["id"], "— keep", directory)


if __name__ == "__main__":
    try:
        main()
    except (IndexError, KeyError, OSError, ValueError, requests.RequestException) as error:
        print("Network request failed. Keep this attempt and inspect its saved files."
              if isinstance(error, requests.RequestException) else str(error), file=sys.stderr)
        sys.exit(1)
Запуск с download-video/
python submit.py job-001

Ожидаемое получение

Успех печатает: job_... и сохраняет submission.json. Квитанция подтверждает, что работа была принята; это не завершенная доставка или окончательная плата.

job-001/submission.json · сокращенно
{
  "id": "job_example",
  "source": "youtube_download",
  "status": "pending",
  "usage": {
    "credits": 0
  }
}

3. Дождитесь доставки и сохраните свой рекорд

Сохраните collect.py рядом с submit.py или collect.sh рядом с submit.sh. Работайте с той же папкой Job-001. Один раз проверяйте сохраненную работу. Для ожидания или обработки подождите секунды 10 и снова запустите ту же команду.

После завершения он сохраняет delivery.json. Подписанное перенаправление здесь извлекает запись доставки JSON, а не MP4; сценарий следует за ней без пересылки ключа FlashData. Сохраненный delivery.json повторно используется без другого запроса API.

download-video/collect.py
# Save as download-video/collect.py, beside submit.py.
import os
import re
import sys
from urllib.parse import urlsplit

import requests
from submit import ROOT, read_json, secret


def main():
    os.umask(0o077)
    folder = sys.argv[1]
    if not re.fullmatch(r"[A-Za-z0-9_-]+", folder):
        raise ValueError("Use the saved output folder name.")
    directory = ROOT / folder
    if (directory / "delivery.json").exists():
        print("Already saved:", directory / "delivery.json")
        return
    receipt = read_json(directory / "submission.json")
    job_id = receipt["id"]
    if receipt["source"] != "youtube_download" or not re.fullmatch(r"[A-Za-z0-9_-]+", job_id):
        raise ValueError("Inspect submission.json before continuing.")
    headers = {"X-API-Key": secret("FLASHDATA_API_KEY"), "Accept": "application/json"}
    url = "https://api.flashdata.dev/v2/jobs/" + job_id

    def get(url, name, headers):
        response = requests.get(url, headers=headers, timeout=(10, 120), allow_redirects=False)
        (directory / name).write_bytes(response.content)
        (directory / (name + ".headers")).write_text(
            "\n".join(f"{k}: {v}" for k, v in response.headers.items()), encoding="utf-8")
        (directory / (name + ".http")).write_text(str(response.status_code))
        return response

    status = get(url, "job-status.json", headers)
    if status.status_code != 200:
        raise ValueError(f"HTTP {status.status_code}. Inspect job-status.json and its headers.")
    job = status.json()["job"]
    if job["id"] != job_id or job["source"] != "youtube_download":
        raise ValueError("The job does not match the saved receipt.")
    if job["status"] in ("pending", "processing"):
        print(job["status"] + ". Wait 10 seconds, then run this command again.")
        return
    if job["status"] != "completed":
        raise ValueError("Job " + job["status"] + ". Inspect job-status.json; do not resubmit.")
    result = get(url + "/results", "delivery.pending.json", headers)
    if result.status_code == 302:
        location = result.headers.get("Location", "")
        parsed = urlsplit(location)
        if parsed.scheme != "https" or not parsed.hostname or parsed.username or parsed.password:
            raise ValueError("Expected an HTTPS result URL.")
        # This URL retrieves the JSON delivery record, not the video.
        # Never forward the FlashData key to the signed storage URL.
        result = get(location, "delivery.pending.json", {})
    if result.status_code != 200:
        raise ValueError(f"HTTP {result.status_code}. Run collect.py again after resolving it.")
    delivery = result.json()
    if (delivery.get("source") != "youtube_download" or delivery.get("status") != "done"
            or not isinstance(delivery.get("results"), list) or len(delivery["results"]) != 1):
        raise ValueError("Inspect delivery.pending.json before using the result.")
    (directory / "delivery.pending.json").replace(directory / "delivery.json")
    print("Saved:", directory / "delivery.json")
    print("Usage:", delivery.get("usage"))


if __name__ == "__main__":
    try:
        main()
    except (IndexError, KeyError, OSError, ValueError, requests.RequestException) as error:
        print("Network request failed. Keep this attempt and inspect its saved files."
              if isinstance(error, requests.RequestException) else str(error), file=sys.stderr)
        sys.exit(1)
Проверить сохраненную работу
python collect.py job-001

Что такое delivery.json

Результат включает в себя file_url, file_size в байтах и md5. Сохраняйте полный рекорд. Файл URL именует ваш объект S3; он не делает частное ведро общедоступным.

job-001/delivery.json · иллюстративные поля
{
  "source": "youtube_download",
  "status": "done",
  "results": [
    {
      "file_url": "https://your-media-bucket.s3.us-east-1.amazonaws.com/recipes/clip-001/jNQXAC9IVRw.mp4",
      "file_size": 1048576,
      "md5": "0123456789abcdef0123456789abcdef"
    }
  ]
}

4. Прочитайте частный объект и проверьте его

Сохранить сценарий проверки рядом с другими сценариями. Используйте настроенную локальную идентификацию AWS с доступом к объекту чтения. Сценарий проверяет, что доставка принадлежит запланированному ведру S3, префиксу и имени видеофайла, после чего загружает его в media.mp4.part.

Только подходящее количество байтов и MD5 производят media.mp4 и verified.json. Запуск проверки снова проверяет существующий media.mp4 локально. Этот шаг считывает ваш объект S3; он не отправляет другую загрузку FlashData.

download-video/verify.py
# Save as download-video/verify.py, beside submit.py.
import hashlib
import json
import os
import re
import sys
from contextlib import closing
from datetime import datetime, timezone
from urllib.parse import urlsplit

import boto3
from submit import ROOT, read_json


def main():
    os.umask(0o077)
    folder = sys.argv[1]
    if not re.fullmatch(r"[A-Za-z0-9_-]+", folder):
        raise ValueError("Use the saved output folder name.")
    directory = ROOT / folder
    request = read_json(directory / "request.json")
    receipt = read_json(directory / "submission.json")
    job = read_json(directory / "job-status.json")["job"]
    delivery = read_json(directory / "delivery.json")
    if (request["source"] != "youtube_download" or receipt["source"] != "youtube_download"
            or job["id"] != receipt["id"] or job["source"] != "youtube_download"
            or job["status"] != "completed" or delivery.get("source") != "youtube_download"
            or delivery.get("status") != "done" or len(delivery["results"]) != 1):
        raise ValueError("Check the saved request, receipt, status and delivery.")
    storage = request["params"]["storage"]
    bucket, region, prefix = (storage[k] for k in ("storage_url", "region", "object_prefix"))
    file = delivery["results"][0]
    parsed = urlsplit(file["file_url"])
    # This recipe uses an ASCII prefix and the MP4 filename generated for the video.
    object_key = prefix + "/" + request["video_id"] + ".mp4"
    if (storage["storage_type"] != "s3" or parsed.scheme != "https"
            or parsed.netloc != bucket + ".s3." + region + ".amazonaws.com"
            or parsed.path != "/" + object_key or parsed.query or parsed.fragment
            or type(file.get("file_size")) is not int or file["file_size"] <= 0
            or not re.fullmatch(r"[A-Fa-f0-9]{32}", file.get("md5", ""))):
        raise ValueError("Delivery URL, byte count or MD5 does not match this recipe's request.")
    local = directory / "media.mp4"
    pending = directory / "media.mp4.part"
    if not local.exists():
        # Boto3 uses your local AWS read identity, not the upload key sent to FlashData.
        with pending.open("xb") as output:
            s3 = boto3.client("s3", region_name=region)
            with closing(s3.get_object(Bucket=bucket, Key=object_key)["Body"]) as stream:
                while chunk := stream.read(1024 * 1024):
                    output.write(chunk)
        local = pending
    size, digest = 0, hashlib.md5(usedforsecurity=False)
    with local.open("rb") as stream:
        while chunk := stream.read(1024 * 1024):
            size += len(chunk)
            digest.update(chunk)
    if size != file["file_size"] or digest.hexdigest() != file["md5"].lower():
        raise ValueError("Size or MD5 mismatch. Keep the local file for inspection.")
    final = directory / "media.mp4"
    if local == pending:
        pending.rename(final)
    record = {
        "job_id": receipt["id"], "video_id": request["video_id"],
        "bucket": bucket, "object_key": object_key, "bytes": size, "md5": digest.hexdigest(),
        "verified_at": datetime.now(timezone.utc).isoformat(), "usage": delivery.get("usage"),
    }
    (directory / "verified.json").write_text(json.dumps(record, indent=2), encoding="utf-8")
    print("Verified:", final, "—", size, "bytes; MD5 matches.")


if __name__ == "__main__":
    try:
        main()
    except Exception as error:
        print(str(error), file=sys.stderr)
        sys.exit(1)
Проверить сохраненную доставку
python verify.py job-001

Успешный результат

Количество байтов выше является иллюстративным. Теперь у вас есть MP4 в ведре, проверенная локальная копия и verified.json, связывающий файл с его работой ID, видео ID, ключ объекта, контрольная сумма и отчет об использовании.

Терминал
Verified: .../job-001/media.mp4 — 1048576 bytes; MD5 matches.

Резюме без второй загрузки

Что случилось?Следующее действие
Отсроченная подача или отсутствие работы ID были сохраненыДержите вакансию-001 и проверяйте History с помощью метки времени и видео. Не удаляйте папку, чтобы заставить другую заявку. Восстановите оригинальную работу, прежде чем решить, нужен ли новый запрос.
Отсрочка/обработкаПодождите секунды 10, затем повторите сбор с помощью работы-001. Он читает только текущую работу.
Работа провалиласьПроверьте job-status.json на наличие ошибки. Исправьте конфигурацию видео или хранилища, прежде чем явно начинать новую работу в новой папке и префиксе.
401 / 403 / 402 / 429Проверьте ключ, разрешение или баланс. Для 429 прочитайте Retry-After в сохраненных заголовках и подождите. Сценарии не автоматически повторяют представление.
Получение результата не удалось или его подписанный URL истек.Повторно собрать для работы-001, чтобы запросить существующий результат снова.
S3 AccessDeniedИсправьте локальную политику AWS считывания идентичности или ведра. Доступ к загрузке FlashData и доступ к локальному чтению являются отдельными.
Частичный файл, неправильный путь, количество байтов или MD5Сохраните сохраненную доставку и файл для проверки. Для свежего чтения S3 после устранения причины отведите media.mp4.part в сторону, а затем повторите проверку. Не возвращайся.