Lewati ke isi
ID
Dapatkan kunci API
Jelajahi dokumentasi

Referensi API

API pemrosesan Bulk

Membuat dan mengontrol berkas berbasis YouTube pekerjaan, kemudian mengambil manifestasi mereka dan bagian hasil.

Di halaman ini

Playground API

Pilih sumber dan salin lengkap alur kerja Python atau Bash, satu permintaan, atau sebuah respon cuplikan. Pratilik taman bermain kode; tidak mengirimkan pekerjaan. Lengkap cardflow handle upload, status checks and retrieval dari setiap bagian hasil.

Parameter sumber

Bangun Bulk alur kerja

Lokal UTF-8 berkas, satu YouTube ID per baris, sampai 2 GiB. Persyaratan masukan.

Hasil pengiriman

Tinggalkan ini untuk mengambil hasil melalui FlashData API.

Bulk pelengkapan webhookPemberitahuan dan verifikasi pelengkapan manifest-
POSThttps://api.flashdata.dev/v2/bulk-jobs
Python 3 · standard library
import gzip
import json
import os
from pathlib import Path
import random
import re
import shutil
import time
import urllib.error
import urllib.parse
import urllib.request

api_key = "YOUR_API_KEY"
api_url = "https://api.flashdata.dev/v2"
input_file = Path("video-ids.txt")
output_dir = Path("bulk-results")
bulk_id = ""  # Paste a saved Bulk ID to monitor/retrieve it without submitting again.
poll_timeout_seconds = 1800
payload = {
    "source": "youtube_trainability",
    "options": {},
}

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)
Buat, unggah, mulai, monitor dan ambil semua bagianOtentikasi X-API-Key

Titik Akhir

Semua titik akhir gunakan https://api.flashdata.dev/v2. Buat suatu pekerjaan yang hendak diunggah ke videoID berkas £1st monitor engkau dapat mengambil manifest dan setiap bagian hasil.

MetodePathAksi
POST/v2/bulk-jobsBuat pekerjaan Bulk
POST/v2/bulk-jobs/{bulkId}/startUnggah dan mulai
GET/v2/bulk-jobs/{bulkId}Dapatkan status pekerjaan
GET/v2/bulk-jobsDaftar tugas
POST/v2/bulk-jobs/{bulkId}/pauseJeda pekerjaan
PATCH/v2/bulk-jobs/{bulkId}Mutakhirkan opsi pekerjaan
POST/v2/bulk-jobs/{bulkId}/resumeLanjutkan pekerjaan
DELETE/v2/bulk-jobs/{bulkId}Batalkan tugas
GET/v2/bulk-jobs/{bulkId}/resultsDapatkan daftar muatan hasil
GET/v2/bulk-jobs/{bulkId}/results/{partNumber}Unduh bagian hasil

Otentikasi dan masukan

Set FLASHDATA_API_KEY ke kunci dengan akses ke sumber yang dipilih. Gunakan kembali kunci dan akun yang sama untuk pembuatan, kontrol, dan hasil. Pemrosesan menggunakan saldo akun dan harga yang normal. YouTube Download membutuhkan akses pemilik dan options.storage.

Membuat folder kerja bernama bulk-api / dan menjalankan contoh-contoh ini dari itu. Taman bermain selesai Python arus kerja menggunakan Python 3.10+ perpustakaan standar; individu Python contoh titik akhir di bawah ini membutuhkan Permintaan; cURL contoh menggunakan Bash, cURL 7.76+, jq dan gzip. Pilih satu bahasa untuk setiap aksi sehingga Anda tidak membuat atau mulai menduplikasi pekerjaan.

Masukan adalah UTF-8 berkas dengan satu 11-character YouTube ID per baris, sampai 2 GiB. Gunakan IDs, bukan URLs. Hapus duplikat IDs sebelum mengunggah; diulang IDs diproses secara terpisah.

SumberOpsi bersama
youtube_metadatainclude_formats, include_chapters
youtube_transcriptbahasa, otomatis
youtube_captionsbahasa, otomatis
youtube_trainabilityTidak ada opsi
youtube_downloadOpsi media dan tujuan penyimpanan
Python ketergantungan
python -m pip install requests

Buat ruas permintaan

RuasJenisPenggunaan
sourcestringPerlu. Satu sumber yang didukung untuk setiap masukan ID.
optionsobjectOpsi sumber bersama. Sumber data dapat mengatur result_storage; YouTube Download membutuhkan penyimpanan.
callback_urlstringHTTPS publik opsional call back selesai. Dikirim setelah publikasi yang jelas.

Buat pekerjaan Bulk

Membuat pekerjaan, mengunggah UTF-8 berkas teks dengan satu 11-character YouTube video ID per baris ke upload.href, kemudian panggilan mulai. Membuat pekerjaan sendiri tidak mulai memproses.

Contoh ini menulis video-ids.txt dan menyimpan tanda terima 201 ke bulk-created.json. Simpan tanda terima itu secara pribadi dan gunakan job.id untuk setiap permintaan nanti. Membuat pekerjaan meninggalkannya di awaiting_upload; upload URL berakhir setelah 15 menit.

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

Simpan bulk_create.py di bulk-api / di samping bulk-created.json. Salin skrip lengkap, kemudian jalankan perintah di bawahnya.

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))
Lari dari bulki-api /
python bulk_create.py

Menanggapi dan meminta skema

Status HTTPArtinya
201Bulk pekerjaan yang dibuat dengan 15Q- menit langsung upload URL
401Otentikasi diperlukan atau tak valid
422Permintaan validasi gagal
503Ketergantungan atau katalog yang diperlukan sementara tidak tersedia
Isi permintaan
{
  "$ref": "#/components/schemas/CreateBulkJobRequest"
}
201 · application/json
{
  "$ref": "#/components/schemas/BulkJobCreated"
}

Unggah dan mulai

Mulai memproses video UTF-8 terunggah ID, hingga ke 2 GiB (2147483648 bytes). Menjaga berkas tidak berubah setelah dimulai.

Pertama PUT video-ids.txt untuk tanda terima upload.href dengan upload.contentType, tanpa X-API-Key. Contoh panggilan dimulai hanya setelah upload sukses. Menjaga file upload tidak berubah sesudahnya.

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

Simpan bulk_start.py di bulk-api / di samping bulk-created.json. Salin skrip lengkap, kemudian jalankan perintah di bawahnya.

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))
Lari dari bulki-api /
python bulk_start.py

Respon

Status HTTPArtinya
200Bulk pekerjaan dimulai atau keadaan idempoten saat ini
401Otentikasi diperlukan atau tak valid
404Sumber daya tidak ditemukan atau tidak dimiliki oleh penelepon
409Kondisi sumber daya atau konflik idempotency
422Permintaan validasi gagal
503Ketergantungan atau katalog yang diperlukan sementara tidak tersedia
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Dapatkan status pekerjaan

Baca job.status, masukan, jumlah, pauseReason dan error. Periksa ulang ID yang sama dengan penundaan; selesai berarti manifest diterbitkan, bukan berarti setiap video berhasil.

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

Simpan bulk_status.py di bulk-api / di samping bulk-created.json. Salin skrip lengkap, kemudian jalankan perintah di bawahnya.

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))
Lari dari bulki-api /
python bulk_status.py

Respon

Status HTTPArtinya
200Bulk kondisi tugas
401Otentikasi diperlukan atau tak valid
404Sumber daya tidak ditemukan atau tidak dimiliki oleh penelepon
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Daftar tugas

Respon berisi data dan paginasi. Pass pagination.nextCursor sebagai permintaan berikutnya parameter query kursor sampai null. Gunakan batas dari 1 ke 50; baku adalah 20.

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

Simpan list_bulk_jobs.py di bulk-api / di samping bulk-created.json. Salin skrip lengkap, kemudian jalankan perintah di bawahnya.

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))
Lari dari bulki-api /
python list_bulk_jobs.py

Respon

Status HTTPArtinya
200Bulk halaman tugas
401Otentikasi diperlukan atau tak valid
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobPage"
}

Jeda pekerjaan

Jeda pengiriman baru dan hasil kemasan. Pekerjaan yang ada terus dengan pengaturan asli mereka dan biaya. Lanjutkan pekerjaan ketika siap.

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

Simpan pause_bulk_job.py di bulk-api / di samping bulk-created.json. Salin skrip lengkap, kemudian jalankan perintah di bawahnya.

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))
Lari dari bulki-api /
python pause_bulk_job.py

Respon

Status HTTPArtinya
200Ditunda lama tugas atau keadaan idempoten saat ini
401Otentikasi diperlukan atau tak valid
404Sumber daya tidak ditemukan atau tidak dimiliki oleh penelepon
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Mutakhirkan opsi pekerjaan

Perbarui opsi ketika menunggu upload, atau saat jeda sebelum semua masukan telah dibaca. Pekerjaan yang ada menjaga pengaturan mereka. Jika jeda masih dalam proses, tunggu dan coba lagi respon 409. Setelah semua masukan dibaca, hanya kredensial pengiriman yang dapat diperbarui. Set callback_url ke null untuk menghapusnya.

Contoh ini menghapus callback penyelesaian. Untuk mengubah opsi sumber, kirim objek options. Jeda pemrosesan terlebih dahulu dan tunggu hingga jeda berlaku; 409 berarti pembaruan belum dapat diterapkan. Tugas turunan yang sudah ada tetap menggunakan opsi awalnya.

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

Simpan update_bulk_job.py di bulk-api / di samping bulk-created.json. Salin skrip lengkap, kemudian jalankan perintah di bawahnya.

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))
Lari dari bulki-api /
python update_bulk_job.py

Menanggapi dan meminta skema

Status HTTPArtinya
200Diperbarui keadaan tugas massal
401Otentikasi diperlukan atau tak valid
404Sumber daya tidak ditemukan atau tidak dimiliki oleh penelepon
409Kondisi sumber daya atau konflik idempotency
422Permintaan validasi gagal
Isi permintaan
{
  "$ref": "#/components/schemas/UpdateBulkJobRequest"
}
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Lanjutkan pekerjaan

Perbaiki pauseReason pertama, seperti menambahkan kredit atau memperbarui mandat penyimpanan, kemudian melanjutkan Bulk ID yang sama.

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

Simpan resume_bulk_job.py di bulk-api / di samping bulk-created.json. Salin skrip lengkap, kemudian jalankan perintah di bawahnya.

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))
Lari dari bulki-api /
python resume_bulk_job.py

Respon

Status HTTPArtinya
200Kondisi tugas besar saat ini
401Otentikasi diperlukan atau tak valid
404Sumber daya tidak ditemukan atau tidak dimiliki oleh penelepon
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Batalkan tugas

Hentikan pengiriman baru. Pekerjaan yang ada masih bisa finish dan dikenakan biaya normal mereka. Pekerjaan yang dibatalkan tidak menerbitkan daftar akhir.

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

Simpan cancel_bulk_job.py di bulk-api / di samping bulk-created.json. Salin skrip lengkap, kemudian jalankan perintah di bawahnya.

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))
Lari dari bulki-api /
python cancel_bulk_job.py

Respon

Status HTTPArtinya
200Kondisi tugas besar saat ini
401Otentikasi diperlukan atau tak valid
404Sumber daya tidak ditemukan atau tidak dimiliki oleh penelepon
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Dapatkan daftar muatan hasil

Ikuti redirek untuk mengunduh manifest JSON dan gunakan link-nya untuk mengambil berkas hasil. Ambil penyimpanan yang ditandatangani URLs tanpa kunci API Anda. Hasil tetap tersedia untuk 24 jam setelah seluruh Bulk menyelesaikan pekerjaan.

Permintaan terotentikasi API mengembalikan 302 dengan header Lokasi. Ambil yang HTTPS penyimpanan URL dalam permintaan terpisah tanpa X-API-Key. Contoh menyelamatkan manifest.json. Sebuah 409 berarti hasil tidak siap; 410 berarti mereka berakhir.

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

Simpan bulk_manifest.py di bulk-api / di samping bulk-created.json. Salin skrip lengkap, kemudian jalankan perintah di bawahnya.

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))
Lari dari bulki-api /
python bulk_manifest.py

Respon

Status HTTPArtinya
200JSON manifest diunduh setelah mengikuti redirect
302Mengarahkan ke R2 URL yang tinggal; API kredensial tidak boleh diteruskan · Location
401Otentikasi diperlukan atau tak valid
404Sumber daya tidak ditemukan atau tidak dimiliki oleh penelepon
409Kondisi sumber daya atau konflik idempotency
410Hasil yang ditahan telah berakhir
200 · application/json
{
  "type": "object",
  "additionalProperties": true
}

Unduh bagian hasil

Gunakan setiap parts[].number dari manifest.json. Setiap titik akhir kembali 302 ke gzip NDJSON berkas; unduh tanpa API kunci, dekompresi, kemudian parse satu JSON objek per baris. Bergabung dengan indeks berbasis zero-. Contoh mengambil semua bagian dan menjaga baik .ndjson.gz dan .ndjson file.

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

Simpan bulk_parts.py di bulk-api / di samping bulk-created.json. Salin skrip lengkap, kemudian jalankan perintah di bawahnya.

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)))
Lari dari bulki-api /
python bulk_parts.py

Respon

Status HTTPArtinya
200NDJSON terkompresi Gzip- diunduh setelah mengikuti redirect
302Mengarahkan ke R2 URL yang tinggal; API kredensial tidak boleh diteruskan · Location
401Otentikasi diperlukan atau tak valid
404Sumber daya tidak ditemukan atau tidak dimiliki oleh penelepon
409Kondisi sumber daya atau konflik idempotency
410Hasil yang ditahan telah berakhir
200 · application/x-ndjson
{
  "type": "string"
}

Pekerjaan negara bagian dan penahanan

Hasil tetap tersedia untuk 24 jam setelah seluruh Bulk menyelesaikan pekerjaan. Selamatkan mereka sebelum expiresAt. Media di tujuanmu mengikuti kebijakan penyimpanan embermu. Pekerjaan selesai dapat menyertakan video gagal; catatan counts.invalid ditolak baris masukan.

KeadaanAksi berikutnya
awaiting_uploadUnggah berkas dan panggil start.
runningPoll ID yang sama dengan backoff; input.complete menunjukkan apakah pemindaian selesai.
pausedBaca pauseReason, perbaiki, kemudian lanjutkan.
finalizingTunggu hasil pengepakan dan publikasi yang nyata.
completedUnduh manifest dan setiap bagian. Inspeksi status dan kesalahan setiap baris.
failed / cancelledGalat pemeriksaan dan keadaan yang disimpan. Tidak ada manifes akhir diterbitkan.

Pengiriman penyimpanan

Gunakan tempat bermain untuk menata penyedia dan pratinjau ruas permintaan yang tepat. Kredensial penyimpanan pelanggan milik dalam objek penyimpanan yang dipilih; X-API-Key hanya otentikasi FlashData API permintaan.

SumberBuat ruas permintaanPengiriman
Metadata, transkrip, captions, pemeriksaan lisensioptions.result_storageOpsional. Salinan bagian hasil NDJSON dan manifest ke ember Anda.
youtube_downloadoptions.storagePerlu. Mengirim media ke ember Anda; result_storage dan browser_delivery tidak diterima.

Temukan berkas yang dikirim

Daftar muatan data ditulis terakhir dan daftar kunci objek, ukuran dan SHA-256 checksums. Ini berbeda dari manifest FlashData, yang daftar nilai API. YYYYMMDD dalam jalur data menggunakan tanggal pembuatan UTC Bulk; dalam jalur media ini menggunakan tanggal upload UTC setiap video. Bulk OSS data pengiriman memerlukan sebuah titik akhir aliyuncs.com.

Media pribadi file_url membutuhkan penyimpanan Anda SDK atau URL yang ditandatangani dari penyedia tersebut. Kunci FlashData tidak memberikan akses ember. Berkas pendamping metadata opsional disimpan di samping media. Pengiriman kembali muncul di delivery.retryCount.

Tata letak objek data
<prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz
<prefix>/<source>/<bulkId>/manifest.json

Menerima sebuah webhook pelengkapan

Tempatkan publik HTTPS callback_url pilihan luar. Bulk mengirim hanya selesai setelah menerbitkan daftar muatan; ini tidak mengirim acara video per dan tidak ada acara penyelesaian untuk gagal atau membatalkan tugas. Menjaga status polling sebagai fallback.

  1. Persist dan deduplikasi delivery_id, kemudian kembali 2xx segera. Pengiriman ulang hingga delapan kali dengan mundur.
  2. Kejadian yang tidak ditandatangani. Cocokkan id dan sumber ke tanda terima tersimpan Anda; verifikasi selesai melalui manajemen terotentikasi API sebelum antrian pengambilan. Abaikan URLs dari sebuah kejadian yang belum diverifikasi.
Buat permintaan dengan callback
{
  "source": "youtube_metadata",
  "options": {
    "include_formats": false,
    "include_chapters": false
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
Acara penyelesaian
{
  "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"
    }
  ]
}

Definisi skema

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