Przejdź do treści
PL
Uzyskaj klucz API
Przeglądaj dokumentację

Dokumentacja API

API przetwarzania Bulk

Tworzenie i kontrola zadań opartych na plikach YouTube, a następnie pobieranie ich manifestów i części wyników.

Na tej stronie

Plac testowy API

Wybierz źródło i skopiuj kompletny strumień pracy Python lub Bash, pojedyncze żądanie lub odpowiedź próbki. Plac zabaw przedstawia kod; nie przedstawia pracy. Kompletne przepływy pracy obsługują wysyłanie, sprawdzanie stanu i pobieranie każdej części wyników.

Parametry źródłowe

Zbuduj przepływ pracy Bulk

Lokalny plik UTF-8, jeden YouTube ID na linię, do 2 GiB. Wymogi dotyczące wejścia.

Wyniki

Zostaw to, aby uzyskać wyniki za pośrednictwem FlashData API.

Hak WWW Uzupełniający BulkPowiadomienie o zakończeniu procedury i weryfikacja
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_trainability",
    "options": {},
}

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)
Tworzenie, wysyłanie, uruchamianie, monitorowanie i odzyskiwanie wszystkich częściUwierzytelnianie X-API-Key

Punkty końcowe

Wszystkie punkty końcowe stosowania https://api.flashdata.dev/v2. Utwórz zadanie → wysyłaj plik wideo-ID → start → monitor → pobrać manifest i każdą część wyniku.

MetodaŚcieżkaDziałanie
POST/v2/bulk-jobsUtwórz zadanie Bulk
POST/v2/bulk-jobs/{bulkId}/startWyślij i uruchom
GET/v2/bulk-jobs/{bulkId}Uzyskaj status pracy
GET/v2/bulk-jobsLista miejsc pracy
POST/v2/bulk-jobs/{bulkId}/pauseWstrzymać pracę
PATCH/v2/bulk-jobs/{bulkId}Aktualizacja opcji pracy
POST/v2/bulk-jobs/{bulkId}/resumeWznowienie pracy
DELETE/v2/bulk-jobs/{bulkId}Anuluj pracę
GET/v2/bulk-jobs/{bulkId}/resultsUzyskaj manifest wyników
GET/v2/bulk-jobs/{bulkId}/results/{partNumber}Pobieranie części wyników

Uwierzytelnianie i wprowadzanie

Ustaw FLASHDATA_API_KEY na klucz z dostępem do wybranego źródła. Ponowne wykorzystanie tego samego klucza i rozliczenie tworzenia, kontroli i wyników. Przetwarzanie wykorzystuje saldo konta i normalne ceny per-source. YouTube Download wymaga dostępu właściciela i options.storage.

Utwórz folder roboczy o nazwie bulk- api / i uruchom z niego te przykłady. Kompletny obieg pracy Python wykorzystuje standardową bibliotekę Python 3.10 +; poszczególne przykłady punktów końcowych Python poniżej wymagają zapytania; przykłady cURL wykorzystują Bash, cURL 7.76 +, jq i gzip. Wybierz jeden język dla każdej akcji, aby nie tworzyć lub rozpocząć duplikat pracy.

Input to plik UTF-8 z jednym znakiem 11- YouTube ID na linię, do 2 GiB. Należy stosować IDs, a nie URLs. Przed wysłaniem należy usunąć duplikat IDs; powtarzalne IDs są przetwarzane oddzielnie.

ŹródłoWspólne opcje
youtube_metadatainclude_formats, include_chapters
youtube_transcriptlanguage, auto
youtube_captionslanguage, auto
youtube_trainabilityBrak opcji
youtube_downloadOpcje medialne i cel przechowywania
Zależność Python
python -m pip install requests

Utwórz pola żądania

PoleRodzajStosowanie
sourcestringWymagane. Jedno obsługiwane źródło dla każdego wejścia ID.
optionsobjectOpcje wspólnego źródła. Źródła danych mogą ustawiać result_storage; YouTube Download wymaga przechowywania.
callback_urlstringFakultatywne publiczne wywołanie zakończenia HTTPS. Wysłany po jawnej publikacji.

Utwórz zadanie Bulk

Utwórz zadanie, wgraj plik tekstowy UTF-8 z jednym znakiem 11- YouTube wideo ID na linię do upload.href, a następnie wywołaj start. Sama praca nie zaczyna się przetwarzać.

Przykład ten zapisuje video-ids.txt i zapisuje paragon 201 na bulk-created.json. Zachowaj ten paragon w tajemnicy i ponownie użyj job.id na każde późniejsze żądanie. Tworzenie zadania pozostawia go w awaiting_upload; wysyłanie URL wygasa po 15 minut.

Punkt końcowy
POST https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEY

Zapisz bulk_create.py w bulk- api / obok bulk-created.json. Skopiuj kompletny skrypt, a następnie uruchom polecenie poniżej.

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))
Uruchom z bulk- api /
python bulk_create.py

Odpowiedzi i schematy zapytań

Status HTTPZnaczenie
201Zadania Bulk utworzone z bezpośrednim wysyłaniem 15- minute URL
401Wymagane uwierzytelnienie lub nieprawidłowe
422Wniosek o zatwierdzenie nie powiódł się
503Wymagane uzależnienie lub katalog jest tymczasowo niedostępny
Treść żądania
{
  "$ref": "#/components/schemas/CreateBulkJobRequest"
}
201 · application/json
{
  "$ref": "#/components/schemas/BulkJobCreated"
}

Wyślij i uruchom

Zacznij przetwarzanie przesłanego pliku UTF-8 wideo ID, aż do 2 GiB (bajty 2147483648). Po uruchomieniu pliku plik nie uległ zmianie.

Pierwszy PUT video-ids.txt do odbioru upload.href z upload.contentType, bez X-API-Key. Przykład wywołania rozpoczyna się dopiero po zakończeniu wysyłania. Następnie należy zachować niezmieniony plik.

ParametrLokalizacjaWymóg
bulkIdpathWymagane · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Punkt końcowy
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/start
X-API-Key: YOUR_API_KEY

Zapisz bulk_start.py w bulk- api / obok bulk-created.json. Skopiuj kompletny skrypt, a następnie uruchom polecenie poniżej.

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))
Uruchom z bulk- api /
python bulk_start.py

Odpowiedzi

Status HTTPZnaczenie
200Rozpoczęto pracę Bulk lub jego obecny stan idemstrong
401Wymagane uwierzytelnienie lub nieprawidłowe
404Zasoby nieznalezione lub niebędące własnością osoby dzwoniącej
409Stan zasobów lub konflikt idempotencji
422Wniosek o zatwierdzenie nie powiódł się
503Wymagane uzależnienie lub katalog jest tymczasowo niedostępny
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Uzyskaj status pracy

Przeczytaj job.status, wejście, liczenie, pauseReason i błąd. Recheck ten sam ID z opóźnieniem; ukończone oznacza, że manifest jest publikowany, nie, że każdy film się powiódł.

ParametrLokalizacjaWymóg
bulkIdpathWymagane · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Punkt końcowy
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Zapisz bulk_status.py w bulk- api / obok bulk-created.json. Skopiuj kompletny skrypt, a następnie uruchom polecenie poniżej.

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))
Uruchom z bulk- api /
python bulk_status.py

Odpowiedzi

Status HTTPZnaczenie
200Stan pracy Bulk
401Wymagane uwierzytelnienie lub nieprawidłowe
404Zasoby nieznalezione lub niebędące własnością osoby dzwoniącej
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Lista miejsc pracy

Reakcja zawiera dane i stronniczość. Podaj pagination.nextCursor jako parametr zapytania kursora następnej prośby do czasu, aż będzie to null. Użyj limitu od 1 do 50; domyślną wartością jest 20.

ParametrLokalizacjaWymóg
cursorqueryOpcjonalne · {"type":"string","maxLength":512}
limitqueryOpcjonalne · {"type":"integer","minimum":1,"maximum":50,"default":20}
Punkt końcowy
GET https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEY

Zapisz list_bulk_jobs.py w bulk- api / obok bulk-created.json. Skopiuj kompletny skrypt, a następnie uruchom polecenie poniżej.

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))
Uruchom z bulk- api /
python list_bulk_jobs.py

Odpowiedzi

Status HTTPZnaczenie
200Strona zadań Bulk
401Wymagane uwierzytelnienie lub nieprawidłowe
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobPage"
}

Wstrzymać pracę

Wstrzymać nowe zgłoszenia i opakowanie. Istniejące miejsca pracy nadal z ich pierwotnych ustawień i opłat. Wznowić pracę, kiedy będzie gotowa.

ParametrLokalizacjaWymóg
bulkIdpathWymagane · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Punkt końcowy
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/pause
X-API-Key: YOUR_API_KEY

Zapisz pause_bulk_job.py w bulk- api / obok bulk-created.json. Skopiuj kompletny skrypt, a następnie uruchom polecenie poniżej.

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))
Uruchom z bulk- api /
python pause_bulk_job.py

Odpowiedzi

Status HTTPZnaczenie
200Paused mass job or its current idemstrong state
401Wymagane uwierzytelnienie lub nieprawidłowe
404Zasoby nieznalezione lub niebędące własnością osoby dzwoniącej
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Aktualizacja opcji pracy

Aktualizuj opcje w oczekiwaniu na wysłanie, lub podczas pauzy zanim wszystkie dane wejściowe zostaną przeczytane. Istniejące miejsca pracy zachowują swoje ustawienia. Jeśli pauza jest w trakcie, czekaj i powtórz odpowiedź 409. Po przeczytaniu wszystkich danych wejściowych można aktualizować jedynie dane uwierzytelniające dostawy. Ustaw callback_url na null, aby go usunąć.

Ten przykład usuwa wywołanie zakończenia. Aby zmienić opcje źródłowe, wyślij obiekt opcji zamiast tego. Zatrzymać się najpierw i czekać, aż przerwa stanie się skuteczna; 409 oznacza, że aktualizacja nie może być jeszcze zastosowana. Istniejące prace dzieci zachowują swoje oryginalne opcje.

ParametrLokalizacjaWymóg
bulkIdpathWymagane · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Punkt końcowy
PATCH https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Zapisz update_bulk_job.py w bulk- api / obok bulk-created.json. Skopiuj kompletny skrypt, a następnie uruchom polecenie poniżej.

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))
Uruchom z bulk- api /
python update_bulk_job.py

Odpowiedzi i schematy zapytań

Status HTTPZnaczenie
200Zaktualizowany stan pracy masowej
401Wymagane uwierzytelnienie lub nieprawidłowe
404Zasoby nieznalezione lub niebędące własnością osoby dzwoniącej
409Stan zasobów lub konflikt idempotencji
422Wniosek o zatwierdzenie nie powiódł się
Treść żądania
{
  "$ref": "#/components/schemas/UpdateBulkJobRequest"
}
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Wznowienie pracy

Napraw najpierw pauseReason, np. dodając punkty lub aktualizując dane dotyczące pamięci masowej, a następnie wznawiaj ten sam Bulk ID.

ParametrLokalizacjaWymóg
bulkIdpathWymagane · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Punkt końcowy
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/resume
X-API-Key: YOUR_API_KEY

Zapisz resume_bulk_job.py w bulk- api / obok bulk-created.json. Skopiuj kompletny skrypt, a następnie uruchom polecenie poniżej.

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))
Uruchom z bulk- api /
python resume_bulk_job.py

Odpowiedzi

Status HTTPZnaczenie
200Bieżący stan pracy masowej
401Wymagane uwierzytelnienie lub nieprawidłowe
404Zasoby nieznalezione lub niebędące własnością osoby dzwoniącej
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Anuluj pracę

Przerwać nowe oświadczenia. Istniejące miejsca pracy mogą nadal podlegać standardowym opłatom finish. Anulowana praca nie publikuje ostatecznego manifestu.

ParametrLokalizacjaWymóg
bulkIdpathWymagane · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Punkt końcowy
DELETE https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Zapisz cancel_bulk_job.py w bulk- api / obok bulk-created.json. Skopiuj kompletny skrypt, a następnie uruchom polecenie poniżej.

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))
Uruchom z bulk- api /
python cancel_bulk_job.py

Odpowiedzi

Status HTTPZnaczenie
200Bieżący stan pracy masowej
401Wymagane uwierzytelnienie lub nieprawidłowe
404Zasoby nieznalezione lub niebędące własnością osoby dzwoniącej
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Uzyskaj manifest wyników

Postępuj zgodnie z redirect, aby pobrać manifest JSON i użyj jego linków do pobierania plików wyników. Pobierz podpisane przechowywanie URLs bez klucza API. Wyniki pozostają dostępne dla 24 godziny po zakończeniu całego zadania Bulk.

Potwierdzone żądanie API zwraca 302 nagłówkiem Lokalizacji. Pobierz, że HTTPS pamięci URL w odrębnym wniosku bez X-API-Key. Przykład zapisuje manifest.json. 409 oznacza, że wyniki nie są gotowe; 410 oznacza, że wygasły.

ParametrLokalizacjaWymóg
bulkIdpathWymagane · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Punkt końcowy
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results
X-API-Key: YOUR_API_KEY

Zapisz bulk_manifest.py w bulk- api / obok bulk-created.json. Skopiuj kompletny skrypt, a następnie uruchom polecenie poniżej.

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))
Uruchom z bulk- api /
python bulk_manifest.py

Odpowiedzi

Status HTTPZnaczenie
200JSON manifest pobrany po przekierowaniu
302Przekierowanie na krótkożyciowy prywatny R2 URL; Nie wolno przekazywać uwierzytelniania API · Location
401Wymagane uwierzytelnienie lub nieprawidłowe
404Zasoby nieznalezione lub niebędące własnością osoby dzwoniącej
409Stan zasobów lub konflikt idempotencji
410Wynik zatrzymany wygasł
200 · application/json
{
  "type": "object",
  "additionalProperties": true
}

Pobieranie części wyników

Każdy parts[].number należy używać z manifest.json. Każdy punkt końcowy zwraca 302 do pliku gzip NDJSON; należy pobrać bez klucza API, dekompresji, a następnie przetworzyć jeden obiekt JSON na linię. Dołącz do indeksu zerowego. Przykład pobiera wszystkie części i przechowuje pliki .ndjson.gz i .ndjson.

ParametrLokalizacjaWymóg
bulkIdpathWymagane · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
partNumberpathWymagane · {"type":"integer","minimum":0}
Punkt końcowy
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results/{partNumber}
X-API-Key: YOUR_API_KEY

Zapisz bulk_parts.py w bulk- api / obok bulk-created.json. Skopiuj kompletny skrypt, a następnie uruchom polecenie poniżej.

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)))
Uruchom z bulk- api /
python bulk_parts.py

Odpowiedzi

Status HTTPZnaczenie
200Gzip- sprężony NDJSON pobrany po przekierowaniu
302Przekierowanie na krótkożyciowy prywatny R2 URL; Nie wolno przekazywać uwierzytelniania API · Location
401Wymagane uwierzytelnienie lub nieprawidłowe
404Zasoby nieznalezione lub niebędące własnością osoby dzwoniącej
409Stan zasobów lub konflikt idempotencji
410Wynik zatrzymany wygasł
200 · application/x-ndjson
{
  "type": "string"
}

Państwa pracy i utrzymanie

Wyniki pozostają dostępne dla 24 godziny po zakończeniu całego zadania Bulk. Zapisz je przed expiresAt. Media w Twoim miejscu przeznaczenia przestrzegają zasad zachowania Twojego wiadra. Ukończone zadanie może obejmować nieudane filmy; counts.invalid zapisuje odrzucone linie wejściowe.

PaństwoNastępna akcja
awaiting_uploadWyślij plik i wywołaj start.
runningID z backoff; input.complete pokazuje, czy skanowanie zakończone.
pausedPrzeczytaj pauseReason, napraw go, a następnie wznowij.
finalizingPoczekać na wyniki pakowania i jawnej publikacji.
completedŚciągnij manifest i każdą jego część. Sprawdź stan i błąd każdego wiersza.
failed / cancelledSprawdź błąd i stan zapisany. Nie opublikowano żadnego ostatecznego manifestu.

Dostawa magazynowa

Użyj placu zabaw, aby skonfigurować dostawcę i podgląd dokładnych pól żądania. Dane uwierzytelniające dla klienta znajdują się w wybranym obiekcie; X-API-Key uwierzytelnia tylko żądania FlashData API.

ŹródłoUtwórz pole żądaniaDostawa
Metadane, transkrypcja, podpisy, kontrola licencjioptions.result_storageOpcjonalnie. Kopiuje części wyników NDJSON i manifest do wiadra.
youtube_downloadoptions.storageWymagane. Dostarczanie mediów do wiadra; result_storage i browser_delivery nie są akceptowane.

Znajdź dostarczone pliki

manifest danych jest zapisany jako ostatni i zawiera listę kluczy obiektów, rozmiarów oraz sumy kontrolne SHA- 256. Różni się od manifestu FlashData, który zawiera listę wartości href API. RRRRMMDD w ścieżkach danych używa daty tworzenia UTC Bulk; w ścieżkach mediów używa daty przesyłania każdego wideo UTC. Dostarczanie danych Bulk OSS wymaga uzyskania punktu końcowego aliyuncs.com.

Wartości file_url dla mediów prywatnych wymagają przechowywania SDK lub podpisanego URL od tego dostawcy. Klawisz FlashData nie zapewnia dostępu do wiadra. Opcjonalne pliki towarzyszące metadanych są przechowywane obok mediów. W delivery.retryCount pojawiają się powtórki dostawy.

Układ obiektu danych
<prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz
<prefix>/<source>/<bulkId>/manifest.json

Otrzymuj hak dopełniający

Umieść publiczne opcje HTTPS callback_url na zewnątrz. Bulk wysyła zakończony dopiero po opublikowaniu manifestu; nie wysyła żadnych zdarzeń per- wideo i nie kończy dla nieudanych lub anulowanych zadań. Utrzymuj status sondażu jako zapas.

  1. Persist i odduplikować delivery_id, a następnie zwrócić 2xx natychmiast. Dostawa ponownie próbuje do ośmiu razy z wycofaniem.
  2. Wydarzenia nie są podpisane. Dopasuj id i źródło do zapisanego paragonu; weryfikuj ukończone za pomocą uwierzytelnionego zarządzania API przed kolejką wyszukiwania. Ignoruj URLs z niezweryfikowanego zdarzenia.
Utwórz żądanie za pomocą połączenia zwrotnego
{
  "source": "youtube_metadata",
  "options": {
    "include_formats": false,
    "include_chapters": false
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
Impreza integracyjna · ilustracja
{
  "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"
    }
  ]
}

Definicje schematów

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."
    }
  }
}