Langkau ke kandungan
MS
Dapatkan kunci API
Semak dokumentasi

Rujukan API

API pemprosesan Bulk

Cipta dan kendali berbasis berkas YouTube Pekerjaan mereka, kemudian mengambil kembali manifes dan bagian hasilnya.

Pada halaman ini

Playground API

Pilih sumber dan salin lengkap Python atau Bash workflow, satu permintaan, atau respon sampel. Kode taman bermain; tidak memberikan pekerjaan. Aliran kerja yang lengkap menangani unggahan, pemeriksaan status dan pengambilan kembali setiap bagian hasil.

Parameter sumber

Bina aliran kerja Bulk

Berkas UTF-8 lokal, satu YouTube ID per baris, hingga 2 GiB. Persyaratan masuk ke dalam.

Biarkan kosong untuk mencoba en-orig, kemudian en, dan kembali satu trek. Atau masukkan satu kode atau sampai 10 kode berbeda dipisahkan dengan koma.

Trek Kapsi kapsi untuk nama auto

Hasil pengiriman

Biarkan ini pergi untuk mendapatkan hasil melalui FlashData API.

Bulk pelengkapan pelengkapan webhookPemakluman dan verifikasi Manifest-penyelesaian
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_captions",
    "options": {
        "auto": False,
    },
}

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, muat naik, mulai, pantau dan ambil semua bagianOtentikasi X-API-Key

Titik akhir Ukiran

Semua titik akhir digunakan https://api.flashdata.dev/v2. → Buat sebuah pekerjaan → upload berkas video-ID → mulai → monitor → ambil manifes dan setiap bagian hasil.

Metode InfakPathAksi
POST/v2/bulk-jobsBuat pekerjaan Bulk
POST/v2/bulk-jobs/{bulkId}/startMuatnaik dan mulai
GET/v2/bulk-jobs/{bulkId}AKAN mendapat status pekerjaan
GET/v2/bulk-jobsDaftar pekerjaan
POST/v2/bulk-jobs/{bulkId}/pauseJeda kerja
PATCH/v2/bulk-jobs/{bulkId}Pilihan kerja update
POST/v2/bulk-jobs/{bulkId}/resumeKembali bekerja
DELETE/v2/bulk-jobs/{bulkId}¡Chardin a job
GET/v2/bulk-jobs/{bulkId}/resultsWoindon mendapatkan hasil manifest
GET/v2/bulk-jobs/{bulkId}/results/{partNumber}Bagian hasil unduhan gandeng

Autentikasi dan input

Diataskan FLASHDATA_API_KEY ke kunci dengan akses ke sumber yang dipilih. Anda menggunakan kembali kunci dan akun yang sama untuk penciptaan, kontrol dan hasil. Pemrosesan menggunakan saldo rekening dan harga per-sumber normal. YouTube Download membutuhkan akses pemilik dan options.storage.

Cipta folder kerja bernama bulk-api/ dan jalankan contoh ini dari folder tersebut. Aliran kerja Python lengkap dalam ruang uji menggunakan pustaka standard Python 3.10+; contoh titik akhir Python berasingan di bawah memerlukan Requests; contoh cURL menggunakan Bash, cURL 7.76+, jq dan gzip. Pilih satu bahasa untuk setiap tindakan supaya anda tidak mencipta atau memulakan kerja pendua.

Input žak adalah berkas UTF-8 dengan satu 11-karakter YouTube ID per baris, hingga 2 GiB. Guna IDs, bukan URLs. Buang pendua pendua IDs sebelum upload; berulang IDs diproses secara terpisah.

SumberPilihan Kongsi
youtube_metadatainclude_formats, include_chapters
youtube_transcriptBahasa, auto
youtube_captionsBahasa, auto
youtube_trainabilityTak ada pilihan
youtube_downloadPilihan media dan destinasi penyimpanan
Kebergantungan Python
python -m pip install requests

Buat bidang permintaan

UkrainianJenisPenggunaan Teropong
sourcestringDiperlukan. Salah satu sumber yang didukung untuk setiap input ID.
optionsobjectPilihan sumber yang terkongsi. Sumber data mungkin menetapkan result_storage; YouTube Download membutuhkan penyimpanan.
callback_urlstringPanggilan balik penyelesaian HTTPS untuk umum opsional. (Inggris) Where Sent after manifes publikasi.

Buat pekerjaan Bulk

Buat pekerjaan, muat naik UTF-8 Berkas teks jarfine dengan satu 11-character YouTube video ID darx <b> upload.hrefKalau begitu, telepon dulu. Menciptakan pekerjaan saja tidak mulai diproses.

Contoh ini menulis video-ids.txt dan menyimpan penerimaan 201 ke bulk-created.json. Memastikan penerimaan itu secara pribadi dan menggunakan kembali job.idQ untuk setiap permintaan selanjutnya. Menciptakan sebuah pekerjaan meninggalkannya dalam awaiting_upload; upload URL berakhir setelah 15 menit.

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

Simpan bulk_create.py dalam pukal-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 pukal-api/
python bulk_create.py

Sambutan dan permintaan skema

Status HTTPArti
201Kerja Bulk dibuat dengan 15-minute direct upload URL
401Pengesahan diperlukan atau tidak sah
422Permintaan validasi quest gagal
503TLS Sebuah dependensi atau katalog yang diperlukan tidak tersedia sementara
Badan permintaan
{
  "$ref": "#/components/schemas/CreateBulkJobRequest"
}
201 · application/json
{
  "$ref": "#/components/schemas/BulkJobCreated"
}

Muatnaik dan mulai

Mulai memproses berkas UTF-8 video ID yang diunggah, hingga 2 GiB (2147483648 bytes). Jaga berkasnya tidak berubah setelah dimulai.

Mula-mula hantar video-ids.txt dengan PUT ke upload.href dalam resit, menggunakan upload.contentType tanpa X-API-Key. Contoh memanggil start hanya selepas muat naik berjaya. Jangan ubah fail yang telah dimuat naik selepas itu.

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

Simpan bulk_start.py dalam pukal-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 pukal-api/
python bulk_start.py

Balasan

Status HTTPArti
200Pekerjaan Bulk dimulai atau keadaan idempoten saat ini
401Pengesahan diperlukan atau tidak sah
404Sumber daya tidak ditemukan atau tidak dimiliki oleh penelepon
409Keadaan Sumber Daya Sumber Daya atau konflik yang tidak menguntungkan
422Permintaan validasi quest gagal
503TLS Sebuah dependensi atau katalog yang diperlukan tidak tersedia sementara
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

AKAN mendapat status pekerjaan

¡job.status, input, jumlah, pauseReason dan kesalahan. Recheck ID yang sama dengan penundaan; selesai berarti manifes diterbitkan, bukan bahwa setiap video berhasil.

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

Simpan bulk_status.py dalam pukal-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 pukal-api/
python bulk_status.py

Balasan

Status HTTPArti
200Bulk Work state
401Pengesahan diperlukan atau tidak sah
404Sumber daya tidak ditemukan atau tidak dimiliki oleh penelepon
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Daftar pekerjaan

Tanggapannya mengandung data dan peginasi. Pass pagination.nextCursor **sebagai parameter pertanyaan kursor permintaan berikutnya sampai saat ini ** null. Batas penggunaan dari 1 Ke 50); baku adalah 20.

ParameterLokasiKeperluan Keperluan Kemurtadan
cursorqueryPilihan · {"type":"string","maxLength":512}
limitqueryPilihan · {"type":"integer","minimum":1,"maximum":50,"default":20}
Titik akhir Ukur
GET https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEY

Simpan list_bulk_jobs.py dalam pukal-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 pukal-api/
python list_bulk_jobs.py

Balasan

Status HTTPArti
200Halaman kerja Bulk
401Pengesahan diperlukan atau tidak sah
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobPage"
}

Jeda kerja

Jeda pengiriman baru dan pengiriman hasil. Pekerjaan yang telah ada berlanjut dengan pengaturan dan tuntutan asli mereka. Lanjutkan pekerjaan ketika siap.

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

Simpan pause_bulk_job.py dalam pukal-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 pukal-api/
python pause_bulk_job.py

Balasan

Status HTTPArti
200Jeda kerja besar atau keadaan idempoten saat ini
401Pengesahan diperlukan atau tidak sah
404Sumber daya tidak ditemukan atau tidak dimiliki oleh penelepon
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Pilihan kerja update

Opsi pemutakhiran saat menunggu unggahan, atau sementara diistirahatkan sebelum semua masukan telah dibaca. Pekerjaan yang ada tetap menjaga pengaturan mereka. Jika berhenti masih dalam proses, tunggu dan coba lagi respon 409. Setelah semua masukan telah dibaca, hanya kelayakan pengiriman yang dapat diperbarui. callback_url ke null untuk menghapusnya.

Contoh ini menghilangkan pelengkapan callback. Untuk mengubah pilihan sumber, kirim sebuah pilihan objek sebagai gantinya. Jeda pertama dan tunggu jeda berlaku; sebuah 409 berarti pembaruan belum dapat diterapkan. Pekerjaan anak - anak yang telah ada tetap memiliki pilihan yang asli.

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

Simpan update_bulk_job.py dalam pukal-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 pukal-api/
python update_bulk_job.py

Sambutan dan permintaan skema

Status HTTPArti
200Status pekerjaan pukal yang baru dimutakhirkan
401Pengesahan diperlukan atau tidak sah
404Sumber daya tidak ditemukan atau tidak dimiliki oleh penelepon
409Keadaan Sumber Daya Sumber Daya atau konflik yang tidak menguntungkan
422Permintaan validasi quest gagal
Badan permintaan
{
  "$ref": "#/components/schemas/UpdateBulkJobRequest"
}
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Kembali bekerja

Pertama-tama Fix pauseReason, seperti menambahkan kredit atau memperbarui kelayakan penyimpanan, kemudian melanjutkan Bulk ID yang sama.

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

Simpan resume_bulk_job.py dalam pukal-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 pukal-api/
python resume_bulk_job.py

Balasan

Status HTTPArti
200Keadaan kerja pukal saat ini
401Pengesahan diperlukan atau tidak sah
404Sumber daya tidak ditemukan atau tidak dimiliki oleh penelepon
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

¡Chardin a job

Hentikan pengiriman baru. Pekerjaan yang telah ada masih dapat finish dan tidak dapat menanggung tuntutan normal mereka. Tugas yang dibatalkan tidak menerbitkan manifes akhir.

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

Simpan cancel_bulk_job.py dalam pukal-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 pukal-api/
python cancel_bulk_job.py

Balasan

Status HTTPArti
200Keadaan kerja pukal saat ini
401Pengesahan diperlukan atau tidak sah
404Sumber daya tidak ditemukan atau tidak dimiliki oleh penelepon
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Woindon mendapatkan hasil manifest

Ikut arah kembali untuk mengunduh manifes JSON dan gunakan link-nya untuk mengambil berkas hasil. Kutip signed penyimpanan URLs tanpa kunci API anda. Hasil hasil tes tetap tersedia untuk jam 24 setelah seluruh pekerjaan Bulk selesai.

Gagal disahkannya permintaan API mengembalikan 302 dengan header Lokasi. Kutip bahwa HTTPS penyimpanan URL dalam permintaan terpisah tanpa X-API-Key. Contoh ini menyelamatkan manifest.json. A 409 berarti hasil tidak siap; 410 berarti mereka sudah tamat.

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

Simpan bulk_manifest.py dalam pukal-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 pukal-api/
python bulk_manifest.py

Balasan

Status HTTPArti
200Diunduh manifes JSON setelah mengikuti arah semula
302Redirect ke swasta berumur pendek R2 URL; Kelayakan API tidak boleh diteruskan · Location
401Pengesahan diperlukan atau tidak sah
404Sumber daya tidak ditemukan atau tidak dimiliki oleh penelepon
409Keadaan Sumber Daya Sumber Daya atau konflik yang tidak menguntungkan
410Hasil yang terpaku telah berakhir
200 · application/json
{
  "type": "object",
  "additionalProperties": true
}

Bagian hasil unduhan gandeng

Guna setiap parts[].number dari manifest.json. Setiap titik akhir end mengembalikan 302 ke berkas gzip NDJSON; download tanpa kunci API, dekompresi, kemudian parse one JSON objek per baris. Bergabung dengan indeks berbasis nol. Contoh itu mengambil semua bagian dan menyimpan kedua berkas .ndjson.gz dan .ndjson.

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

Simpan bulk_parts.py dalam pukal-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 pukal-api/
python bulk_parts.py

Balasan

Status HTTPArti
200Terkompresi Gzip-Mode NDJSON download setelah mengikuti arah semula
302Redirect ke swasta berumur pendek R2 URL; Kelayakan API tidak boleh diteruskan · Location
401Pengesahan diperlukan atau tidak sah
404Sumber daya tidak ditemukan atau tidak dimiliki oleh penelepon
409Keadaan Sumber Daya Sumber Daya atau konflik yang tidak menguntungkan
410Hasil yang terpaku telah berakhir
200 · application/x-ndjson
{
  "type": "string"
}

¡Job negara bagian dan retensi

Hasil hasil tes tetap tersedia untuk jam 24 setelah seluruh pekerjaan Bulk selesai. Simpan mereka sebelum expiresAt. Media di tempat tujuanmu mengikuti kebijakan retensi embermu. Sebuah pekerjaan yang selesai dapat mencakup video yang gagal; catatan counts.invalid menolak input baris.

Negara BagianTindakan berikutnya
awaiting_uploadUpload file dan panggilan mulai.
runningID dengan backoff yang sama; input.complete menunjukkan apakah pemindaian selesai.
pausedBaca pauseReason, perbaiki, lalu sambungkan lagi.
finalizingTunggu hasil kemasan dan publikasinya.
completedUnduh manifes dan setiap bagian. Periksa status dan kesalahan setiap baris.
failed / cancelledPeriksa kesalahan dan keadaan tersimpan. Tidak ada manifes akhir diterbitkan.

Pengiriman penyimpanan

Gunakan ruang uji untuk mengkonfigurasi penyedia dan melihat medan permintaan yang tepat. Kelayakan storan pelanggan perlu berada dalam objek storan yang dipilih; X-API-Key hanya mengesahkan permintaan API FlashData.

SumberBuat bidang permintaanPengiriman
Data meta, transkrip, kapsi, cek lisensioptions.result_storageCoaled. Salin bagian hasil NDJSON dan manifest ke ember Anda.
youtube_downloadoptions.storageDiperlukan. Media pengiriman ke ember Anda; result_storage dan browser_delivery tidak diterima.

Cari file yang dikirimkan

manifest data ditulis terakhir dan mencantumkan kunci objek, ukuran dan SHA-256Q checksums. Ini berbeda dengan manifes FlashData, yang mencantumkan nilai horef API. OLEH YYYYMMDDD dalam jalur data menggunakan tanggal pembuatan UTC Bulk; dalam jalur media ia menggunakan tanggal unggah UTC masing-masing video. Pengiriman data Bulk OSS membutuhkan titik akhir aliyuncs.com.

Nilai file_url untuk media swasta untuk penyimpanan SDK atau URL yang ditandatangani dari penyedia tersebut. Kunci FlashData tidak memberikan akses ember. Berkas-berkas pendamping data metadata yang bersifat opsional telah disimpan di samping media. Retrie pengiriman muncul di delivery.retryCount.

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

Ipar akan menerima pelengkapan webhook

Tempatkan HTTPS callback_url umum di luar pilihan. Pengiriman Bulk baru selesai setelah menerbitkan manifes; ia mengirimkan tidak ada acara per-video dan tidak ada acara penyelesaian untuk pekerjaan yang gagal atau dibatalkan. Tetap jajak pendapat status sebagai kemunduran.

  1. Keperatan dan deduplikasi delivery_id, kemudian kembali 2xx secara segera. Pengiriman sampai delapan kali dengan backoff.
  2. Peristiwa-peristiwa yang tidak ditandatangani. Hatch cocokkan id dan sumber ke penerimaan yang telah disimpan; verifikasi selesai melalui manajemen terotentikasi API sebelum queuing penerimaan kembali. Abaikan URLs dari 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 penyempurnaan hasil penghitungan hasil karya · kejelasan
{
  "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 Schema sontak

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