Salta al contenuto
IT
Ottieni la chiave API
Sfoglia la documentazione

Riferimento API

API di elaborazione Bulk

Creare e controllare i lavori YouTube basati su file, quindi recuperare i loro manifesti e parti di risultato.

In questa pagina

Playground API

Scegliere una sorgente e copiare un flusso di lavoro completo Python o Bash, una singola richiesta o una risposta del campione. Il parco giochi prevede il codice; non presenta un lavoro. I flussi di lavoro completi gestiscono il caricamento, i controlli di stato e il recupero di ogni parte del risultato.

Parametri di origine

Costruire un flusso di lavoro Bulk

File locale UTF-8, uno YouTube ID per linea, fino a 2 GiB. Requisiti di ingresso.

Risultato consegna

Lasciare questo fuori per recuperare i risultati attraverso FlashData API.

Bulk completamento webhookNotifica e verifica della conformità del manifesto
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_metadata",
    "options": {
        "include_formats": True,
        "include_chapters": 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)
Creare, caricare, avviare, monitorare e recuperare tutte le partiautenticazione X-API-Key

Punti di fine

Tutti gli endpoint utilizzano https://api.flashdata.dev/v2. Creare un lavoro → caricare un file video-ID → avviare → monitorare → recuperare il manifesto e ogni parte del risultato.

MetodoSentieroAzione
POST/v2/bulk-jobsCreare un lavoro Bulk
POST/v2/bulk-jobs/{bulkId}/startCarica e inizia
GET/v2/bulk-jobs/{bulkId}Ottieni lo stato del lavoro
GET/v2/bulk-jobsElenco lavori
POST/v2/bulk-jobs/{bulkId}/pausePausa un lavoro
PATCH/v2/bulk-jobs/{bulkId}Opzioni di lavoro di aggiornamento
POST/v2/bulk-jobs/{bulkId}/resumeRiprendi un lavoro
DELETE/v2/bulk-jobs/{bulkId}Annullare un lavoro
GET/v2/bulk-jobs/{bulkId}/resultsOttenere il risultato manifesta
GET/v2/bulk-jobs/{bulkId}/results/{partNumber}Scarica parti del risultato

Autenticazione e input

Impostare FLASHDATA_API_KEY a una chiave con l'accesso alla sorgente selezionata. Riutilizzare la stessa chiave e account per la creazione, i controlli e i risultati. Il trattamento utilizza l'equilibrio dell'account e il normale prezzo per-source. YouTube Download richiede l'accesso del proprietario e options.storage.

Creare una cartella di lavoro denominata bulk-api/ ed eseguire questi esempi da esso. Il flusso di lavoro completo Python utilizza la libreria standard Python 3.10+; i singoli esempi di endpoint Python di seguito richiedono richieste; gli esempi cURL utilizzano Bash, cURL 7.76+, jq e gzip. Scegli una lingua per ogni azione in modo da non creare o avviare il lavoro duplicato.

L'ingresso è un file UTF-8 con un 11-character YouTube ID per linea, fino a 2 GiB. Utilizzare IDs, non URLs. Rimuovere il duplicato IDs prima di caricare; IDs ripetuto vengono elaborati separatamente.

FonteOpzioni condivise
youtube_metadatainclude_formats, include_chapters
youtube_transcriptlingua, auto
youtube_captionslingua, auto
youtube_trainabilityNessuna opzione
youtube_downloadOpzioni multimediali e destinazione di archiviazione
Dipendenza Python
python -m pip install requests

Crea campi di richiesta

Campo di applicazioneTipologiaUtilizzo
sourcestringObbligatorio. Una fonte supportata per ogni input ID.
optionsobjectOpzioni di sorgente condivise. Le fonti di dati possono impostare result_storage; YouTube Download richiede lo storage.
callback_urlstringCallback di completamento pubblico opzionale HTTPS. Inviato dopo la pubblicazione manifesta.

Creare un lavoro Bulk

Creare un lavoro, caricare un file di testo UTF-8 con un 11-character YouTube video ID per linea a upload.href, quindi avviare la chiamata. Creare il lavoro da solo non inizia l'elaborazione.

Questo esempio scrive video-ids.txt e salva la ricevuta 201 a bulk-created.json. Mantenere la ricevuta privata e riutilizzare job.id per ogni richiesta successiva. La creazione di un lavoro lo lascia in awaiting_upload; il caricamento URL scade dopo i minuti 15.

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

Salvare bulk_create.py in bulk-api/ accanto a bulk-created.json. Copia lo script completo, quindi esegui il comando sottostante.

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

Risposte e schema di richiesta

stato HTTPSignificato
201Lavoro Bulk creato con un caricamento diretto 15-minuto URL
401Autenticazione richiesta o invalida
422Richiesta di validazione non riuscita
503Una dipendenza o un catalogo richiesti è temporaneamente non disponibile
Corpo della richiesta
{
  "$ref": "#/components/schemas/CreateBulkJobRequest"
}
201 · application/json
{
  "$ref": "#/components/schemas/BulkJobCreated"
}

Carica e inizia

Iniziare a elaborare il file ID video caricato UTF-8, fino a 2 GiB (2147483648 byte). Mantenere il file invariato dopo l'inizio.

Prima PUT video-ids.txt alla ricevuta upload.href con upload.contentType, senza X-API-Key. L'esempio chiama l'inizio solo dopo che il caricamento ha successo. Mantenere il file caricato invariato in seguito.

ParametroLocalitàRequisito
bulkIdpathObbligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Punto di arrivo
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/start
X-API-Key: YOUR_API_KEY

Salvare bulk_start.py in bulk-api/ accanto a bulk-created.json. Copia lo script completo, quindi esegui il comando sottostante.

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

Risposte

stato HTTPSignificato
200Il lavoro Bulk è iniziato o il suo stato idempotent attuale
401Autenticazione richiesta o invalida
404Risorse non trovate o non possedute dal chiamante
409Stato di risorse o conflitto di idempotency
422Richiesta di validazione non riuscita
503Una dipendenza o un catalogo richiesti è temporaneamente non disponibile
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Ottieni lo stato del lavoro

Leggi job.status, input, conteggi, pauseReason ed errore. Ricontrollare lo stesso ID con un ritardo; completato significa che il manifesto è pubblicato, non che ogni video è riuscito.

ParametroLocalitàRequisito
bulkIdpathObbligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Punto di arrivo
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Salvare bulk_status.py in bulk-api/ accanto a bulk-created.json. Copia lo script completo, quindi esegui il comando sottostante.

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

Risposte

stato HTTPSignificato
200Stato di lavoro Bulk
401Autenticazione richiesta o invalida
404Risorse non trovate o non possedute dal chiamante
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Elenco lavori

La risposta contiene i dati e la paginazione. Passare pagination.nextCursor come parametro di query del cursore della prossima richiesta fino a quando non è null. Utilizzare il limite da 1 a 50; il valore predefinito è 20.

ParametroLocalitàRequisito
cursorqueryFacoltativo · {"type":"string","maxLength":512}
limitqueryFacoltativo · {"type":"integer","minimum":1,"maximum":50,"default":20}
Punto di arrivo
GET https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEY

Salvare list_bulk_jobs.py in bulk-api/ accanto a bulk-created.json. Copia lo script completo, quindi esegui il comando sottostante.

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

Risposte

stato HTTPSignificato
200Pagina del lavoro Bulk
401Autenticazione richiesta o invalida
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobPage"
}

Pausa un lavoro

Pausa nuove presentazioni e packaging dei risultati. I lavori esistenti continuano con le loro impostazioni e le spese originali. Riprendi il lavoro quando sei pronto.

ParametroLocalitàRequisito
bulkIdpathObbligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Punto di arrivo
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/pause
X-API-Key: YOUR_API_KEY

Salvare pause_bulk_job.py in bulk-api/ accanto a bulk-created.json. Copia lo script completo, quindi esegui il comando sottostante.

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

Risposte

stato HTTPSignificato
200Lavoro di massa riutilizzato o il suo stato idempotent attuale
401Autenticazione richiesta o invalida
404Risorse non trovate o non possedute dal chiamante
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Opzioni di lavoro di aggiornamento

Opzioni di aggiornamento in attesa di caricamento, o durante la pausa prima che tutto l'ingresso sia stato letto. I lavori esistenti tengono le loro impostazioni. Se il pausing è ancora in corso, attendere e riprovare una risposta 409. Dopo che tutto l'ingresso è stato letto, solo le credenziali di consegna possono essere aggiornate. Impostare callback_url a null per rimuoverlo.

Questo esempio rimuove il callback di completamento. Per cambiare le opzioni di origine, inviare un oggetto opzioni invece. Pausa prima e attendere la pausa per prendere effetto; un 409 significa che l'aggiornamento non può ancora essere applicato. I lavori per bambini esistenti mantengono le loro opzioni originali.

ParametroLocalitàRequisito
bulkIdpathObbligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Punto di arrivo
PATCH https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Salvare update_bulk_job.py in bulk-api/ accanto a bulk-created.json. Copia lo script completo, quindi esegui il comando sottostante.

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

Risposte e schema di richiesta

stato HTTPSignificato
200Stato di lavoro all'ingrosso aggiornato
401Autenticazione richiesta o invalida
404Risorse non trovate o non possedute dal chiamante
409Stato di risorse o conflitto di idempotency
422Richiesta di validazione non riuscita
Corpo della richiesta
{
  "$ref": "#/components/schemas/UpdateBulkJobRequest"
}
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Riprendi un lavoro

Fissare prima pauseReason, come l'aggiunta di crediti o l'aggiornamento delle credenziali di archiviazione, quindi riprendere lo stesso Bulk ID.

ParametroLocalitàRequisito
bulkIdpathObbligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Punto di arrivo
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/resume
X-API-Key: YOUR_API_KEY

Salvare resume_bulk_job.py in bulk-api/ accanto a bulk-created.json. Copia lo script completo, quindi esegui il comando sottostante.

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

Risposte

stato HTTPSignificato
200Stato attuale del lavoro in massa
401Autenticazione richiesta o invalida
404Risorse non trovate o non possedute dal chiamante
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Annullare un lavoro

Smettetela di presentare nuove proposte. I posti di lavoro esistenti possono ancora finish e incorrere le loro spese normali. Un lavoro annullato non pubblica un manifesto finale.

ParametroLocalitàRequisito
bulkIdpathObbligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Punto di arrivo
DELETE https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Salvare cancel_bulk_job.py in bulk-api/ accanto a bulk-created.json. Copia lo script completo, quindi esegui il comando sottostante.

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

Risposte

stato HTTPSignificato
200Stato attuale del lavoro in massa
401Autenticazione richiesta o invalida
404Risorse non trovate o non possedute dal chiamante
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Ottenere il risultato manifesta

Seguire il reindirizzamento per scaricare il manifesto JSON e utilizzare i suoi link per recuperare i file di risultato. Blocca lo storage firmato URLs senza la chiave API. I risultati rimangono disponibili per le ore 24 dopo che l'intero lavoro Bulk è completato.

La richiesta autenticata API restituisce 302 con un intestazione Location. Prestare che lo storage HTTPS URL in una richiesta separata senza X-API-Key. L'esempio salva manifest.json. A 409 significa che i risultati non sono pronti; 410 significa che sono scaduti.

ParametroLocalitàRequisito
bulkIdpathObbligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Punto di arrivo
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results
X-API-Key: YOUR_API_KEY

Salvare bulk_manifest.py in bulk-api/ accanto a bulk-created.json. Copia lo script completo, quindi esegui il comando sottostante.

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

Risposte

stato HTTPSignificato
200JSON manifesto scaricato dopo aver seguito il reindirizzamento
302Reindirizzamento a un R2 URL privato di breve durata; Le credenziali API non devono essere inoltrate · Location
401Autenticazione richiesta o invalida
404Risorse non trovate o non possedute dal chiamante
409Stato di risorse o conflitto di idempotency
410Il risultato mantenuto è scaduto
200 · application/json
{
  "type": "object",
  "additionalProperties": true
}

Scarica parti del risultato

Utilizzare ogni parts[].number da manifest.json. Ogni endpoint restituisce un 302 a un file gzip NDJSON; scarica senza la chiave API, decomprimere, quindi parse un oggetto JSON per linea. Partecipa all'indice zero-based. L'esempio recupera tutte le parti e mantiene entrambi i file .ndjson.gz e .ndjson.

ParametroLocalitàRequisito
bulkIdpathObbligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
partNumberpathObbligatorio · {"type":"integer","minimum":0}
Punto di arrivo
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results/{partNumber}
X-API-Key: YOUR_API_KEY

Salvare bulk_parts.py in bulk-api/ accanto a bulk-created.json. Copia lo script completo, quindi esegui il comando sottostante.

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

Risposte

stato HTTPSignificato
200Gzip-compressed NDJSON scaricato dopo aver seguito il reindirizzamento
302Reindirizzamento a un R2 URL privato di breve durata; Le credenziali API non devono essere inoltrate · Location
401Autenticazione richiesta o invalida
404Risorse non trovate o non possedute dal chiamante
409Stato di risorse o conflitto di idempotency
410Il risultato mantenuto è scaduto
200 · application/x-ndjson
{
  "type": "string"
}

Stati di lavoro e ritenzione

I risultati rimangono disponibili per le ore 24 dopo che l'intero lavoro Bulk è completato. Salvali prima di expiresAt. I media nella vostra destinazione seguono la politica di conservazione del vostro secchio. Un lavoro completato può includere video falliti; counts.invalid registra linee di input rifiutate.

StatoProssima azione
awaiting_uploadCarica il file e chiama l'inizio.
runningVersare lo stesso ID con backoff; input.complete mostra se la scansione è finita.
pausedLeggi pauseReason, risolvilo, poi riprendi.
finalizingAttendere l'imballaggio dei risultati e la pubblicazione manifesta.
completedScarica il manifesto e ogni parte. Ispezionare lo stato e l'errore di ogni riga.
failed / cancelledIspezionare l'errore e lo stato salvato. Non viene pubblicato nessun manifesto finale.

Consegna di stoccaggio

Utilizzare il parco giochi per configurare un fornitore e visualizzare in anteprima i campi di richiesta esatti. Le credenziali di archiviazione dei clienti appartengono all'oggetto di archiviazione scelto; X-API-Key autentica solo le richieste FlashData API.

FonteCreare campo di richiestaConsegna
Metadati, trascrizione, didascalie, controllo di licenzaoptions.result_storageFacoltativo. Copies NDJSON parti di risultato e un manifesto al vostro secchio.
youtube_downloadoptions.storageObbligatorio. Fornisce i supporti al secchio; result_storage e browser_delivery non sono accettati.

Trova i file consegnati

Il manifesto di dati è scritto per ultimo e elenca le chiavi di oggetto, le dimensioni e i checksum SHA-256. Si differenzia dal manifesto FlashData, che elenca i valori di href API. YYYYMMDD nei percorsi di dati utilizza la data di creazione UTC Bulk; nei percorsi multimediali utilizza la data di caricamento UTC di ogni video. La consegna dei dati di Bulk OSS richiede un endpoint aliyuncs.com.

Media privati file_url i valori hanno bisogno del tuo storage SDK o firmata URL da quel fornitore. Una chiave FlashData non garantisce l'accesso al secchio. I file dei compagni di metadati opzionali sono memorizzati accanto ai media. I retries di consegna appaiono in delivery.retryCount.

Disposizione degli oggetti di dati
<prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz
<prefix>/<source>/<bulkId>/manifest.json

Ricevere un Webhook di completamento

Posizionare un pubblico HTTPS callback_url opzioni esterne. Bulk invia completato solo dopo aver pubblicato il manifesto; non invia eventi per video e nessun evento di completamento per lavori falliti o annullati. Mantenere lo stato inquinante come un fallback.

  1. Persistere e deduplicare delivery_id, quindi restituire immediatamente 2xx. Ritiri di consegna fino a otto volte con backoff.
  2. Gli eventi non sono firmati. Abbina id e fonte alla ricevuta salvata; verifica completata tramite la gestione autenticata API prima di eseguire il recupero. Ignora URLs da un evento non verificato.
Crea richiesta con un callback
{
  "source": "youtube_metadata",
  "options": {
    "include_formats": false,
    "include_chapters": false
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
Evento di completamento · illustrativo
{
  "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"
    }
  ]
}

Definizioni dello schema

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