Documentatie bekijken
API-referentie
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.
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.
Resultaat
Laat dit uit om resultaten op te halen via de FlashData API.
Bulk-completion webhook
Aanmelding en verificatie van het manifesthttps://api.flashdata.dev/v2/bulk-jobsEindpunten
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.
| Methode | Pad | Actie |
|---|---|---|
| POST | /v2/bulk-jobs | Een Bulk-taak aanmaken |
| POST | /v2/bulk-jobs/{bulkId}/start | Uploaden en starten |
| GET | /v2/bulk-jobs/{bulkId} | Werkstatus opvragen |
| GET | /v2/bulk-jobs | Lijsttaken |
| POST | /v2/bulk-jobs/{bulkId}/pause | Een baan pauzeren |
| PATCH | /v2/bulk-jobs/{bulkId} | Opties voor taak bijwerken |
| POST | /v2/bulk-jobs/{bulkId}/resume | Een baan hervatten |
| DELETE | /v2/bulk-jobs/{bulkId} | Een opdracht annuleren |
| GET | /v2/bulk-jobs/{bulkId}/results | Het 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.
| Bron | Gedeelde opties |
|---|---|
| youtube_metadata | include_formats, include_chapters |
| youtube_transcript | taal, auto |
| youtube_captions | taal, auto |
| youtube_trainability | Geen opties |
| youtube_download | Media-opties en opslagbestemming |
python -m pip install requestsVelden voor aanvragen aanmaken
| Veld | Type | Gebruik |
|---|---|---|
| source | string | Vereist. Een ondersteunde bron voor elke invoer ID. |
| options | object | Gedeelde bronopties. Gegevensbronnen kunnen result_storage instellen; YouTube Download vereist opslag. |
| callback_url | string | Optionele 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.
POST https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEYBewaar bulk_create.py in bulk-api/naast bulk-created.json. Kopieer het volledige script en voer het commando hieronder uit.
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.jsonAntwoorden en schema aanvragen
| HTTP-status | Betekenis |
|---|---|
| 201 | Bulk job gemaakt met een 15-minuten directe upload URL |
| 401 | Authenticatie vereist of ongeldig |
| 422 | Verzoekvalidering mislukt |
| 503 | Een vereiste afhankelijkheid of catalogus is tijdelijk niet beschikbaar |
{
"$ref": "#/components/schemas/CreateBulkJobRequest"
}{
"$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.
| Parameter | Locatie | Vereist |
|---|---|---|
| bulkId | path | Vereist · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/start
X-API-Key: YOUR_API_KEYBewaar bulk_start.py in bulk-api/naast bulk-created.json. Kopieer het volledige script en voer het commando hieronder uit.
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}"Antwoorden
| HTTP-status | Betekenis |
|---|---|
| 200 | Bulk-taak gestart of de huidige idempotent-status |
| 401 | Authenticatie vereist of ongeldig |
| 404 | Hulpbron niet gevonden of niet eigendom van de beller |
| 409 | Een conflict tussen hulpbronnenstaat of idempotentie |
| 422 | Verzoekvalidering mislukt |
| 503 | Een vereiste afhankelijkheid of catalogus is tijdelijk niet beschikbaar |
{
"$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.
| Parameter | Locatie | Vereist |
|---|---|---|
| bulkId | path | Vereist · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEYBewaar bulk_status.py in bulk-api/naast bulk-created.json. Kopieer het volledige script en voer het commando hieronder uit.
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.jsonAntwoorden
| HTTP-status | Betekenis |
|---|---|
| 200 | Bulk-taakstatus |
| 401 | Authenticatie vereist of ongeldig |
| 404 | Hulpbron niet gevonden of niet eigendom van de beller |
{
"$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.
| Parameter | Locatie | Vereist |
|---|---|---|
| cursor | query | Optioneel · {"type":"string","maxLength":512} |
| limit | query | Optioneel · {"type":"integer","minimum":1,"maximum":50,"default":20} |
GET https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEYBewaar list_bulk_jobs.py in bulk-api/naast bulk-created.json. Kopieer het volledige script en voer het commando hieronder uit.
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"Antwoorden
| HTTP-status | Betekenis |
|---|---|
| 200 | Bulk-taakpagina |
| 401 | Authenticatie vereist of ongeldig |
{
"$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.
| Parameter | Locatie | Vereist |
|---|---|---|
| bulkId | path | Vereist · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/pause
X-API-Key: YOUR_API_KEYBewaar pause_bulk_job.py in bulk-api/naast bulk-created.json. Kopieer het volledige script en voer het commando hieronder uit.
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"Antwoorden
| HTTP-status | Betekenis |
|---|---|
| 200 | Gepauzeerd bulk werk of de huidige idempotent toestand |
| 401 | Authenticatie vereist of ongeldig |
| 404 | Hulpbron niet gevonden of niet eigendom van de beller |
{
"$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.
| Parameter | Locatie | Vereist |
|---|---|---|
| bulkId | path | Vereist · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
PATCH https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEYBewaar update_bulk_job.py in bulk-api/naast bulk-created.json. Kopieer het volledige script en voer het commando hieronder uit.
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"Antwoorden en schema aanvragen
| HTTP-status | Betekenis |
|---|---|
| 200 | Bijgewerkte bulktaakstatus |
| 401 | Authenticatie vereist of ongeldig |
| 404 | Hulpbron niet gevonden of niet eigendom van de beller |
| 409 | Een conflict tussen hulpbronnenstaat of idempotentie |
| 422 | Verzoekvalidering mislukt |
{
"$ref": "#/components/schemas/UpdateBulkJobRequest"
}{
"$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.
| Parameter | Locatie | Vereist |
|---|---|---|
| bulkId | path | Vereist · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/resume
X-API-Key: YOUR_API_KEYBewaar resume_bulk_job.py in bulk-api/naast bulk-created.json. Kopieer het volledige script en voer het commando hieronder uit.
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"Antwoorden
| HTTP-status | Betekenis |
|---|---|
| 200 | Huidige bulk-taakstatus |
| 401 | Authenticatie vereist of ongeldig |
| 404 | Hulpbron niet gevonden of niet eigendom van de beller |
{
"$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.
| Parameter | Locatie | Vereist |
|---|---|---|
| bulkId | path | Vereist · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
DELETE https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEYBewaar cancel_bulk_job.py in bulk-api/naast bulk-created.json. Kopieer het volledige script en voer het commando hieronder uit.
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"Antwoorden
| HTTP-status | Betekenis |
|---|---|
| 200 | Huidige bulk-taakstatus |
| 401 | Authenticatie vereist of ongeldig |
| 404 | Hulpbron niet gevonden of niet eigendom van de beller |
{
"$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.
| Parameter | Locatie | Vereist |
|---|---|---|
| bulkId | path | Vereist · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results
X-API-Key: YOUR_API_KEYBewaar bulk_manifest.py in bulk-api/naast bulk-created.json. Kopieer het volledige script en voer het commando hieronder uit.
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.jsonAntwoorden
| HTTP-status | Betekenis |
|---|---|
| 200 | JSON manifest gedownload na het volgen van de redirect |
| 302 | Redirect naar een kortlevende privé R2 URL; API-aanmeldgegevens mogen niet worden doorgestuurd · Location |
| 401 | Authenticatie vereist of ongeldig |
| 404 | Hulpbron niet gevonden of niet eigendom van de beller |
| 409 | Een conflict tussen hulpbronnenstaat of idempotentie |
| 410 | Het behouden resultaat is verlopen |
{
"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.
| Parameter | Locatie | Vereist |
|---|---|---|
| bulkId | path | Vereist · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
| partNumber | path | Vereist · {"type":"integer","minimum":0} |
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results/{partNumber}
X-API-Key: YOUR_API_KEYBewaar bulk_parts.py in bulk-api/naast bulk-created.json. Kopieer het volledige script en voer het commando hieronder uit.
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"
doneAntwoorden
| HTTP-status | Betekenis |
|---|---|
| 200 | Gzip-gecomprimeerde NDJSON gedownload na het volgen van de redirect |
| 302 | Redirect naar een kortlevende privé R2 URL; API-aanmeldgegevens mogen niet worden doorgestuurd · Location |
| 401 | Authenticatie vereist of ongeldig |
| 404 | Hulpbron niet gevonden of niet eigendom van de beller |
| 409 | Een conflict tussen hulpbronnenstaat of idempotentie |
| 410 | Het behouden resultaat is verlopen |
{
"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.
| Staat | Volgende actie |
|---|---|
| awaiting_upload | Upload het bestand en bel start. |
| running | Poll dezelfde ID met backoff; input.complete toont of scannen voltooid is. |
| paused | Lees pauseReason, repareer het en ga dan verder. |
| finalizing | Wachten op resultaat verpakking en manifest publicatie. |
| completed | Download het manifest en elk onderdeel. Controleer de status en fout van elke rij. |
| failed / cancelled | Controleer 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.
| Bron | Verzoekveld aanmaken | Levering |
|---|---|---|
| Metadata, transcriptie, bijschriften, licentiecontrole | options.result_storage | Optioneel. Kopiëren NDJSON resultaatdelen en een manifest aan uw emmer. |
| youtube_download | options.storage | Vereist. 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.
<prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz
<prefix>/<source>/<bulkId>/manifest.jsonOntvang 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.
- Perst en dedupliceert delivery_id, keer dan direct 2xx terug. De levering wordt tot acht keer herhaald met backoff.
- 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.
{
"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"
}
]
}Schemadefinities
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."
}
}
}