Dokumentation durchsuchen
API-Referenz
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.
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 Webhook
Manifestierungsmitteilung und Prüfunghttps://api.flashdata.dev/v2/bulk-jobsEndpunkte
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.
| Methode | Wegstrecke | Aktion |
|---|---|---|
| POST | /v2/bulk-jobs | Erstellen Sie einen Bulk-Job |
| POST | /v2/bulk-jobs/{bulkId}/start | Hochladen und Starten |
| GET | /v2/bulk-jobs/{bulkId} | Erhalten Sie den Jobstatus |
| GET | /v2/bulk-jobs | Liste der Arbeitsplätze |
| POST | /v2/bulk-jobs/{bulkId}/pause | Einen Job unterbrechen |
| PATCH | /v2/bulk-jobs/{bulkId} | Aktualisieren von Job-Optionen |
| POST | /v2/bulk-jobs/{bulkId}/resume | Wiederaufnahme eines Arbeitsplatzes |
| DELETE | /v2/bulk-jobs/{bulkId} | Einen Job stornieren |
| GET | /v2/bulk-jobs/{bulkId}/results | Holen 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.
| Quelle | Gemeinsame Optionen |
|---|---|
| youtube_metadata | include_formats, include_chapters |
| youtube_transcript | Sprache, Auto |
| youtube_captions | Sprache, Auto |
| youtube_trainability | Keine Optionen |
| youtube_download | Medienoptionen und Speicherziel |
python -m pip install requestsAnforderungsfelder erstellen
| Feld | Typ | Nutzung |
|---|---|---|
| source | string | erforderlich. Eine unterstützte Quelle für jeden Eingang ID. |
| options | object | Shared Source Optionen. Datenquellen können result_storage einstellen; YouTube Download benötigt Speicher. |
| callback_url | string | Optionaler ö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.
POST https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEYSpeichern 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.
import json
import os
from pathlib import Path
import requests
os.umask(0o077)
Path("video-ids.txt").write_bytes(b"jNQXAC9IVRw\ndQw4w9WgXcQ\n")
response = requests.post(
"https://api.flashdata.dev/v2/bulk-jobs",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
json={"source": "youtube_metadata", "options": {"include_formats": False}},
timeout=30, allow_redirects=False,
)
response.raise_for_status()
receipt = response.json()
Path("bulk-created.json").write_text(json.dumps(receipt, indent=2), encoding="utf-8")
print(json.dumps(receipt["job"], indent=2))python bulk_create.pyumask 077
printf '%s\n' 'jNQXAC9IVRw' 'dQw4w9WgXcQ' > video-ids.txt
curl --fail-with-body --silent --show-error \
'https://api.flashdata.dev/v2/bulk-jobs' \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Content-Type: application/json' \
--data '{"source":"youtube_metadata","options":{"include_formats":false}}' \
--output bulk-created.json &&
jq '.job | {id, source, status}' bulk-created.jsonAntworten und Anforderungsschema
| HTTP-Status | Bedeutung |
|---|---|
| 201 | Bulk-Auftrag erstellt mit einem 15-Minuten-Direkt-Upload URL |
| 401 | Authentifizierung erforderlich oder ungültig |
| 422 | Antragsvalidierung fehlgeschlagen |
| 503 | Eine erforderliche Abhängigkeit oder ein Katalog ist vorübergehend nicht verfügbar |
{
"$ref": "#/components/schemas/CreateBulkJobRequest"
}{
"$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.
| Parameter | Standort | Anforderungen |
|---|---|---|
| bulkId | path | Erforderlich · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/start
X-API-Key: YOUR_API_KEYSpeichern 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.
import json
import os
from pathlib import Path
import requests
receipt = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))
upload = receipt["upload"]
if upload["method"] != "PUT" or not upload["href"].startswith("https://"):
raise ValueError("Expected an HTTPS PUT upload URL")
# Stream the file to storage without the FlashData key.
with open("video-ids.txt", "rb") as file:
response = requests.put(
upload["href"], data=file,
headers={"Content-Type": upload["contentType"]},
timeout=300, allow_redirects=False,
)
response.raise_for_status()
if not 200 <= response.status_code < 300:
raise RuntimeError("Upload did not complete; do not start the job yet")
bulk_id = receipt["job"]["id"]
response = requests.post(
f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/start",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json()["job"], indent=2))python bulk_start.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
UPLOAD_URL=$(jq -er '.upload.href' bulk-created.json)
CONTENT_TYPE=$(jq -er '.upload.contentType' bulk-created.json)
curl --fail-with-body --silent --show-error --proto '=https' \
--header "Content-Type: $CONTENT_TYPE" \
--upload-file video-ids.txt "$UPLOAD_URL" &&
curl --fail-with-body --silent --show-error --request POST \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID/start" \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}"Antworten
| HTTP-Status | Bedeutung |
|---|---|
| 200 | Bulk-Job gestartet oder sein aktueller idempotenter Zustand |
| 401 | Authentifizierung erforderlich oder ungültig |
| 404 | Ressource nicht gefunden oder nicht im besitz des anrufers. |
| 409 | Ressourcenzustand oder Idempotenzkonflikt |
| 422 | Antragsvalidierung fehlgeschlagen |
| 503 | Eine erforderliche Abhängigkeit oder ein Katalog ist vorübergehend nicht verfügbar |
{
"$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.
| Parameter | Standort | Anforderungen |
|---|---|---|
| bulkId | path | Erforderlich · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEYSpeichern 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.
import json
import os
from pathlib import Path
import requests
bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.get(
f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
timeout=30, allow_redirects=False,
)
response.raise_for_status()
Path("bulk-job.json").write_text(json.dumps(response.json(), indent=2), encoding="utf-8")
print(json.dumps(response.json()["job"], indent=2))python bulk_status.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
curl --fail-with-body --silent --show-error \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID" \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--output bulk-job.json &&
jq '.job | {id, status, counts, pauseReason, error, expiresAt}' bulk-job.jsonAntworten
| HTTP-Status | Bedeutung |
|---|---|
| 200 | Bulk Jobstatus |
| 401 | Authentifizierung erforderlich oder ungültig |
| 404 | Ressource nicht gefunden oder nicht im besitz des anrufers. |
{
"$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.
| Parameter | Standort | Anforderungen |
|---|---|---|
| cursor | query | Optional · {"type":"string","maxLength":512} |
| limit | query | Optional · {"type":"integer","minimum":1,"maximum":50,"default":20} |
GET https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEYSpeichern 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.
import json
import os
from pathlib import Path
import requests
response = requests.get(
"https://api.flashdata.dev/v2/bulk-jobs?limit=20",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))python list_bulk_jobs.pycurl --fail-with-body --silent --show-error --max-time 30 \
--request GET \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
"https://api.flashdata.dev/v2/bulk-jobs?limit=20"Antworten
| HTTP-Status | Bedeutung |
|---|---|
| 200 | Bulk Jobseite |
| 401 | Authentifizierung erforderlich oder ungültig |
{
"$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.
| Parameter | Standort | Anforderungen |
|---|---|---|
| bulkId | path | Erforderlich · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/pause
X-API-Key: YOUR_API_KEYSpeichern 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.
import json
import os
from pathlib import Path
import requests
bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.post(
f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/pause",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))python pause_bulk_job.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
curl --fail-with-body --silent --show-error --max-time 30 \
--request POST \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID/pause"Antworten
| HTTP-Status | Bedeutung |
|---|---|
| 200 | Unterbrochener Bulk Job oder sein aktueller idempotenter Zustand |
| 401 | Authentifizierung erforderlich oder ungültig |
| 404 | Ressource nicht gefunden oder nicht im besitz des anrufers. |
{
"$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.
| Parameter | Standort | Anforderungen |
|---|---|---|
| bulkId | path | Erforderlich · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
PATCH https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEYSpeichern 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.
import json
import os
from pathlib import Path
import requests
bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.patch(
f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
json={"callback_url": None},
timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))python update_bulk_job.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
curl --fail-with-body --silent --show-error --max-time 30 \
--request PATCH \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Content-Type: application/json' --data '{"callback_url":null}' \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID"Antworten und Anforderungsschema
| HTTP-Status | Bedeutung |
|---|---|
| 200 | Aktualisierter Bulk-Job-Status |
| 401 | Authentifizierung erforderlich oder ungültig |
| 404 | Ressource nicht gefunden oder nicht im besitz des anrufers. |
| 409 | Ressourcenzustand oder Idempotenzkonflikt |
| 422 | Antragsvalidierung fehlgeschlagen |
{
"$ref": "#/components/schemas/UpdateBulkJobRequest"
}{
"$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.
| Parameter | Standort | Anforderungen |
|---|---|---|
| bulkId | path | Erforderlich · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/resume
X-API-Key: YOUR_API_KEYSpeichern 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.
import json
import os
from pathlib import Path
import requests
bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.post(
f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/resume",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))python resume_bulk_job.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
curl --fail-with-body --silent --show-error --max-time 30 \
--request POST \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID/resume"Antworten
| HTTP-Status | Bedeutung |
|---|---|
| 200 | Aktueller Massenarbeitsplatz |
| 401 | Authentifizierung erforderlich oder ungültig |
| 404 | Ressource nicht gefunden oder nicht im besitz des anrufers. |
{
"$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.
| Parameter | Standort | Anforderungen |
|---|---|---|
| bulkId | path | Erforderlich · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
DELETE https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEYSpeichern 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.
import json
import os
from pathlib import Path
import requests
bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.delete(
f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))python cancel_bulk_job.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
curl --fail-with-body --silent --show-error --max-time 30 \
--request DELETE \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID"Antworten
| HTTP-Status | Bedeutung |
|---|---|
| 200 | Aktueller Massenarbeitsplatz |
| 401 | Authentifizierung erforderlich oder ungültig |
| 404 | Ressource nicht gefunden oder nicht im besitz des anrufers. |
{
"$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.
| Parameter | Standort | Anforderungen |
|---|---|---|
| bulkId | path | Erforderlich · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results
X-API-Key: YOUR_API_KEYSpeichern 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.
import json
import os
from pathlib import Path
import requests
bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.get(
f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/results",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
timeout=30, allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 302:
raise RuntimeError(f"Expected a manifest redirect, got {response.status_code}")
url = response.headers["Location"]
if not url.startswith("https://"):
raise ValueError("Expected an HTTPS storage URL")
manifest = requests.get(url, timeout=120) # No FlashData API key.
manifest.raise_for_status()
Path("manifest.json").write_text(json.dumps(manifest.json(), indent=2), encoding="utf-8")
print(json.dumps(manifest.json(), indent=2))python bulk_manifest.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
# Only send the API key to FlashData; fetch storage URLs separately.
fetch_bulk_result() {
local storage_url
storage_url=$(curl --fail-with-body --silent --show-error \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID/results$1" \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--output /dev/null --write-out '%{redirect_url}') || return
curl --fail-with-body --silent --show-error --proto '=https' \
"${storage_url:?Expected a signed result URL}" --output "$2"
}
fetch_bulk_result '' manifest.json &&
jq '{status, counts, parts, expires_at}' manifest.jsonAntworten
| HTTP-Status | Bedeutung |
|---|---|
| 200 | JSON Manifest heruntergeladen, nachdem Sie die Weiterleitung |
| 302 | Weiterleitung zu einem kurzlebigen privaten R2 URL; API-Anmeldeinformationen dürfen nicht weitergeleitet werden · Location |
| 401 | Authentifizierung erforderlich oder ungültig |
| 404 | Ressource nicht gefunden oder nicht im besitz des anrufers. |
| 409 | Ressourcenzustand oder Idempotenzkonflikt |
| 410 | Das behaltene Ergebnis ist abgelaufen |
{
"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.
| Parameter | Standort | Anforderungen |
|---|---|---|
| bulkId | path | Erforderlich · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
| partNumber | path | Erforderlich · {"type":"integer","minimum":0} |
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results/{partNumber}
X-API-Key: YOUR_API_KEYSpeichern 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.
import json
import os
from pathlib import Path
import requests
import gzip
import shutil
bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
manifest = json.loads(Path("manifest.json").read_text(encoding="utf-8"))
for part in manifest["parts"]:
number = part["number"]
response = requests.get(
f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/results/{number}",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
timeout=30, allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 302:
raise RuntimeError(f"Expected a part redirect, got {response.status_code}")
url = response.headers["Location"]
if not url.startswith("https://"):
raise ValueError("Expected an HTTPS storage URL")
# Save the original gzip bytes; do not decompress twice.
with requests.get(url, stream=True, timeout=120) as download:
download.raise_for_status()
with open(f"part-{number}.ndjson.gz", "wb") as file:
download.raw.decode_content = False
shutil.copyfileobj(download.raw, file)
with gzip.open(f"part-{number}.ndjson.gz", "rt", encoding="utf-8") as rows:
with open(f"part-{number}.ndjson", "w", encoding="utf-8") as file:
for line in rows:
file.write(line)
print(json.dumps(json.loads(line)))python bulk_parts.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
# Only send the API key to FlashData; fetch storage URLs separately.
fetch_bulk_result() {
local storage_url
storage_url=$(curl --fail-with-body --silent --show-error \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID/results$1" \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--output /dev/null --write-out '%{redirect_url}') || return
curl --fail-with-body --silent --show-error --proto '=https' \
"${storage_url:?Expected a signed result URL}" --output "$2"
}
fetch_bulk_result '' manifest.json &&
jq '{status, counts, parts, expires_at}' manifest.json
# Run in the same Bash session as fetch_bulk_result.
jq -r '.parts[].number' manifest.json | while IFS= read -r PART; do
fetch_bulk_result "/$PART" "part-$PART.ndjson.gz" || exit
gzip -dc "part-$PART.ndjson.gz" > "part-$PART.ndjson" || exit
jq -c '{index, video_id, status, results, error}' "part-$PART.ndjson"
doneAntworten
| HTTP-Status | Bedeutung |
|---|---|
| 200 | Gzip-komprimiertes NDJSON heruntergeladen, nachdem Sie die Weiterleitung |
| 302 | Weiterleitung zu einem kurzlebigen privaten R2 URL; API-Anmeldeinformationen dürfen nicht weitergeleitet werden · Location |
| 401 | Authentifizierung erforderlich oder ungültig |
| 404 | Ressource nicht gefunden oder nicht im besitz des anrufers. |
| 409 | Ressourcenzustand oder Idempotenzkonflikt |
| 410 | Das behaltene Ergebnis ist abgelaufen |
{
"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.
| Staat | Nächste Maßnahme |
|---|---|
| awaiting_upload | Laden Sie die Datei hoch und rufen Sie den Start an. |
| running | Pollen Sie die gleiche ID mit Backoff; input.complete zeigt an, ob das Scannen abgeschlossen ist. |
| paused | Lesen Sie pauseReason, beheben Sie es, dann wieder aufnehmen. |
| finalizing | Warten Sie auf die Ergebnisverpackung und die manifeste Veröffentlichung. |
| completed | Laden 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.
| Quelle | Anforderungsfeld erstellen | Lieferung |
|---|---|---|
| Metadaten, Transkript, Bildunterschriften, Lizenzprüfung | options.result_storage | Fakultativ Kopiert NDJSON Ergebnisteile und ein Manifest für Ihren Bucket. |
| youtube_download | options.storage | erforderlich. 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.
<prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz
<prefix>/<source>/<bulkId>/manifest.jsonErhalten 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.
- Beharren Sie und deduplizieren Sie delivery_id, dann geben Sie 2xx sofort zurück. Lieferung wiederholt bis zu acht Mal mit Backoff.
- 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.
{
"source": "youtube_metadata",
"options": {
"include_formats": false,
"include_chapters": false
},
"callback_url": "https://your-app.example/webhooks/flashdata"
}{
"delivery_id": "bulk-completion:bulk_EXAMPLE123",
"id": "bulk_EXAMPLE123",
"source": "youtube_metadata",
"status": "completed",
"links": [
{
"rel": "self",
"href": "https://api.flashdata.dev/v2/bulk-jobs/bulk_EXAMPLE123",
"method": "GET"
},
{
"rel": "results",
"href": "https://api.flashdata.dev/v2/bulk-jobs/bulk_EXAMPLE123/results",
"method": "GET"
}
]
}Schemadefinitionen
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
{
"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
{
"type": "object",
"additionalProperties": false,
"required": [
"data",
"pagination"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BulkJob"
}
},
"pagination": {
"$ref": "#/components/schemas/Pagination"
}
}
}BulkJobResponse
{
"type": "object",
"additionalProperties": false,
"required": [
"job"
],
"properties": {
"job": {
"$ref": "#/components/schemas/BulkJob"
}
}
}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
{
"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
{
"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
{
"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
{
"type": "object",
"additionalProperties": false,
"required": [
"field",
"code",
"message"
],
"properties": {
"field": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}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."
}
}
}