Перейти до вмісту
UK
Отримати ключ API
Переглянути документацію

Довідник API

API обробки Bulk

Створіть і управляти файлами на основі YouTube, потім отримайте свої проявляються і результати.

На цій сторінці

Пісочниця API

Виберіть джерело та скопіюйте повну робочу лінію Python або Bash, єдиний запит або відповідь зразка. Код перегляду майданчика; не подає завдання. Повний робочий процес завантаження, перевірки стану та перерозподіл кожного результату.

Параметри джерела

Побудувати робочий потік Bulk

Місцеве ТБ UTF-8 файл, один YouTube ID в рядку, до 2 ГиБ. Вимоги до введення.

Розширені можливості медіа

Місцеположення

Завантажуйте програму завантажте за посиланням (YYYYYMMDDDD).

Додайте свої облікові дані для зберігання на сервері перед запуском коду. Вони потребують дозволу на завантаження файлів.

Вимоги до вимог та умов зберігання
Bulk вебхоокПовідомлення про реєстрацію та перевірку Manifest
POSThttps://api.flashdata.dev/v2/bulk-jobs
Python 3 · standard library
import gzip
import json
import os
from pathlib import Path
import random
import re
import shutil
import time
import urllib.error
import urllib.parse
import urllib.request

api_key = "YOUR_API_KEY"
api_url = "https://api.flashdata.dev/v2"
input_file = Path("video-ids.txt")
output_dir = Path("bulk-results")
bulk_id = ""  # Paste a saved Bulk ID to monitor/retrieve it without submitting again.
poll_timeout_seconds = 1800
payload = {
    "source": "youtube_download",
    "options": {
        "download_type": "audio_video",
        "video_quality": "<=720",
        "audio_language": "default",
        "upload_metadata": False,
        "output_format": "mp4",
        "storage": {
            "storage_type": "s3",
            "storage_url": "your-media-bucket",
            "access_key": "YOUR_ACCESS_KEY",
            "secret_key": "YOUR_SECRET_KEY",
            "region": "us-east-1",
        },
    },
}

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

opener = urllib.request.build_opener(NoRedirect())
os.umask(0o077)

def api(path, method="GET", body=None):
    data = None if body is None else json.dumps(body).encode("utf-8")
    headers = {"X-API-Key": api_key, "Content-Type": "application/json"}
    for attempt in range(5):
        try:
            request = urllib.request.Request(api_url + path, data=data, headers=headers, method=method)
            with opener.open(request, timeout=60) as response:
                return json.load(response)
        except urllib.error.HTTPError as error:
            if method != "GET" or error.code not in (429, 502, 503, 504) or attempt == 4:
                raise
            retry_after = error.headers.get("Retry-After", "")
            delay = min(120, int(retry_after)) if retry_after.isdigit() else 2 ** attempt
            time.sleep(delay + random.random())

def result_location(path):
    request = urllib.request.Request(api_url + path, headers={"X-API-Key": api_key})
    try:
        with opener.open(request, timeout=60):
            raise RuntimeError("Expected a 302 result redirect")
    except urllib.error.HTTPError as error:
        if error.code != 302:
            raise
        location = error.headers.get("Location", "")
    parsed = urllib.parse.urlsplit(location)
    if parsed.scheme != urllib.parse.urlsplit(api_url).scheme or not parsed.hostname or parsed.username or parsed.password:
        raise RuntimeError("Invalid signed storage URL")
    return location

if not bulk_id:
    if not input_file.is_file() or not 1 <= input_file.stat().st_size <= 2147483648:
        raise ValueError("Use a nonempty UTF-8 ID file up to 2 GiB")
    created = api("/bulk-jobs", "POST", payload)
    bulk_id = created["job"]["id"]
    if not re.fullmatch(r"bulk_[A-Za-z0-9_-]{8,}", bulk_id):
        raise RuntimeError("Invalid Bulk ID")
    work = output_dir / bulk_id
    work.mkdir(parents=True, exist_ok=True)
    (work / "created.json").write_text(json.dumps(created, indent=2))
    print("Saved Bulk ID:", bulk_id, flush=True)
    upload = created["upload"]
    upload_url = urllib.parse.urlsplit(upload["href"])
    if upload["method"] != "PUT" or upload_url.scheme != urllib.parse.urlsplit(api_url).scheme or not upload_url.hostname or upload_url.username or upload_url.password:
        raise RuntimeError("Invalid signed upload URL")
    with input_file.open("rb") as file:
        request = urllib.request.Request(upload["href"], data=file, method="PUT", headers={
            "Content-Type": upload["contentType"], "Content-Length": str(input_file.stat().st_size)
        })
        with opener.open(request, timeout=120) as response:
            response.read()
    api("/bulk-jobs/" + bulk_id + "/start", "POST")

if not re.fullmatch(r"bulk_[A-Za-z0-9_-]{8,}", bulk_id):
    raise ValueError("Invalid Bulk ID")
work = output_dir / bulk_id
work.mkdir(parents=True, exist_ok=True)
deadline = time.monotonic() + poll_timeout_seconds
while True:
    job = api("/bulk-jobs/" + bulk_id)["job"]
    (work / "status.json").write_text(json.dumps(job, indent=2))
    print(job["status"], job["input"], job["counts"], flush=True)
    if job["status"] == "completed":
        break
    if job["status"] in ("paused", "failed", "cancelled", "awaiting_upload"):
        raise RuntimeError(json.dumps({"id": bulk_id, "status": job["status"], "pauseReason": job.get("pauseReason"), "error": job.get("error")}))
    if time.monotonic() >= deadline:
        raise TimeoutError("Job still running. Set bulk_id to " + bulk_id + " and rerun to continue monitoring.")
    time.sleep(10 + random.random())

manifest_url = result_location("/bulk-jobs/" + bulk_id + "/results")
with opener.open(manifest_url, timeout=60) as response:  # No API key sent to storage.
    manifest = json.load(response)
(work / "manifest.json").write_text(json.dumps(manifest, indent=2))
for part in manifest["parts"]:
    number = part["number"]
    if type(number) is not int or number < 1:
        raise RuntimeError("Invalid part number")
    path = "/bulk-jobs/" + bulk_id + "/results/" + str(number)
    if part["href"] != api_url + path:
        raise RuntimeError("Unexpected part API URL")
    storage_url = result_location(path)
    compressed = work / ("part-" + str(number) + ".jsonl.gz")
    with opener.open(storage_url, timeout=120) as response, compressed.open("wb") as file:
        shutil.copyfileobj(response, file, 1024 * 1024)
    with compressed.open("rb") as file:
        gzipped = file.read(2) == b"\x1f\x8b"
    reader = gzip.open(compressed, "rb") if gzipped else compressed.open("rb")
    with reader, (work / ("part-" + str(number) + ".jsonl")).open("wb") as file:
        shutil.copyfileobj(reader, file, 1024 * 1024)
print("Saved manifest and decoded NDJSON parts in", work)
Створення, завантаження, початок, контроль і відновлення всіх частинавтентифікації X-API-Key

Напрямки

Всі кінцеві точки використовують https://api.flashdata.dev/v2. Створіть роботу → завантажте відео-ID файл → start → монітор → отримати проявляється і кожен результат частина.

МетодологіяДоляДія
POST/v2/bulk-jobsСтворити роботу Bulk
POST/v2/bulk-jobs/{bulkId}/startЗавантажити і почати
GET/v2/bulk-jobs/{bulkId}Отримати статус роботи
GET/v2/bulk-jobsСписок робочих місць
POST/v2/bulk-jobs/{bulkId}/pauseЗапобігти роботі
PATCH/v2/bulk-jobs/{bulkId}Оновити параметри роботи
POST/v2/bulk-jobs/{bulkId}/resumeОформити роботу
DELETE/v2/bulk-jobs/{bulkId}Скасувати роботу
GET/v2/bulk-jobs/{bulkId}/resultsОтримати результат проявляється
GET/v2/bulk-jobs/{bulkId}/results/{partNumber}Завантажити деталі результату

Ауттентифікація та введення

Встановіть FLASHDATA_API_KEY на ключ з доступом до вибраного джерела. Використовуйте той самий ключ і обліковий запис для створення, управління та результати. Обробка використовує баланс облікового запису та нормалізацію надр. YouTube Download вимагає доступу власника і options.storage.

Створіть робочу папку, яка названа сипучих/ і запустіть ці приклади з неї. Повний ігровий майданчик Python використовує стандартну бібліотеку Python 3.10+; індивідуальні приклади кінцевих точок Python нижче, ніж вимагають запитань; приклади cURL використовують Bash, cURL 7.76+, jq і gzip. Виберіть одну мову для кожної дії, так що ви не створюєте або починаєте дублікати роботи.

Вхід - UTF-8 файл з одним 11-character YouTube ID на лінію, до 2 GiB. Використовуйте IDs, не URLs. Видалити дублікати IDs перед завантаженням; повторний IDs обробляються окремо.

ДжерелоДодаткові параметри
youtube_metadatainclude_formats, include_chapters
youtube_transcriptмова, авто
youtube_captionsмова, авто
youtube_trainabilityНемає опцій
youtube_downloadПараметри та призначення носіїв
Python залежностей
python -m pip install requests

Створіть поля запиту

ПолеТипиЗакупи
sourcestringПотрібні. Підтримуваний джерело для кожного входу ID.
optionsobjectЗагальні параметри джерела. Джерела даних можуть встановлювати result_storage; YouTube Download вимагає зберігання.
callback_urlstringНеобов'язково громадський HTTPS зворотний дзвінок. Протипоказання після явної публікації.

Створити роботу Bulk

Створіть роботу, завантажте текстовий файл UTF-8 з одним 11-character YouTube відео ID на лінії upload.href, після чого зателефонуйте старт. Створення роботи самостійно не починається обробки.

Цей приклад пише video-ids.txt і зберігає надходження 201 до bulk-created.json. Зберігайте, що отримання приватного та повторного використання job.id для кожного пізнішого запиту. Створюючи робочі листи в awaiting_upload; завантаження URL закінчується після 15 хвилин.

Навігація
POST https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEY

Заощаджуйте bulk_create.py на сипучих та бокових bulk-created.json. Скопіюйте загальний скрипт, потім запустіть команду нижче.

bulk_create.py
import json
import os
from pathlib import Path

import requests

os.umask(0o077)
Path("video-ids.txt").write_bytes(b"jNQXAC9IVRw\ndQw4w9WgXcQ\n")
response = requests.post(
    "https://api.flashdata.dev/v2/bulk-jobs",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    json={"source": "youtube_metadata", "options": {"include_formats": False}},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
receipt = response.json()
Path("bulk-created.json").write_text(json.dumps(receipt, indent=2), encoding="utf-8")
print(json.dumps(receipt["job"], indent=2))
Запуск з сипучих/
python bulk_create.py

Відповіді та запит схема

HTTP статусЗручності
201Bulk створений з 15-хвилинним прямим завантаженням URL
401Ауттентифікація, обов'язкова або недійсна
422Заява про те, що не вдалося
503Необхідна залежність або каталог тимчасово недоступний
Тіло запиту
{
  "$ref": "#/components/schemas/CreateBulkJobRequest"
}
201 · application/json
{
  "$ref": "#/components/schemas/BulkJobCreated"
}

Завантажити і почати

Почати обробку завантаженого UTF-8 відео ID файл, до 2 GiB (2147483648 байтів). Зберігати файл, що змінюється після початку.

Перший PUT video-ids.txt до отримання upload.href з upload.contentType, без X-API-Key. Приклад викликів стартує тільки після того, як завантажити вдасться. Зберігайте завантажений файл, який не змінюється після

ПараметрМісцезнаходженняЗакупівля
bulkIdpathОбов’язково · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Навігація
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/start
X-API-Key: YOUR_API_KEY

Заощаджуйте bulk_start.py на сипучих та бокових bulk-created.json. Скопіюйте загальний скрипт, потім запустіть команду нижче.

bulk_start.py
import json
import os
from pathlib import Path

import requests

receipt = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))
upload = receipt["upload"]
if upload["method"] != "PUT" or not upload["href"].startswith("https://"):
    raise ValueError("Expected an HTTPS PUT upload URL")
# Stream the file to storage without the FlashData key.
with open("video-ids.txt", "rb") as file:
    response = requests.put(
        upload["href"], data=file,
        headers={"Content-Type": upload["contentType"]},
        timeout=300, allow_redirects=False,
    )
    response.raise_for_status()
    if not 200 <= response.status_code < 300:
        raise RuntimeError("Upload did not complete; do not start the job yet")

bulk_id = receipt["job"]["id"]
response = requests.post(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/start",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json()["job"], indent=2))
Запуск з сипучих/
python bulk_start.py

Відповіді

HTTP статусЗручності
200Bulk розпочато роботу або його поточний стан idempotent
401Ауттентифікація, обов'язкова або недійсна
404Ресурс не знайдено або не належить абоненту
409Конфлікт з питань ресурсного стану або відповідальності
422Заява про те, що не вдалося
503Необхідна залежність або каталог тимчасово недоступний
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Отримати статус роботи

Читати далі job.status, вхід, кількість, pauseReason і помилки. Зніміть те ж саме ID з затримкою; завершений засіб проявляється, не що кожна відео досягла успіху.

ПараметрМісцезнаходженняЗакупівля
bulkIdpathОбов’язково · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Навігація
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Заощаджуйте bulk_status.py на сипучих та бокових bulk-created.json. Скопіюйте загальний скрипт, потім запустіть команду нижче.

bulk_status.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.get(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
Path("bulk-job.json").write_text(json.dumps(response.json(), indent=2), encoding="utf-8")
print(json.dumps(response.json()["job"], indent=2))
Запуск з сипучих/
python bulk_status.py

Відповіді

HTTP статусЗручності
200Bulk стан роботи
401Ауттентифікація, обов'язкова або недійсна
404Ресурс не знайдено або не належить абоненту
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Список робочих місць

Відповідність містить дані та патологія. Пройдіть pagination.nextCursor як наступний параметр запиту, доки він є null. Використовуйте ліміт від 1 до 50; за замовчуванням 20.

ПараметрМісцезнаходженняЗакупівля
cursorqueryНеобов’язково · {"type":"string","maxLength":512}
limitqueryНеобов’язково · {"type":"integer","minimum":1,"maximum":50,"default":20}
Навігація
GET https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEY

Заощаджуйте list_bulk_jobs.py на сипучих та бокових bulk-created.json. Скопіюйте загальний скрипт, потім запустіть команду нижче.

list_bulk_jobs.py
import json
import os
from pathlib import Path

import requests

response = requests.get(
    "https://api.flashdata.dev/v2/bulk-jobs?limit=20",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Запуск з сипучих/
python list_bulk_jobs.py

Відповіді

HTTP статусЗручності
200Bulk робоча сторінка
401Ауттентифікація, обов'язкова або недійсна
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobPage"
}

Запобігти роботі

Застосувати нові надходження та кінцеву упаковку. Виконуючи робочі місця, що продовжуються з оригінальними налаштуваннями та зарядами. Зроби роботу при готовності.

ПараметрМісцезнаходженняЗакупівля
bulkIdpathОбов’язково · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Навігація
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/pause
X-API-Key: YOUR_API_KEY

Заощаджуйте pause_bulk_job.py на сипучих та бокових bulk-created.json. Скопіюйте загальний скрипт, потім запустіть команду нижче.

pause_bulk_job.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.post(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/pause",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Запуск з сипучих/
python pause_bulk_job.py

Відповіді

HTTP статусЗручності
200Використовуються об'ємні роботи або його поточний стан
401Ауттентифікація, обов'язкова або недійсна
404Ресурс не знайдено або не належить абоненту
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Оновити параметри роботи

Оновити параметри при очікуванні завантаження, або при пауті до всіх вхідних даних. Виконуючи робочі місця, зберігайте свої налаштування. Якщо паусінг ще триває, чекайте та переробляйте відповідь 409. Після того, як всі дані були прочитані, можна оновити лише дані доставки. Набір callback_url до null для видалення його.

Цей приклад видаляє зворотний дзвінок. Щоб змінити параметри джерела, надішлемо параметри об'єкта. Запобігти першому і чекати паузу, щоб прийняти ефект; 409 означає, що оновлення не можна застосувати ще. Ведуться роботи дитини зберігають свої оригінальні варіанти.

ПараметрМісцезнаходженняЗакупівля
bulkIdpathОбов’язково · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Навігація
PATCH https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Заощаджуйте update_bulk_job.py на сипучих та бокових bulk-created.json. Скопіюйте загальний скрипт, потім запустіть команду нижче.

update_bulk_job.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.patch(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    json={"callback_url": None},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Запуск з сипучих/
python update_bulk_job.py

Відповіді та запит схема

HTTP статусЗручності
200Оновлений загальний стан роботи
401Ауттентифікація, обов'язкова або недійсна
404Ресурс не знайдено або не належить абоненту
409Конфлікт з питань ресурсного стану або відповідальності
422Заява про те, що не вдалося
Тіло запиту
{
  "$ref": "#/components/schemas/UpdateBulkJobRequest"
}
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Оформити роботу

Виправлено pauseReason першим, таким як додавання кредитів або оновлення облікових даних зберігання, потім відновити те ж саме Bulk ID.

ПараметрМісцезнаходженняЗакупівля
bulkIdpathОбов’язково · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Навігація
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/resume
X-API-Key: YOUR_API_KEY

Заощаджуйте resume_bulk_job.py на сипучих та бокових bulk-created.json. Скопіюйте загальний скрипт, потім запустіть команду нижче.

resume_bulk_job.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.post(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/resume",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Запуск з сипучих/
python resume_bulk_job.py

Відповіді

HTTP статусЗручності
200Поточний стан роботи на сипучих роботах
401Ауттентифікація, обов'язкова або недійсна
404Ресурс не знайдено або не належить абоненту
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Скасувати роботу

Стоп нові подання. Забезпечити роботу ще finish і неточувати їх нормальними зарядами. Відмінна робота не публікує остаточний проміжок.

ПараметрМісцезнаходженняЗакупівля
bulkIdpathОбов’язково · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Навігація
DELETE https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Заощаджуйте cancel_bulk_job.py на сипучих та бокових bulk-created.json. Скопіюйте загальний скрипт, потім запустіть команду нижче.

cancel_bulk_job.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.delete(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Запуск з сипучих/
python cancel_bulk_job.py

Відповіді

HTTP статусЗручності
200Поточний стан роботи на сипучих роботах
401Ауттентифікація, обов'язкова або недійсна
404Ресурс не знайдено або не належить абоненту
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Отримати результат проявляється

Дотримуйтесь перенаправлення, щоб завантажити JSON проявляється і використовувати його посилання для отримання файлів результатів. Зареєструйтеся на зберігання URLs без ключа API. Доступні результати 24 годин після всього Bulk робота завершується.

Успішний запит API повертається 302 з головуванням розташування. Fetch, що HTTPS зберігання URL в окремому запиті без X-API-Key. Приклад зберігає manifest.json. 409 означає результати не готові; 410 означає, що вони закінчуються.

ПараметрМісцезнаходженняЗакупівля
bulkIdpathОбов’язково · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Навігація
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results
X-API-Key: YOUR_API_KEY

Заощаджуйте bulk_manifest.py на сипучих та бокових bulk-created.json. Скопіюйте загальний скрипт, потім запустіть команду нижче.

bulk_manifest.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.get(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/results",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 302:
    raise RuntimeError(f"Expected a manifest redirect, got {response.status_code}")
url = response.headers["Location"]
if not url.startswith("https://"):
    raise ValueError("Expected an HTTPS storage URL")

manifest = requests.get(url, timeout=120)  # No FlashData API key.
manifest.raise_for_status()
Path("manifest.json").write_text(json.dumps(manifest.json(), indent=2), encoding="utf-8")
print(json.dumps(manifest.json(), indent=2))
Запуск з сипучих/
python bulk_manifest.py

Відповіді

HTTP статусЗручності
200JSON проявляється після перенаправлення
302Перенаправлення на короткочасний приватний R2 URL; API не повинні бути переадресовані · Location
401Ауттентифікація, обов'язкова або недійсна
404Ресурс не знайдено або не належить абоненту
409Конфлікт з питань ресурсного стану або відповідальності
410Затриманий результат вибухнув
200 · application/json
{
  "type": "object",
  "additionalProperties": true
}

Завантажити деталі результату

Використовуйте кожен parts[].number від manifest.json. Кожна кінцева точка повертає 302 на Gzip NDJSON файл; скачати без ключа API, декомпресувати, потім записати один об'єкт JSON на рядок. Приєднатися до індексу нульової бази. Приклад отримує всі частини і зберігає як .ndjson.gz і .ndjson файли.

ПараметрМісцезнаходженняЗакупівля
bulkIdpathОбов’язково · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
partNumberpathОбов’язково · {"type":"integer","minimum":0}
Навігація
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results/{partNumber}
X-API-Key: YOUR_API_KEY

Заощаджуйте bulk_parts.py на сипучих та бокових bulk-created.json. Скопіюйте загальний скрипт, потім запустіть команду нижче.

bulk_parts.py
import json
import os
from pathlib import Path

import requests
import gzip
import shutil

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
manifest = json.loads(Path("manifest.json").read_text(encoding="utf-8"))
for part in manifest["parts"]:
    number = part["number"]
    response = requests.get(
        f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/results/{number}",
        headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
        timeout=30, allow_redirects=False,
    )
    response.raise_for_status()
    if response.status_code != 302:
        raise RuntimeError(f"Expected a part redirect, got {response.status_code}")
    url = response.headers["Location"]
    if not url.startswith("https://"):
        raise ValueError("Expected an HTTPS storage URL")

    # Save the original gzip bytes; do not decompress twice.
    with requests.get(url, stream=True, timeout=120) as download:
        download.raise_for_status()
        with open(f"part-{number}.ndjson.gz", "wb") as file:
            download.raw.decode_content = False
            shutil.copyfileobj(download.raw, file)
    with gzip.open(f"part-{number}.ndjson.gz", "rt", encoding="utf-8") as rows:
        with open(f"part-{number}.ndjson", "w", encoding="utf-8") as file:
            for line in rows:
                file.write(line)
                print(json.dumps(json.loads(line)))
Запуск з сипучих/
python bulk_parts.py

Відповіді

HTTP статусЗручності
200Gzip-compressed NDJSON скачати після перенаправлення
302Перенаправлення на короткочасний приватний R2 URL; API не повинні бути переадресовані · Location
401Ауттентифікація, обов'язкова або недійсна
404Ресурс не знайдено або не належить абоненту
409Конфлікт з питань ресурсного стану або відповідальності
410Затриманий результат вибухнув
200 · application/x-ndjson
{
  "type": "string"
}

Стани та затримка робочих місць

Доступні результати 24 годин після всього Bulk робота завершується. Збережіть їх до expiresAt. Медіа у Вашому пункті слідувати політиці збереження відро. Закінчена робота може включати не вдалося відео; counts.invalid записів відхилених вхідних ліній.

Державна державна адміністраціяПопередня дія
awaiting_uploadЗавантажте файл і зателефонуйте.
runningПоповнити те ж ID з відворотом; input.complete показує, чи закінчиться сканування.
pausedЧитать pauseReason, зафіксуйте його, потім відновіть.
finalizingОчікується на результат упаковки і проявляється публікація.
completedЗавантажити проявляється і кожна частина. Огляньте статус кожного рядка і похибку.
failed / cancelledПохибка і збережена держава. Не публікується остаточний проявляється.

Доставка сховищ

Використовуйте дитячий майданчик для налаштування провайдера та попереднього перегляду точну поля запиту. Принципи зберігання клієнтів, що належать до об'єкта, вибраного зберігання; X-API-Key автентизує тільки FlashData API запитів.

ДжерелоСтворити поле запитуДоставка
Метадані, трафарет, підписки, перевірка ліцензіїoptions.result_storageНеобов'язково. Copies NDJSON результат частини і проявляється до вашого відро.
youtube_downloadoptions.storageПотрібні. Виконує медіа на відро; result_storage і browser_delivery не приймаються.

Знайдіть завантажені файли

Дані проявляються письмовими останніми і списками ключових слів об'єкта, розмірів і SHA-256. Він відрізняється від прояви FlashData, який списує значення API. YYYYMMDDDD у доріжках даних використовує дату створення UTC Bulk; в медіа-стеженнях він використовує дату завантаження кожного відео UTC. Bulk Доставка даних OSS вимагає aliyuncs.com кінцева точка.

Приватні медіа file_url значення потребують вашого зберігання SDK або підписаного URL від цього провайдера. Ключ FlashData не надає доступу до відро. Необов'язкові файли метаданих, що зберігаються усередку носіїв. З'являються ретилії в delivery.retryCount.

Планування об'єкта даних
<prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz
<prefix>/<source>/<bulkId>/manifest.json

Отримувати вебхоок

Місце громадськості HTTPS callback_url поза варіантами. Bulk надсилається тільки після публікації проявляється; він відправляється не на відео події і не відмовляється від завершення події для невдалих або скасованих робочих місць. Зберігайте опитування стану як падлогу.

  1. Персист і deduplicate delivery_id, потім повертаємо 2xxx оперативно. Доставка восьмих разів з відключенням.
  2. Події не відмічаються. Збігти id і джерело до збереженого чека; перевірити, що завершено через автентичне управління API до отримання ретривалю. Ignore URLs від неперевершеного заходу.
Створіть запит з зворотним зв'язком
{
  "source": "youtube_metadata",
  "options": {
    "include_formats": false,
    "include_chapters": false
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
Проведення заходів · ілюстративний
{
  "delivery_id": "bulk-completion:bulk_EXAMPLE123",
  "id": "bulk_EXAMPLE123",
  "source": "youtube_metadata",
  "status": "completed",
  "links": [
    {
      "rel": "self",
      "href": "https://api.flashdata.dev/v2/bulk-jobs/bulk_EXAMPLE123",
      "method": "GET"
    },
    {
      "rel": "results",
      "href": "https://api.flashdata.dev/v2/bulk-jobs/bulk_EXAMPLE123/results",
      "method": "GET"
    }
  ]
}

Визначення стеми

BulkJobCreated

BulkJobCreated
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "job",
    "upload"
  ],
  "properties": {
    "job": {
      "$ref": "#/components/schemas/BulkJob"
    },
    "upload": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "href",
        "method",
        "expiresAt",
        "contentType"
      ],
      "properties": {
        "href": {
          "type": "string",
          "format": "uri"
        },
        "method": {
          "type": "string",
          "const": "PUT"
        },
        "expiresAt": {
          "type": "string",
          "format": "date-time"
        },
        "contentType": {
          "type": "string",
          "const": "text/plain; charset=utf-8"
        }
      }
    }
  }
}

BulkJob

BulkJob
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "source",
    "status",
    "input",
    "counts",
    "delivery",
    "pauseReason",
    "error",
    "createdAt",
    "startedAt",
    "completedAt",
    "expiresAt",
    "links"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^bulk_[A-Za-z0-9_-]{8,}$"
    },
    "source": {
      "type": "string",
      "enum": [
        "youtube_metadata",
        "youtube_transcript",
        "youtube_captions",
        "youtube_trainability",
        "youtube_download"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "awaiting_upload",
        "running",
        "paused",
        "finalizing",
        "completed",
        "failed",
        "cancelled"
      ]
    },
    "input": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "bytes",
        "complete",
        "scannedBytes",
        "scannedLines"
      ],
      "properties": {
        "bytes": {
          "type": "integer",
          "minimum": 0
        },
        "complete": {
          "type": "boolean"
        },
        "scannedBytes": {
          "type": "integer",
          "minimum": 0
        },
        "scannedLines": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "counts": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "accepted",
        "completed",
        "failed",
        "invalid",
        "results"
      ],
      "properties": {
        "accepted": {
          "type": "integer",
          "minimum": 0
        },
        "completed": {
          "type": "integer",
          "minimum": 0
        },
        "failed": {
          "type": "integer",
          "minimum": 0
        },
        "invalid": {
          "type": "integer",
          "minimum": 0
        },
        "results": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "pauseReason": {
      "type": [
        "string",
        "null"
      ]
    },
    "delivery": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "customerStorage",
        "storageType",
        "uploadedParts",
        "retryCount"
      ],
      "properties": {
        "customerStorage": {
          "type": "boolean"
        },
        "storageType": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "s3",
            "s3_compatible",
            "oss",
            "gcs",
            "azure",
            "cos",
            "bos",
            "tos",
            null
          ]
        },
        "uploadedParts": {
          "type": "integer",
          "minimum": 0
        },
        "retryCount": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "error": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "code",
            "detail"
          ],
          "properties": {
            "code": {
              "type": "string"
            },
            "detail": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        }
      ]
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "startedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "completedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "expiresAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "links": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/JobLink"
      }
    }
  }
}

BulkJobPage

BulkJobPage
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/BulkJob"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  }
}

BulkJobResponse

BulkJobResponse
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "job"
  ],
  "properties": {
    "job": {
      "$ref": "#/components/schemas/BulkJob"
    }
  }
}

CreateBulkJobRequest

CreateBulkJobRequest
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "source"
  ],
  "properties": {
    "source": {
      "type": "string",
      "enum": [
        "youtube_metadata",
        "youtube_transcript",
        "youtube_captions",
        "youtube_trainability",
        "youtube_download"
      ]
    },
    "options": {
      "type": "object",
      "additionalProperties": true,
      "description": "Reused for every ID. Metadata accepts include_formats and include_chapters. Transcript and captions accept language (one code or an array of 1–10 distinct codes) and auto (applies to all requested languages). Omit language to prefer en-orig, fall back to en, and return one track. With auto=true, each requested code tries its -orig track first, then the plain code. Explicit -orig codes and auto=false stay exact. languageCode identifies the selected track; requestedLanguageCode is included when it differs from the requested code. A language array returns tracks and per-language errors for each video with at least one retrieved track. If no track is retrieved, the video job fails and its reserved credits are refunded. Bulk exports use one JSONL record per video. Trainability accepts no source options. These four data sources optionally accept result_storage. Supported storage_type values are s3, s3_compatible, oss, gcs, azure, cos, bos, and tos. storage_url is the bucket name (Azure container name); object_prefix is optional. S3, S3-compatible, OSS, COS, BOS, and TOS use access_key and secret_key. S3-compatible and OSS also require a public HTTPS endpoint_url. COS, BOS, and TOS require region and use fixed provider endpoints. COS bucket names include the APPID. BOS S3-compatible HTTPS delivery supports bj, su, and hkg. GCS requires service_account with project_id, client_email, and private_key. Azure requires account_name and a container SAS sas_token with write permission. Default object_prefix is YYYYMMDD, frozen to the UTC bulk creation date. Files are written to <prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz; manifest.json in the same bulk directory is written last. Each JSONL row includes its input index and completed, failed, or invalid status. Internal R2 results remain available through the result links for 24 hours. Download accepts the normal YouTube download parameters, requires customer storage, and does not permit browser_delivery. Download storage supports the same eight provider types and credential shapes listed above under the storage field. Download storage may include object_prefix; YYYYMMDD tokens resolve to the UTC upload date, while literal prefixes are unchanged."
    },
    "callback_url": {
      "type": "string",
      "format": "uri",
      "maxLength": 2048,
      "description": "Optional public HTTPS endpoint notified once after manifest publication."
    }
  }
}

JobLink

JobLink
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "rel",
    "href",
    "method"
  ],
  "properties": {
    "rel": {
      "type": "string",
      "enum": [
        "self",
        "results",
        "content",
        "download"
      ]
    },
    "href": {
      "type": "string",
      "format": "uri"
    },
    "method": {
      "type": "string",
      "const": "GET"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "filename": {
      "type": "string"
    },
    "content_type": {
      "type": "string"
    },
    "size_bytes": {
      "type": "integer",
      "minimum": 1
    }
  }
}

Pagination

Pagination
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "hasMore",
    "limit"
  ],
  "properties": {
    "nextCursor": {
      "type": [
        "string",
        "null"
      ]
    },
    "previousCursor": {
      "type": [
        "string",
        "null"
      ]
    },
    "hasMore": {
      "type": "boolean"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}

Problem

Problem
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "type",
    "title",
    "status",
    "code",
    "requestId"
  ],
  "properties": {
    "type": {
      "type": "string",
      "format": "uri-reference"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer",
      "minimum": 400,
      "maximum": 599
    },
    "code": {
      "type": "string",
      "pattern": "^[a-z0-9_]+$"
    },
    "detail": {
      "type": "string"
    },
    "requestId": {
      "type": "string",
      "pattern": "^req_"
    },
    "fieldErrors": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/FieldError"
      }
    }
  }
}

FieldError

FieldError
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "field",
    "code",
    "message"
  ],
  "properties": {
    "field": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}

UpdateBulkJobRequest

UpdateBulkJobRequest
{
  "type": "object",
  "additionalProperties": false,
  "minProperties": 1,
  "properties": {
    "options": {
      "type": "object",
      "additionalProperties": true,
      "description": "Partial option update. Nested storage fields are merged so unchanged credentials do not need to be resent. Data result_storage fields are merged the same way. After all IDs have been scanned, a paused data bulk job accepts credential updates only: access_key and secret_key, GCS service_account, or Azure sas_token, depending on the storage type. The complete merged configuration is validated before it is stored."
    },
    "callback_url": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri",
      "maxLength": 2048,
      "description": "Replacement completion callback, or null to remove the callback."
    }
  }
}