Ga naar de inhoud
NL
API-sleutel ophalen
Documentatie bekijken

API-referentie

API voor Bulk-verwerking

Creëer en controle op bestand gebaseerde YouTube-taken, en haal vervolgens hun manifesten en resultaatdelen op.

Op deze pagina

API-playground

Kies een broncode en kopieer een complete Python of Bash workflow, een enkele aanvraag of een steekproefrespons. De speeltuin previews code; het geeft geen opdracht. Complete workflows hanteren upload, status controles en het ophalen van elk resultaat deel.

Bronparameters

Bouw een Bulk workflow

Lokale UTF-8-bestand, één YouTube ID per regel, tot 2 GiB. Invoervereisten.

Laat leeg om eerst en-orig en daarna en te proberen en één spoor terug te geven. Of voer één tot 10 verschillende codes in, gescheiden door komma’s.

Nummer bijschrift auto

Resultaat

Laat dit uit om resultaten op te halen via de FlashData API.

Bulk-completion webhookAanmelding en verificatie van het 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_transcript",
    "options": {
        "auto": True,
    },
}

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)
Alle onderdelen aanmaken, uploaden, starten, monitoren en ophalenX-API-Key-authenticatie

Eindpunten

Alle eindpunten gebruiken https://api.flashdata.dev/v2. Maak een job aan → upload een video-ID bestand → start → monitor → haalt de manifest en elk resultaat deel.

MethodePadActie
POST/v2/bulk-jobsEen Bulk-taak aanmaken
POST/v2/bulk-jobs/{bulkId}/startUploaden en starten
GET/v2/bulk-jobs/{bulkId}Werkstatus opvragen
GET/v2/bulk-jobsLijsttaken
POST/v2/bulk-jobs/{bulkId}/pauseEen baan pauzeren
PATCH/v2/bulk-jobs/{bulkId}Opties voor taak bijwerken
POST/v2/bulk-jobs/{bulkId}/resumeEen baan hervatten
DELETE/v2/bulk-jobs/{bulkId}Een opdracht annuleren
GET/v2/bulk-jobs/{bulkId}/resultsHet resultaat manifest ophalen
GET/v2/bulk-jobs/{bulkId}/results/{partNumber}Download resultaatonderdelen

Authenticatie en invoer

Stel FLASHDATA_API_KEY in op een sleutel met toegang tot de gekozen bron. Hergebruik dezelfde sleutel en zorg voor creatie, controles en resultaten. De verwerking maakt gebruik van het saldo van de rekening en de normale prijzen per bron. YouTube Download vereist toegang tot de eigenaar en options.storage.

Maak een werkmap genaamd bulk-api/ en voer deze voorbeelden uit. De complete Python workflow maakt gebruik van de Python 3.10+ standaardbibliotheek; de afzonderlijke Python endpoint voorbeelden hieronder vereisen Verzoeken; cURL voorbeelden gebruiken Bash, cURL 7.76+, jq en gzip. Kies één taal voor elke actie zodat u geen dubbel werk maakt of start.

Invoer is een UTF-8-bestand met één 11-karakter YouTube ID per regel, tot 2 GiB. Gebruik IDs, niet URLs. Verwijder dubbele IDs alvorens te uploaden; herhaalde IDs worden afzonderlijk verwerkt.

BronGedeelde opties
youtube_metadatainclude_formats, include_chapters
youtube_transcripttaal, auto
youtube_captionstaal, auto
youtube_trainabilityGeen opties
youtube_downloadMedia-opties en opslagbestemming
Python afhankelijkheid
python -m pip install requests

Velden voor aanvragen aanmaken

VeldTypeGebruik
sourcestringVereist. Een ondersteunde bron voor elke invoer ID.
optionsobjectGedeelde bronopties. Gegevensbronnen kunnen result_storage instellen; YouTube Download vereist opslag.
callback_urlstringOptionele publieke HTTPS voltooiing callback. Verzonden na publicatie.

Een Bulk-taak aanmaken

Maak een job aan, upload een UTF-8 tekstbestand met één 11-karakter YouTube video ID per regel naar upload.href en bel dan start. Het creëren van de taak alleen begint niet met verwerken.

Dit voorbeeld schrijft video-ids.txt en slaat het 201 ontvangstbewijs op in bulk-created.json. Houd dat ontvangstbewijs privé en hergebruik job.id voor elke latere aanvraag. Het aanmaken van een taak laat het in awaiting_upload; de upload URL verloopt na 15 minuten.

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

Bewaar bulk_create.py in bulk-api/naast bulk-created.json. Kopieer het volledige script en voer het commando hieronder uit.

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

Antwoorden en schema aanvragen

HTTP-statusBetekenis
201Bulk job gemaakt met een 15-minuten directe upload URL
401Authenticatie vereist of ongeldig
422Verzoekvalidering mislukt
503Een vereiste afhankelijkheid of catalogus is tijdelijk niet beschikbaar
Aanvraaginhoud
{
  "$ref": "#/components/schemas/CreateBulkJobRequest"
}
201 · application/json
{
  "$ref": "#/components/schemas/BulkJobCreated"
}

Uploaden en starten

Begin met het verwerken van het geüploade UTF-8 video ID bestand, tot 2 GiB (2147483648 bytes). Het bestand ongewijzigd houden na het starten.

Eerste PUT video-ids.txt naar upload.href met upload.contentType, zonder X-API-Key. Het voorbeeld roept start pas na upload slaagt. Houd het geüploade bestand daarna onveranderd.

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

Bewaar bulk_start.py in bulk-api/naast bulk-created.json. Kopieer het volledige script en voer het commando hieronder uit.

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

Antwoorden

HTTP-statusBetekenis
200Bulk-taak gestart of de huidige idempotent-status
401Authenticatie vereist of ongeldig
404Hulpbron niet gevonden of niet eigendom van de beller
409Een conflict tussen hulpbronnenstaat of idempotentie
422Verzoekvalidering mislukt
503Een vereiste afhankelijkheid of catalogus is tijdelijk niet beschikbaar
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Werkstatus opvragen

Lees job.status, input, counts, pauseReason en fout. Controleer dezelfde ID opnieuw met een vertraging; voltooid betekent dat het manifest wordt gepubliceerd, niet dat elke video geslaagd is.

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

Bewaar bulk_status.py in bulk-api/naast bulk-created.json. Kopieer het volledige script en voer het commando hieronder uit.

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

Antwoorden

HTTP-statusBetekenis
200Bulk-taakstatus
401Authenticatie vereist of ongeldig
404Hulpbron niet gevonden of niet eigendom van de beller
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Lijsttaken

De respons bevat gegevens en paginatie. Geef pagination.nextCursor door als de cursor-queryparameter van de volgende aanvraag totdat het null is. Gebruik limiet van 1 tot 50; de standaard is 20.

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

Bewaar list_bulk_jobs.py in bulk-api/naast bulk-created.json. Kopieer het volledige script en voer het commando hieronder uit.

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

Antwoorden

HTTP-statusBetekenis
200Bulk-taakpagina
401Authenticatie vereist of ongeldig
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobPage"
}

Een baan pauzeren

Pauzeer nieuwe inzendingen en resultaatverpakking. Bestaande banen blijven bestaan met hun oorspronkelijke instellingen en lasten. Hervat de klus als je klaar bent.

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

Bewaar pause_bulk_job.py in bulk-api/naast bulk-created.json. Kopieer het volledige script en voer het commando hieronder uit.

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

Antwoorden

HTTP-statusBetekenis
200Gepauzeerd bulk werk of de huidige idempotent toestand
401Authenticatie vereist of ongeldig
404Hulpbron niet gevonden of niet eigendom van de beller
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Opties voor taak bijwerken

Update opties tijdens het wachten uploaden, of terwijl gepauzeerd voordat alle invoer is gelezen. Bestaande banen behouden hun instellingen. Als het pauzeren nog bezig is, wacht en probeer dan een 409-respons. Nadat alle invoer is gelezen, kunnen alleen de leveringsgegevens worden bijgewerkt. Stel callback_url in op null om het te verwijderen.

Dit voorbeeld verwijdert de complete callback. Om de bronopties te wijzigen, stuur je een optie object. Pauzeer eerst en wacht tot de pauze van kracht wordt; een 409 betekent dat de update nog niet kan worden toegepast. Bestaande baantjes houden hun oorspronkelijke opties.

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

Bewaar update_bulk_job.py in bulk-api/naast bulk-created.json. Kopieer het volledige script en voer het commando hieronder uit.

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

Antwoorden en schema aanvragen

HTTP-statusBetekenis
200Bijgewerkte bulktaakstatus
401Authenticatie vereist of ongeldig
404Hulpbron niet gevonden of niet eigendom van de beller
409Een conflict tussen hulpbronnenstaat of idempotentie
422Verzoekvalidering mislukt
Aanvraaginhoud
{
  "$ref": "#/components/schemas/UpdateBulkJobRequest"
}
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Een baan hervatten

Fix pauseReason eerst, zoals het toevoegen van credits of het bijwerken van opslaggegevens, dan hervatten van dezelfde Bulk ID.

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

Bewaar resume_bulk_job.py in bulk-api/naast bulk-created.json. Kopieer het volledige script en voer het commando hieronder uit.

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

Antwoorden

HTTP-statusBetekenis
200Huidige bulk-taakstatus
401Authenticatie vereist of ongeldig
404Hulpbron niet gevonden of niet eigendom van de beller
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Een opdracht annuleren

Stop nieuwe inzendingen. Bestaande banen kunnen nog steeds finish en hun normale kosten. Een geannuleerde job publiceert geen definitieve manifest.

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

Bewaar cancel_bulk_job.py in bulk-api/naast bulk-created.json. Kopieer het volledige script en voer het commando hieronder uit.

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

Antwoorden

HTTP-statusBetekenis
200Huidige bulk-taakstatus
401Authenticatie vereist of ongeldig
404Hulpbron niet gevonden of niet eigendom van de beller
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Het resultaat manifest ophalen

Volg de redirect om de JSON manifest te downloaden en gebruik de links om resultaatbestanden op te halen. Gesigneerde opslag URLs ophalen zonder uw API-sleutel. De resultaten blijven beschikbaar voor 24 uren nadat de volledige Bulk-taak is voltooid.

Het geauthentiseerde API-verzoek geeft 302 terug met een Locatie-header. Haal die HTTPS opslag URL in een aparte aanvraag zonder X-API-Key. Het voorbeeld slaat manifest.json op. Een 409 betekent dat de resultaten niet klaar zijn; 410 betekent dat ze verlopen zijn.

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

Bewaar bulk_manifest.py in bulk-api/naast bulk-created.json. Kopieer het volledige script en voer het commando hieronder uit.

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

Antwoorden

HTTP-statusBetekenis
200JSON manifest gedownload na het volgen van de redirect
302Redirect naar een kortlevende privé R2 URL; API-aanmeldgegevens mogen niet worden doorgestuurd · Location
401Authenticatie vereist of ongeldig
404Hulpbron niet gevonden of niet eigendom van de beller
409Een conflict tussen hulpbronnenstaat of idempotentie
410Het behouden resultaat is verlopen
200 · application/json
{
  "type": "object",
  "additionalProperties": true
}

Download resultaatonderdelen

Gebruik elke parts[].number van manifest.json. Elk eindpunt geeft een 302 terug aan een gzip NDJSON bestand; download zonder de API sleutel, decomprimeer, ontleed dan één JSON object per regel. Voeg je bij de nul-gebaseerde index. Het voorbeeld haalt alle onderdelen op en houdt zowel .ndjson.gz als .ndjson bestanden.

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

Bewaar bulk_parts.py in bulk-api/naast bulk-created.json. Kopieer het volledige script en voer het commando hieronder uit.

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

Antwoorden

HTTP-statusBetekenis
200Gzip-gecomprimeerde NDJSON gedownload na het volgen van de redirect
302Redirect naar een kortlevende privé R2 URL; API-aanmeldgegevens mogen niet worden doorgestuurd · Location
401Authenticatie vereist of ongeldig
404Hulpbron niet gevonden of niet eigendom van de beller
409Een conflict tussen hulpbronnenstaat of idempotentie
410Het behouden resultaat is verlopen
200 · application/x-ndjson
{
  "type": "string"
}

Banenstaten en behoud

De resultaten blijven beschikbaar voor 24 uren nadat de volledige Bulk-taak is voltooid. Sla ze op voor expiresAt. Media op uw bestemming volgt het bewaarbeleid van uw emmer. Een voltooide job kan mislukte video's bevatten; counts.invalid neemt afgewezen invoerlijnen op.

StaatVolgende actie
awaiting_uploadUpload het bestand en bel start.
runningPoll dezelfde ID met backoff; input.complete toont of scannen voltooid is.
pausedLees pauseReason, repareer het en ga dan verder.
finalizingWachten op resultaat verpakking en manifest publicatie.
completedDownload het manifest en elk onderdeel. Controleer de status en fout van elke rij.
failed / cancelledControleer fout en opgeslagen status. Er wordt geen laatste manifest gepubliceerd.

Levering opslag

Gebruik de speeltuin om een provider te configureren en een voorbeeld te geven van de exacte aanvraagvelden. de gegevens van de opslag van de klant behoren tot het gekozen opslagobject; X-API-Key authenticeert alleen FlashData API verzoeken.

BronVerzoekveld aanmakenLevering
Metadata, transcriptie, bijschriften, licentiecontroleoptions.result_storageOptioneel. Kopiëren NDJSON resultaatdelen en een manifest aan uw emmer.
youtube_downloadoptions.storageVereist. Levert media in uw emmer; result_storage en browser_delivery worden niet geaccepteerd.

Zoek de geleverde bestanden

Het gegevens manifest is als laatste geschreven en bevat objectsleutels, maten en SHA-256 controlesums. Het verschilt van het FlashData manifest, dat API href waarden bevat. JJJJMMDD in datapaden gebruikt de UTC Bulk aanmaakdatum; in mediapaden gebruikt het de UTC-uploaddatum van elke video. Bulk OSS-gegevenslevering vereist een aliyuncs.com-eindpunt.

Private media file_url waarden hebben uw opslag SDK of een ondertekende URL van die provider nodig. Een FlashData sleutel geeft geen toegang tot de emmer. Optionele metadata metgezelbestanden worden naast de media opgeslagen. Leveringsherhalingen verschijnen in delivery.retryCount.

Opmaak van gegevensobject
<prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz
<prefix>/<source>/<bulkId>/manifest.json

Ontvang een aangevulde webhook

Plaats een publieke HTTPS callback_url buiten de opties. Bulk stuurt alleen voltooid na het publiceren van het manifest; het stuurt geen per-video-evenementen en geen voltooiingsevenement voor mislukte of geannuleerde taken. Blijf de status peilen als een terugval.

  1. Perst en dedupliceert delivery_id, keer dan direct 2xx terug. De levering wordt tot acht keer herhaald met backoff.
  2. Gebeurtenissen zijn niet ondertekend. Pas id en bron aan uw opgeslagen ontvangstbewijs aan; verifieer voltooid via het geauthentiseerde beheer API voordat u de ophalen in de wachtrij plaatst. Negeer URLs van een niet-verifieerde gebeurtenis.
Een verzoek aanmaken met een terugbelopdracht
{
  "source": "youtube_metadata",
  "options": {
    "include_formats": false,
    "include_chapters": false
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
Afrondingsevenement · illustratief
{
  "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"
    }
  ]
}

Schemadefinities

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