Sfoglia la documentazione
Riferimento API
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.
Costruire un flusso di lavoro Bulk
File locale UTF-8, uno YouTube ID per linea, fino a 2 GiB. Requisiti di ingresso.
Lascia vuoto per provare prima en-orig, poi en, e ottenere una traccia. Oppure inserisci da uno a 10 codici distinti separati da virgole.
Risultato consegna
Lasciare questo fuori per recuperare i risultati attraverso FlashData API.
Bulk completamento webhook
Notifica e verifica della conformità del manifestohttps://api.flashdata.dev/v2/bulk-jobsPunti 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.
| Metodo | Sentiero | Azione |
|---|---|---|
| POST | /v2/bulk-jobs | Creare un lavoro Bulk |
| POST | /v2/bulk-jobs/{bulkId}/start | Carica e inizia |
| GET | /v2/bulk-jobs/{bulkId} | Ottieni lo stato del lavoro |
| GET | /v2/bulk-jobs | Elenco lavori |
| POST | /v2/bulk-jobs/{bulkId}/pause | Pausa un lavoro |
| PATCH | /v2/bulk-jobs/{bulkId} | Opzioni di lavoro di aggiornamento |
| POST | /v2/bulk-jobs/{bulkId}/resume | Riprendi un lavoro |
| DELETE | /v2/bulk-jobs/{bulkId} | Annullare un lavoro |
| GET | /v2/bulk-jobs/{bulkId}/results | Ottenere 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.
| Fonte | Opzioni condivise |
|---|---|
| youtube_metadata | include_formats, include_chapters |
| youtube_transcript | lingua, auto |
| youtube_captions | lingua, auto |
| youtube_trainability | Nessuna opzione |
| youtube_download | Opzioni multimediali e destinazione di archiviazione |
python -m pip install requestsCrea campi di richiesta
| Campo di applicazione | Tipologia | Utilizzo |
|---|---|---|
| source | string | Obbligatorio. Una fonte supportata per ogni input ID. |
| options | object | Opzioni di sorgente condivise. Le fonti di dati possono impostare result_storage; YouTube Download richiede lo storage. |
| callback_url | string | Callback 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.
POST https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEYSalvare bulk_create.py in bulk-api/ accanto a bulk-created.json. Copia lo script completo, quindi esegui il comando sottostante.
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.jsonRisposte e schema di richiesta
| stato HTTP | Significato |
|---|---|
| 201 | Lavoro Bulk creato con un caricamento diretto 15-minuto URL |
| 401 | Autenticazione richiesta o invalida |
| 422 | Richiesta di validazione non riuscita |
| 503 | Una dipendenza o un catalogo richiesti è temporaneamente non disponibile |
{
"$ref": "#/components/schemas/CreateBulkJobRequest"
}{
"$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.
| Parametro | Località | Requisito |
|---|---|---|
| bulkId | path | Obbligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/start
X-API-Key: YOUR_API_KEYSalvare bulk_start.py in bulk-api/ accanto a bulk-created.json. Copia lo script completo, quindi esegui il comando sottostante.
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}"Risposte
| stato HTTP | Significato |
|---|---|
| 200 | Il lavoro Bulk è iniziato o il suo stato idempotent attuale |
| 401 | Autenticazione richiesta o invalida |
| 404 | Risorse non trovate o non possedute dal chiamante |
| 409 | Stato di risorse o conflitto di idempotency |
| 422 | Richiesta di validazione non riuscita |
| 503 | Una dipendenza o un catalogo richiesti è temporaneamente non disponibile |
{
"$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.
| Parametro | Località | Requisito |
|---|---|---|
| bulkId | path | Obbligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEYSalvare bulk_status.py in bulk-api/ accanto a bulk-created.json. Copia lo script completo, quindi esegui il comando sottostante.
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.jsonRisposte
| stato HTTP | Significato |
|---|---|
| 200 | Stato di lavoro Bulk |
| 401 | Autenticazione richiesta o invalida |
| 404 | Risorse non trovate o non possedute dal chiamante |
{
"$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.
| Parametro | Località | Requisito |
|---|---|---|
| cursor | query | Facoltativo · {"type":"string","maxLength":512} |
| limit | query | Facoltativo · {"type":"integer","minimum":1,"maximum":50,"default":20} |
GET https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEYSalvare list_bulk_jobs.py in bulk-api/ accanto a bulk-created.json. Copia lo script completo, quindi esegui il comando sottostante.
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"Risposte
| stato HTTP | Significato |
|---|---|
| 200 | Pagina del lavoro Bulk |
| 401 | Autenticazione richiesta o invalida |
{
"$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.
| Parametro | Località | Requisito |
|---|---|---|
| bulkId | path | Obbligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/pause
X-API-Key: YOUR_API_KEYSalvare pause_bulk_job.py in bulk-api/ accanto a bulk-created.json. Copia lo script completo, quindi esegui il comando sottostante.
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"Risposte
| stato HTTP | Significato |
|---|---|
| 200 | Lavoro di massa riutilizzato o il suo stato idempotent attuale |
| 401 | Autenticazione richiesta o invalida |
| 404 | Risorse non trovate o non possedute dal chiamante |
{
"$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.
| Parametro | Località | Requisito |
|---|---|---|
| bulkId | path | Obbligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
PATCH https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEYSalvare update_bulk_job.py in bulk-api/ accanto a bulk-created.json. Copia lo script completo, quindi esegui il comando sottostante.
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"Risposte e schema di richiesta
| stato HTTP | Significato |
|---|---|
| 200 | Stato di lavoro all'ingrosso aggiornato |
| 401 | Autenticazione richiesta o invalida |
| 404 | Risorse non trovate o non possedute dal chiamante |
| 409 | Stato di risorse o conflitto di idempotency |
| 422 | Richiesta di validazione non riuscita |
{
"$ref": "#/components/schemas/UpdateBulkJobRequest"
}{
"$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.
| Parametro | Località | Requisito |
|---|---|---|
| bulkId | path | Obbligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/resume
X-API-Key: YOUR_API_KEYSalvare resume_bulk_job.py in bulk-api/ accanto a bulk-created.json. Copia lo script completo, quindi esegui il comando sottostante.
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"Risposte
| stato HTTP | Significato |
|---|---|
| 200 | Stato attuale del lavoro in massa |
| 401 | Autenticazione richiesta o invalida |
| 404 | Risorse non trovate o non possedute dal chiamante |
{
"$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.
| Parametro | Località | Requisito |
|---|---|---|
| bulkId | path | Obbligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
DELETE https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEYSalvare cancel_bulk_job.py in bulk-api/ accanto a bulk-created.json. Copia lo script completo, quindi esegui il comando sottostante.
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"Risposte
| stato HTTP | Significato |
|---|---|
| 200 | Stato attuale del lavoro in massa |
| 401 | Autenticazione richiesta o invalida |
| 404 | Risorse non trovate o non possedute dal chiamante |
{
"$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.
| Parametro | Località | Requisito |
|---|---|---|
| bulkId | path | Obbligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results
X-API-Key: YOUR_API_KEYSalvare bulk_manifest.py in bulk-api/ accanto a bulk-created.json. Copia lo script completo, quindi esegui il comando sottostante.
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.jsonRisposte
| stato HTTP | Significato |
|---|---|
| 200 | JSON manifesto scaricato dopo aver seguito il reindirizzamento |
| 302 | Reindirizzamento a un R2 URL privato di breve durata; Le credenziali API non devono essere inoltrate · Location |
| 401 | Autenticazione richiesta o invalida |
| 404 | Risorse non trovate o non possedute dal chiamante |
| 409 | Stato di risorse o conflitto di idempotency |
| 410 | Il risultato mantenuto è scaduto |
{
"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.
| Parametro | Località | Requisito |
|---|---|---|
| bulkId | path | Obbligatorio · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
| partNumber | path | Obbligatorio · {"type":"integer","minimum":0} |
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results/{partNumber}
X-API-Key: YOUR_API_KEYSalvare bulk_parts.py in bulk-api/ accanto a bulk-created.json. Copia lo script completo, quindi esegui il comando sottostante.
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"
doneRisposte
| stato HTTP | Significato |
|---|---|
| 200 | Gzip-compressed NDJSON scaricato dopo aver seguito il reindirizzamento |
| 302 | Reindirizzamento a un R2 URL privato di breve durata; Le credenziali API non devono essere inoltrate · Location |
| 401 | Autenticazione richiesta o invalida |
| 404 | Risorse non trovate o non possedute dal chiamante |
| 409 | Stato di risorse o conflitto di idempotency |
| 410 | Il risultato mantenuto è scaduto |
{
"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.
| Stato | Prossima azione |
|---|---|
| awaiting_upload | Carica il file e chiama l'inizio. |
| running | Versare lo stesso ID con backoff; input.complete mostra se la scansione è finita. |
| paused | Leggi pauseReason, risolvilo, poi riprendi. |
| finalizing | Attendere l'imballaggio dei risultati e la pubblicazione manifesta. |
| completed | Scarica il manifesto e ogni parte. Ispezionare lo stato e l'errore di ogni riga. |
| failed / cancelled | Ispezionare 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.
| Fonte | Creare campo di richiesta | Consegna |
|---|---|---|
| Metadati, trascrizione, didascalie, controllo di licenza | options.result_storage | Facoltativo. Copies NDJSON parti di risultato e un manifesto al vostro secchio. |
| youtube_download | options.storage | Obbligatorio. 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.
<prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz
<prefix>/<source>/<bulkId>/manifest.jsonRicevere 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.
- Persistere e deduplicare delivery_id, quindi restituire immediatamente 2xx. Ritiri di consegna fino a otto volte con backoff.
- 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.
{
"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"
}
]
}Definizioni dello schema
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."
}
}
}