Überspringen zum Inhalt
DE
API-Schlüssel
Dokumentation durchsuchen

API-Referenz

API für Bulk-Verarbeitung

Erstellen und Steuern von dateibasierten YouTube-Jobs, und rufen Sie dann deren Manifeste und Ergebnisteile ab.

Auf dieser Seite

API-Playground

Wählen Sie eine Quelle aus und kopieren Sie einen vollständigen Python- oder Bash-Workflow, eine einzelne Anforderung oder eine Beispielantwort. Der Spielplatz zeigt Code an; es wird kein Job eingereicht. Komplette Workflows behandeln Upload, Statusüberprüfungen und Abruf jedes Ergebnisteils.

Quellenparameter

Erstellen Sie einen Bulk Workflow

Lokale UTF-8-Datei, eine YouTube ID pro Zeile, bis 2 GiB. Anforderungen an die Eingabe.

Ergebnislieferung

Lassen Sie dies aus, um Ergebnisse über den FlashData API abzurufen.

Bulk Vervollständigung WebhookManifestierungsmitteilung und Prüfung
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)
Erstellen, Hochladen, Starten, Überwachen und Abrufen aller TeileX-API-Key-Authentifizierung

Endpunkte

Alle Endpunkte verwenden https://api.flashdata.dev/v2. Erstellen Sie einen Job → Laden Sie eine Video-ID-Datei hoch → Starten → Monitor → Holen Sie das Manifest und jeden Ergebnisteil ab.

MethodeWegstreckeAktion
POST/v2/bulk-jobsErstellen Sie einen Bulk-Job
POST/v2/bulk-jobs/{bulkId}/startHochladen und Starten
GET/v2/bulk-jobs/{bulkId}Erhalten Sie den Jobstatus
GET/v2/bulk-jobsListe der Arbeitsplätze
POST/v2/bulk-jobs/{bulkId}/pauseEinen Job unterbrechen
PATCH/v2/bulk-jobs/{bulkId}Aktualisieren von Job-Optionen
POST/v2/bulk-jobs/{bulkId}/resumeWiederaufnahme eines Arbeitsplatzes
DELETE/v2/bulk-jobs/{bulkId}Einen Job stornieren
GET/v2/bulk-jobs/{bulkId}/resultsHolen Sie sich das Ergebnis manifest
GET/v2/bulk-jobs/{bulkId}/results/{partNumber}Download Ergebnisteile

Authentifizierung und Eingabe

Setzen Sie FLASHDATA_API_KEY auf einen Schlüssel mit Zugriff auf die ausgewählte Quelle. Verwenden Sie den gleichen Schlüssel und Konto für die Erstellung, Kontrollen und Ergebnisse. Die Verarbeitung verwendet den Kontostand und die normale Preisgestaltung pro Quelle. YouTube Download erfordert Besitzerzugriff und options.storage.

Erstellen Sie einen Arbeitsordner mit dem Namen bulk-api/ und führen Sie diese Beispiele aus. Der komplette Python Workflow des Spielplatzes verwendet die Python 3.10+ Standardbibliothek; die einzelnen Python Endpunktbeispiele unten erfordern Requests; cURL Beispiele verwenden Bash, cURL 7.76+, jq und gzip. Wählen Sie für jede Aktion eine Sprache aus, damit Sie keine doppelte Arbeit erstellen oder starten.

Input ist eine UTF-8-Datei mit einem 11-Zeichen YouTube ID pro Zeile, bis 2 GiB. Verwenden Sie IDs, nicht URLs. Entfernen Sie doppelte IDs vor dem Hochladen; wiederholte IDs werden separat verarbeitet.

QuelleGemeinsame Optionen
youtube_metadatainclude_formats, include_chapters
youtube_transcriptSprache, Auto
youtube_captionsSprache, Auto
youtube_trainabilityKeine Optionen
youtube_downloadMedienoptionen und Speicherziel
Python Abhängigkeit
python -m pip install requests

Anforderungsfelder erstellen

FeldTypNutzung
sourcestringerforderlich. Eine unterstützte Quelle für jeden Eingang ID.
optionsobjectShared Source Optionen. Datenquellen können result_storage einstellen; YouTube Download benötigt Speicher.
callback_urlstringOptionaler öffentlicher HTTPS-Abschluss Callback. Gesendet nach manifester Veröffentlichung.

Erstellen Sie einen Bulk-Job

Erstellen Sie einen Job, laden Sie eine UTF-8-Textdatei mit einem 11-Zeichen YouTube-Video ID pro Zeile in upload.href hoch und rufen Sie dann den Start an. Das Erstellen des Jobs allein beginnt nicht mit der Verarbeitung.

Dieses Beispiel schreibt video-ids.txt und speichert den 201-Beleg in bulk-created.json. Bewahren Sie diese Quittung privat auf und verwenden Sie job.id für jede spätere Anfrage wieder. Das Erstellen eines Jobs lässt ihn in awaiting_upload; der Upload URL läuft nach 15 Minuten ab.

Endpunkt
POST https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEY

Speichern Sie bulk_create.py in Bulk-Api / neben bulk-created.json. Kopieren Sie das komplette Skript und führen Sie dann den Befehl darunter aus.

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))
Lauf von Bulk-Api/
python bulk_create.py

Antworten und Anforderungsschema

HTTP-StatusBedeutung
201Bulk-Auftrag erstellt mit einem 15-Minuten-Direkt-Upload URL
401Authentifizierung erforderlich oder ungültig
422Antragsvalidierung fehlgeschlagen
503Eine erforderliche Abhängigkeit oder ein Katalog ist vorübergehend nicht verfügbar
Anfrageinhalt
{
  "$ref": "#/components/schemas/CreateBulkJobRequest"
}
201 · application/json
{
  "$ref": "#/components/schemas/BulkJobCreated"
}

Hochladen und Starten

Beginnen Sie mit der Verarbeitung der hochgeladenen UTF-8-Video-ID-Datei bis zu 2 GiB (2147483648-Bytes). Behalten Sie die Datei nach dem Start unverändert.

Erstes PUT video-ids.txt zum upload.href der Quittung mit upload.contentType, ohne X-API-Key. Die Beispielaufrufe starten erst, nachdem der Upload erfolgreich ist. Halten Sie die hochgeladene Datei danach unverändert.

ParameterStandortAnforderungen
bulkIdpathErforderlich · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Endpunkt
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/start
X-API-Key: YOUR_API_KEY

Speichern Sie bulk_start.py in Bulk-Api / neben bulk-created.json. Kopieren Sie das komplette Skript und führen Sie dann den Befehl darunter aus.

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))
Lauf von Bulk-Api/
python bulk_start.py

Antworten

HTTP-StatusBedeutung
200Bulk-Job gestartet oder sein aktueller idempotenter Zustand
401Authentifizierung erforderlich oder ungültig
404Ressource nicht gefunden oder nicht im besitz des anrufers.
409Ressourcenzustand oder Idempotenzkonflikt
422Antragsvalidierung fehlgeschlagen
503Eine erforderliche Abhängigkeit oder ein Katalog ist vorübergehend nicht verfügbar
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Erhalten Sie den Jobstatus

Lesen Sie job.status, Input, Counts, pauseReason und Error. Überprüfen Sie das gleiche ID mit einer Verzögerung; abgeschlossen bedeutet, dass das Manifest veröffentlicht wird, nicht dass jedes Video erfolgreich war.

ParameterStandortAnforderungen
bulkIdpathErforderlich · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Endpunkt
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Speichern Sie bulk_status.py in Bulk-Api / neben bulk-created.json. Kopieren Sie das komplette Skript und führen Sie dann den Befehl darunter aus.

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))
Lauf von Bulk-Api/
python bulk_status.py

Antworten

HTTP-StatusBedeutung
200Bulk Jobstatus
401Authentifizierung erforderlich oder ungültig
404Ressource nicht gefunden oder nicht im besitz des anrufers.
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Liste der Arbeitsplätze

Die Antwort enthält Daten und Paginierung. Geben Sie pagination.nextCursor als Cursorabfrageparameter der nächsten Anforderung weiter, bis es null ist. Verwenden Sie Limit von 1 zu 50; der Standard ist 20.

ParameterStandortAnforderungen
cursorqueryOptional · {"type":"string","maxLength":512}
limitqueryOptional · {"type":"integer","minimum":1,"maximum":50,"default":20}
Endpunkt
GET https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEY

Speichern Sie list_bulk_jobs.py in Bulk-Api / neben bulk-created.json. Kopieren Sie das komplette Skript und führen Sie dann den Befehl darunter aus.

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))
Lauf von Bulk-Api/
python list_bulk_jobs.py

Antworten

HTTP-StatusBedeutung
200Bulk Jobseite
401Authentifizierung erforderlich oder ungültig
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobPage"
}

Einen Job unterbrechen

Unterbrechen Sie neue Einsendungen und Ergebnisverpackung. Bestehende Jobs setzen sich mit ihren ursprünglichen Einstellungen und Gebühren fort. Nehmen Sie den Job wieder auf, wenn Sie bereit sind.

ParameterStandortAnforderungen
bulkIdpathErforderlich · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Endpunkt
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/pause
X-API-Key: YOUR_API_KEY

Speichern Sie pause_bulk_job.py in Bulk-Api / neben bulk-created.json. Kopieren Sie das komplette Skript und führen Sie dann den Befehl darunter aus.

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))
Lauf von Bulk-Api/
python pause_bulk_job.py

Antworten

HTTP-StatusBedeutung
200Unterbrochener Bulk Job oder sein aktueller idempotenter Zustand
401Authentifizierung erforderlich oder ungültig
404Ressource nicht gefunden oder nicht im besitz des anrufers.
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Aktualisieren von Job-Optionen

Aktualisieren Sie die Optionen, während Sie auf den Upload warten, oder während Sie angehalten werden, bevor alle Eingaben gelesen wurden. Bestehende Jobs behalten ihre Einstellungen. Wenn das Pausieren noch im Gange ist, warten und wiederholen Sie eine 409 Antwort. Nachdem alle Eingaben gelesen wurden, können nur die Lieferberechtigungen aktualisiert werden. Setzen Sie callback_url auf null, um es zu entfernen.

Dieses Beispiel entfernt den Abschluss-Callback. Um Quelloptionen zu ändern, senden Sie stattdessen ein Optionsobjekt. Halten Sie zuerst an und warten Sie, bis die Pause wirksam wird; ein 409 bedeutet, dass das Update noch nicht angewendet werden kann. Bestehende Kinderjobs behalten ihre ursprünglichen Optionen.

ParameterStandortAnforderungen
bulkIdpathErforderlich · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Endpunkt
PATCH https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Speichern Sie update_bulk_job.py in Bulk-Api / neben bulk-created.json. Kopieren Sie das komplette Skript und führen Sie dann den Befehl darunter aus.

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))
Lauf von Bulk-Api/
python update_bulk_job.py

Antworten und Anforderungsschema

HTTP-StatusBedeutung
200Aktualisierter Bulk-Job-Status
401Authentifizierung erforderlich oder ungültig
404Ressource nicht gefunden oder nicht im besitz des anrufers.
409Ressourcenzustand oder Idempotenzkonflikt
422Antragsvalidierung fehlgeschlagen
Anfrageinhalt
{
  "$ref": "#/components/schemas/UpdateBulkJobRequest"
}
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Wiederaufnahme eines Arbeitsplatzes

Beheben Sie zuerst pauseReason, z. B. Hinzufügen von Credits oder Aktualisieren von Speicheranmeldeinformationen, und nehmen Sie dann dasselbe Bulk ID wieder auf.

ParameterStandortAnforderungen
bulkIdpathErforderlich · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Endpunkt
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/resume
X-API-Key: YOUR_API_KEY

Speichern Sie resume_bulk_job.py in Bulk-Api / neben bulk-created.json. Kopieren Sie das komplette Skript und führen Sie dann den Befehl darunter aus.

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))
Lauf von Bulk-Api/
python resume_bulk_job.py

Antworten

HTTP-StatusBedeutung
200Aktueller Massenarbeitsplatz
401Authentifizierung erforderlich oder ungültig
404Ressource nicht gefunden oder nicht im besitz des anrufers.
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Einen Job stornieren

Stoppen Sie neue Einreichungen. Bestehende Jobs können immer noch finish und entstehen ihre normalen Gebühren. Ein stornierter Job veröffentlicht kein endgültiges Manifest.

ParameterStandortAnforderungen
bulkIdpathErforderlich · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Endpunkt
DELETE https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Speichern Sie cancel_bulk_job.py in Bulk-Api / neben bulk-created.json. Kopieren Sie das komplette Skript und führen Sie dann den Befehl darunter aus.

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))
Lauf von Bulk-Api/
python cancel_bulk_job.py

Antworten

HTTP-StatusBedeutung
200Aktueller Massenarbeitsplatz
401Authentifizierung erforderlich oder ungültig
404Ressource nicht gefunden oder nicht im besitz des anrufers.
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Holen Sie sich das Ergebnis manifest

Folgen Sie der Umleitung, um das JSON-Manifest herunterzuladen und seine Links zu verwenden, um Ergebnisdateien abzurufen. Holen Sie sich signierten Speicher URLs ohne Ihren API-Schlüssel. Die Ergebnisse bleiben für 24 Stunden nach Abschluss des gesamten Bulk-Auftrags verfügbar.

Die authentifizierte API-Anforderung gibt 302 mit einem Location-Header zurück. Holen Sie diesen HTTPS-Speicher URL in einer separaten Anforderung ohne X-API-Key ab. Das Beispiel speichert manifest.json. Ein 409 bedeutet, dass die Ergebnisse nicht bereit sind; 410 bedeutet, dass sie abgelaufen sind.

ParameterStandortAnforderungen
bulkIdpathErforderlich · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Endpunkt
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results
X-API-Key: YOUR_API_KEY

Speichern Sie bulk_manifest.py in Bulk-Api / neben bulk-created.json. Kopieren Sie das komplette Skript und führen Sie dann den Befehl darunter aus.

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))
Lauf von Bulk-Api/
python bulk_manifest.py

Antworten

HTTP-StatusBedeutung
200JSON Manifest heruntergeladen, nachdem Sie die Weiterleitung
302Weiterleitung zu einem kurzlebigen privaten R2 URL; API-Anmeldeinformationen dürfen nicht weitergeleitet werden · Location
401Authentifizierung erforderlich oder ungültig
404Ressource nicht gefunden oder nicht im besitz des anrufers.
409Ressourcenzustand oder Idempotenzkonflikt
410Das behaltene Ergebnis ist abgelaufen
200 · application/json
{
  "type": "object",
  "additionalProperties": true
}

Download Ergebnisteile

Verwenden Sie jedes parts[].number aus manifest.json. Jeder Endpunkt gibt eine 302 in eine gzip NDJSON-Datei zurück; Download ohne den API-Schlüssel, Dekomprimierung und dann ein JSON-Objekt pro Zeile. Verbinden Sie sich mit dem Null-basierten Index. Das Beispiel ruft alle Teile ab und behält sowohl .ndjson.gz als auch .ndjson Dateien.

ParameterStandortAnforderungen
bulkIdpathErforderlich · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
partNumberpathErforderlich · {"type":"integer","minimum":0}
Endpunkt
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results/{partNumber}
X-API-Key: YOUR_API_KEY

Speichern Sie bulk_parts.py in Bulk-Api / neben bulk-created.json. Kopieren Sie das komplette Skript und führen Sie dann den Befehl darunter aus.

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)))
Lauf von Bulk-Api/
python bulk_parts.py

Antworten

HTTP-StatusBedeutung
200Gzip-komprimiertes NDJSON heruntergeladen, nachdem Sie die Weiterleitung
302Weiterleitung zu einem kurzlebigen privaten R2 URL; API-Anmeldeinformationen dürfen nicht weitergeleitet werden · Location
401Authentifizierung erforderlich oder ungültig
404Ressource nicht gefunden oder nicht im besitz des anrufers.
409Ressourcenzustand oder Idempotenzkonflikt
410Das behaltene Ergebnis ist abgelaufen
200 · application/x-ndjson
{
  "type": "string"
}

Job-Staaten und Beibehaltung

Die Ergebnisse bleiben für 24 Stunden nach Abschluss des gesamten Bulk-Auftrags verfügbar. Speichern Sie sie vor expiresAt. Die Medien in Ihrem Zielort folgen den Aufbewahrungsrichtlinien Ihres Buckets. Ein abgeschlossener Job kann ausgefallene Videos enthalten; counts.invalid zeichnet abgelehnte Eingabezeilen auf.

StaatNächste Maßnahme
awaiting_uploadLaden Sie die Datei hoch und rufen Sie den Start an.
runningPollen Sie die gleiche ID mit Backoff; input.complete zeigt an, ob das Scannen abgeschlossen ist.
pausedLesen Sie pauseReason, beheben Sie es, dann wieder aufnehmen.
finalizingWarten Sie auf die Ergebnisverpackung und die manifeste Veröffentlichung.
completedLaden Sie das Manifest und jeden Teil herunter. Überprüfen Sie den Status und den Fehler jeder Zeile.
failed / cancelledÜberprüfen Sie Fehler und gespeicherten Zustand. Es wird kein endgültiges Manifest veröffentlicht.

Lagerhaltung

Verwenden Sie den Spielplatz, um einen Anbieter zu konfigurieren und die genauen Anforderungsfelder in der Vorschau anzuzeigen. Kundenspeicherberechtigungen gehören in das ausgewählte Speicherobjekt; X-API-Key authentifiziert nur FlashData API-Anforderungen.

QuelleAnforderungsfeld erstellenLieferung
Metadaten, Transkript, Bildunterschriften, Lizenzprüfungoptions.result_storageFakultativ Kopiert NDJSON Ergebnisteile und ein Manifest für Ihren Bucket.
youtube_downloadoptions.storageerforderlich. Liefert Medien an Ihren Bucket; result_storage und browser_delivery werden nicht akzeptiert.

Finden Sie die gelieferten Dateien

Das Datenmanifest wird zuletzt geschrieben und listet Objektschlüssel, Größen und SHA-256-Prüfsummen auf. Es unterscheidet sich vom FlashData-Manifest, das API href-Werte auflistet. YYYYMMDD verwendet in Datenpfaden das UTC Bulk-Erstellungsdatum; in Medienpfaden verwendet es das UTC-Uploaddatum jedes Videos. Bulk OSS Datenlieferung erfordert einen aliyuncs.com Endpunkt.

Private Medien file_url-Werte benötigen Ihren Speicher SDK oder einen signierten URL von diesem Anbieter. Ein FlashData-Schlüssel gewährt keinen Bucket-Zugriff. Optionale Metadaten Companion Dateien werden neben dem Medium gespeichert. Delivery Retries erscheinen in delivery.retryCount.

Layout des Datenobjekts
<prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz
<prefix>/<source>/<bulkId>/manifest.json

Erhalten Sie einen Completement Webhook

Platzieren Sie eine öffentliche HTTPS callback_url außerhalb der Optionen. Bulk sendet abgeschlossen erst nach der Veröffentlichung des Manifests; es sendet keine Pro-Video-Ereignisse und keine Abschlussveranstaltung für fehlgeschlagene oder abgesagte Aufträge. Halten Sie Status Polling als Fallback.

  1. Beharren Sie und deduplizieren Sie delivery_id, dann geben Sie 2xx sofort zurück. Lieferung wiederholt bis zu acht Mal mit Backoff.
  2. Ereignisse sind nicht signiert. Passen Sie die ID und die Quelle zu Ihrem gespeicherten Beleg ab; überprüfen Sie, ob Sie durch das authentifizierte Management API abgeschlossen wurden, bevor Sie den Abruf in die Warteschlange stellen. Ignorieren Sie URLs von einem nicht verifizierten Ereignis.
Request mit einem Callback erstellen
{
  "source": "youtube_metadata",
  "options": {
    "include_formats": false,
    "include_chapters": false
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
Abschlussveranstaltung · illustrativ
{
  "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"
    }
  ]
}

Schemadefinitionen

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