تخطَّ إلى المحتوى
AR
الحصول على مفتاح API
تصفح الوثائق

مرجع API

واجهة API لمعالجة Bulk

أنشئ مهام YouTube القائمة على الملفات وتحكّم فيها، ثم استرجع ملفات البيان وأجزاء النتائج.

في هذه الصفحة

بيئة تجربة API

(ب) اختيار مصدر ونسخ كامل لتدفق العمل من طراز Python أو Bash، أو طلب واحد، أو رد العينة. الملعب يُفترض أنه لا يقدم عملاً وتعالج تدفقات العمل الكاملة عبء التحميل، والتحقق من الوضع، واسترجاع كل جزء من أجزاء النتائج.

بارامترات المصدر

بناء تدفق عمل من طراز Bulk

ملف محلي بصيغة UTF-8، بمعرّف YouTube واحد في كل سطر، وبحجم يصل إلى 2 GiB. الاحتياجات من المدخلات.

إتركْ فارغاً لتَحْاوُل، ثمّ يَدْعمُ، ويُعيدُ مسارَ واحد. أو الدخول إلى رمز واحد أو حتى 10 رموز مميزة مُنفصلة عن طريق الشيوعيين

مسار التكوين auto

تسليم النتائج

اترك هذا لاسترجاع النتائج من خلال FlashData API.

موقع استكمال Bulk على شبكة الإنترنت(ح)الإخطارات المتعلقة بإكمال المهام والتحقق منها
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_transcript",
    "options": {
        "auto": True,
    },
}

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

opener = urllib.request.build_opener(NoRedirect())
os.umask(0o077)

def api(path, method="GET", body=None):
    data = None if body is None else json.dumps(body).encode("utf-8")
    headers = {"X-API-Key": api_key, "Content-Type": "application/json"}
    for attempt in range(5):
        try:
            request = urllib.request.Request(api_url + path, data=data, headers=headers, method=method)
            with opener.open(request, timeout=60) as response:
                return json.load(response)
        except urllib.error.HTTPError as error:
            if method != "GET" or error.code not in (429, 502, 503, 504) or attempt == 4:
                raise
            retry_after = error.headers.get("Retry-After", "")
            delay = min(120, int(retry_after)) if retry_after.isdigit() else 2 ** attempt
            time.sleep(delay + random.random())

def result_location(path):
    request = urllib.request.Request(api_url + path, headers={"X-API-Key": api_key})
    try:
        with opener.open(request, timeout=60):
            raise RuntimeError("Expected a 302 result redirect")
    except urllib.error.HTTPError as error:
        if error.code != 302:
            raise
        location = error.headers.get("Location", "")
    parsed = urllib.parse.urlsplit(location)
    if parsed.scheme != urllib.parse.urlsplit(api_url).scheme or not parsed.hostname or parsed.username or parsed.password:
        raise RuntimeError("Invalid signed storage URL")
    return location

if not bulk_id:
    if not input_file.is_file() or not 1 <= input_file.stat().st_size <= 2147483648:
        raise ValueError("Use a nonempty UTF-8 ID file up to 2 GiB")
    created = api("/bulk-jobs", "POST", payload)
    bulk_id = created["job"]["id"]
    if not re.fullmatch(r"bulk_[A-Za-z0-9_-]{8,}", bulk_id):
        raise RuntimeError("Invalid Bulk ID")
    work = output_dir / bulk_id
    work.mkdir(parents=True, exist_ok=True)
    (work / "created.json").write_text(json.dumps(created, indent=2))
    print("Saved Bulk ID:", bulk_id, flush=True)
    upload = created["upload"]
    upload_url = urllib.parse.urlsplit(upload["href"])
    if upload["method"] != "PUT" or upload_url.scheme != urllib.parse.urlsplit(api_url).scheme or not upload_url.hostname or upload_url.username or upload_url.password:
        raise RuntimeError("Invalid signed upload URL")
    with input_file.open("rb") as file:
        request = urllib.request.Request(upload["href"], data=file, method="PUT", headers={
            "Content-Type": upload["contentType"], "Content-Length": str(input_file.stat().st_size)
        })
        with opener.open(request, timeout=120) as response:
            response.read()
    api("/bulk-jobs/" + bulk_id + "/start", "POST")

if not re.fullmatch(r"bulk_[A-Za-z0-9_-]{8,}", bulk_id):
    raise ValueError("Invalid Bulk ID")
work = output_dir / bulk_id
work.mkdir(parents=True, exist_ok=True)
deadline = time.monotonic() + poll_timeout_seconds
while True:
    job = api("/bulk-jobs/" + bulk_id)["job"]
    (work / "status.json").write_text(json.dumps(job, indent=2))
    print(job["status"], job["input"], job["counts"], flush=True)
    if job["status"] == "completed":
        break
    if job["status"] in ("paused", "failed", "cancelled", "awaiting_upload"):
        raise RuntimeError(json.dumps({"id": bulk_id, "status": job["status"], "pauseReason": job.get("pauseReason"), "error": job.get("error")}))
    if time.monotonic() >= deadline:
        raise TimeoutError("Job still running. Set bulk_id to " + bulk_id + " and rerun to continue monitoring.")
    time.sleep(10 + random.random())

manifest_url = result_location("/bulk-jobs/" + bulk_id + "/results")
with opener.open(manifest_url, timeout=60) as response:  # No API key sent to storage.
    manifest = json.load(response)
(work / "manifest.json").write_text(json.dumps(manifest, indent=2))
for part in manifest["parts"]:
    number = part["number"]
    if type(number) is not int or number < 1:
        raise RuntimeError("Invalid part number")
    path = "/bulk-jobs/" + bulk_id + "/results/" + str(number)
    if part["href"] != api_url + path:
        raise RuntimeError("Unexpected part API URL")
    storage_url = result_location(path)
    compressed = work / ("part-" + str(number) + ".jsonl.gz")
    with opener.open(storage_url, timeout=120) as response, compressed.open("wb") as file:
        shutil.copyfileobj(response, file, 1024 * 1024)
    with compressed.open("rb") as file:
        gzipped = file.read(2) == b"\x1f\x8b"
    reader = gzip.open(compressed, "rb") if gzipped else compressed.open("rb")
    with reader, (work / ("part-" + str(number) + ".jsonl")).open("wb") as file:
        shutil.copyfileobj(reader, file, 1024 * 1024)
print("Saved manifest and decoded NDJSON parts in", work)
إنشاء جميع الأجزاء وشحنها وبدءها ورصدها واسترجاعهاX-API-Key authentication

نقاط النهاية

جميع نقاط النهاية تستخدم https://api.flashdata.dev/v2. اصنعي وظيفة احملي شريط فيديوID ابدأوا بالمراقبة و استرجعوا البيانات وكل جزء من النتائج

المنهجيةPathالإجراء
POST/v2/bulk-jobsإنشاء وظيفة من طراز Bulk
POST/v2/bulk-jobs/{bulkId}/startتحميل وبدء
GET/v2/bulk-jobs/{bulkId}الحصول على وظيفة
GET/v2/bulk-jobsالوظائف المدرجة في القائمة
POST/v2/bulk-jobs/{bulkId}/pauseاوقفوا العمل
PATCH/v2/bulk-jobs/{bulkId}تحديث خيارات العمل
POST/v2/bulk-jobs/{bulkId}/resumeإستئناف وظيفة
DELETE/v2/bulk-jobs/{bulkId}إلغاء وظيفة
GET/v2/bulk-jobs/{bulkId}/resultsاحصل على نتائج
GET/v2/bulk-jobs/{bulkId}/results/{partNumber}قطع الغيار

التوثيق والمدخلات

اضبط FLASHDATA_API_KEY على مفتاح يملك صلاحية المصدر المختار. أعد استخدام المفتاح والحساب نفسيهما للإنشاء والتحكم والنتائج. تستخدم المعالجة رصيد الحساب وأسعار المصدر المعتادة. يتطلب YouTube Download وصول المالك وoptions.storage.

إنشاء ملف عمل اسمه " السوائب " وطرح هذه الأمثلة منه. اكتملت ساحة اللعب Python استخدامات تدفق العمل Python 3.10+ المكتبة الموحدة؛ الفرد Python وتحتاج الأمثلة النهائية الواردة أدناه إلى طلبات؛ cURL أمثلة Bash, cURL 7.76+, jq و(زب) اختر لغة واحدة لكل عمل حتى لا تخلق أو تبدأ العمل المزدوج

المدخلات هي: UTF-8 ملف واحد 11-منتج YouTube ID لكل خط 2 جي بي. الاستخدام IDsليس URLs. Remove duplicate IDs before uploading; repeated IDs are processed separately.

المصدرالخيارات المشتركة
youtube_metadatainclude_formats, include_chapters
youtube_transcriptاللغة الآلية
youtube_captionsاللغة الآلية
youtube_trainabilityلا خيارات
youtube_downloadخيارات وسائط الإعلام ومقصد التخزين
Python dependency
python -m pip install requests

إنشاء حقول طلب

الميدانالنوعUsage
sourcestringمطلوب. دعم مصدر لكل مدخلات ID.
optionsobjectخيارات المصادر المشتركة. ويمكن أن تحدد مصادر البيانات موقع result_storage؛ YouTube Download يَحتاجُ للتخزين.
callback_urlstringالرأي العام HTTPS إستعادة إستدعاء. Sent after manifest publication.

إنشاء وظيفة من طراز Bulk

إنشاء وظيفة، وتحميل ملف نصي من طراز UTF-8 مع ملصق من طراز 11-character YouTube شريط فيديو ID لكل خط إلى upload.href، ثم الاتصال بالبدء. إن إنشاء الوظيفة وحدها لا يبدأ في التجهيز.

ويكتب هذا المثال video-ids.txt ويحتفظ باستلام 201 إلى bulk-created.json. أبقي هذا الإيصال خاصًا وأعيد استخدامه job.id لكل طلب لاحق إنشاء وظيفة يتركها في awaiting_upload; the upload URL تنتهي مدة العضوية بعد 15 دقائق.

نقطة النهاية
POST https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEY

وفّر bulk_create.py in bulk-api/ beside bulk-created.json. عُلم النص الكامل ثمّ أدير القيادة تحته

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))
تشغيل من السوائب/
python bulk_create.py

الردود والطلب

HTTPمعنى
201Bulk created with a 15-minute direct upload URL
401التوثيق المطلوب أو غير صحيح
422فشل التثبت من الطلب
503التبعية المطلوبة أو المكتال غير متاح بصورة مؤقتة
نص الطلب
{
  "$ref": "#/components/schemas/CreateBulkJobRequest"
}
201 · application/json
{
  "$ref": "#/components/schemas/BulkJobCreated"
}

تحميل وبدء

ابدأوا بتجهيز الحمولة UTF-8 فيديو ID الملف، حتى 2 غيبي2147483648 (ب) أبقِ الملفَ بدون تغيير بعد البَدْء.

أولا PUT video-ids.txt إلى الإيصال upload.href مع upload.contentTypeبدون X-API-Key. على سبيل المثال لا تبدأ إلا بعد أن ينجح تحميلها. أبقوا الملف المُحمّل بدون تغيير بعد ذلك.

البارامتراتالموقعالاحتياج
bulkIdpathمطلوب · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
نقطة النهاية
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/start
X-API-Key: YOUR_API_KEY

وفّر bulk_start.py in bulk-api/ beside bulk-created.json. عُلم النص الكامل ثمّ أدير القيادة تحته

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))
تشغيل من السوائب/
python bulk_start.py

الردود

HTTPمعنى
200بدأت وظيفة Bulk أو حالتها الحالية
401التوثيق المطلوب أو غير صحيح
404الموارد التي لم يعثر عليها أو لا يملكها المتصل
409النزاع في حالة الموارد أو الافتراض
422فشل التثبت من الطلب
503التبعية المطلوبة أو المكتال غير متاح بصورة مؤقتة
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

الحصول على وظيفة

اقرأ job.status وinput وcounts وpauseReason وerror. أعد فحص المعرّف نفسه بعد انتظار؛ وتعني completed نشر manifest، لا نجاح كل فيديو.

البارامتراتالموقعالاحتياج
bulkIdpathمطلوب · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
نقطة النهاية
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

وفّر bulk_status.py in bulk-api/ beside bulk-created.json. عُلم النص الكامل ثمّ أدير القيادة تحته

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))
تشغيل من السوائب/
python bulk_status.py

الردود

HTTPمعنى
200Bulk وظيفة ولاية
401التوثيق المطلوب أو غير صحيح
404الموارد التي لم يعثر عليها أو لا يملكها المتصل
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

الوظائف المدرجة في القائمة

ويتضمن الرد بيانات ومهرجات. مرّة pagination.nextCursor كبرامتر إستفسار الطلب التالي حتى هو null. (ج) الحد الأقصى للاستخدام من 1 إلى 50؛ والمقدار هو 20.

البارامتراتالموقعالاحتياج
cursorqueryاختياري · {"type":"string","maxLength":512}
limitqueryاختياري · {"type":"integer","minimum":1,"maximum":50,"default":20}
نقطة النهاية
GET https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEY

وفّر list_bulk_jobs.py in bulk-api/ beside bulk-created.json. عُلم النص الكامل ثمّ أدير القيادة تحته

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))
تشغيل من السوائب/
python list_bulk_jobs.py

الردود

HTTPمعنى
200Bulk Page
401التوثيق المطلوب أو غير صحيح
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobPage"
}

اوقفوا العمل

وقف العروض الجديدة وتعبئة النتائج. وتستمر الوظائف القائمة بأماكنها الأصلية واتهامها. إسترجعْ العملَ عندما يَستعدُّ.

البارامتراتالموقعالاحتياج
bulkIdpathمطلوب · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
نقطة النهاية
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/pause
X-API-Key: YOUR_API_KEY

وفّر pause_bulk_job.py in bulk-api/ beside bulk-created.json. عُلم النص الكامل ثمّ أدير القيادة تحته

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))
تشغيل من السوائب/
python pause_bulk_job.py

الردود

HTTPمعنى
200وظيفة بالجملة مدفوعة الأجر أو الدولة الافتراضية الحالية
401التوثيق المطلوب أو غير صحيح
404الموارد التي لم يعثر عليها أو لا يملكها المتصل
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

تحديث خيارات العمل

تحديث الخيارات في انتظار تحميلها، أو مع تمهيدها قبل قراءة جميع المدخلات. الوظائف الموجودة تحتفظ بأماكنها إذا كان التوقف لا يزال جارياً، فانتظر وأعيد فحص ردّ شركة 409. وبعد قراءة جميع المدخلات، لا يمكن تحديث سوى وثائق تفويض التسليم. المجموعة callback_url إلى null لإزالته.

وهذا المثال يزيل عودتي الاستكمال. ولتغيير خيارات المصدر، أرسلوا بدلاً من ذلك موضوعاً للخيارات. وقف أولاً وانتظر أن يبدأ نفاذ الوقف؛ يعني الرقم 409 أنه لا يمكن بعد تطبيق آخر المستجدات. وظائف الأطفال القائمة تحتفظ بخياراتهم الأصلية.

البارامتراتالموقعالاحتياج
bulkIdpathمطلوب · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
نقطة النهاية
PATCH https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

وفّر update_bulk_job.py in bulk-api/ beside bulk-created.json. عُلم النص الكامل ثمّ أدير القيادة تحته

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))
تشغيل من السوائب/
python update_bulk_job.py

الردود والطلب

HTTPمعنى
200آخر وظيفة في حالة السوائب
401التوثيق المطلوب أو غير صحيح
404الموارد التي لم يعثر عليها أو لا يملكها المتصل
409النزاع في حالة الموارد أو الافتراض
422فشل التثبت من الطلب
نص الطلب
{
  "$ref": "#/components/schemas/UpdateBulkJobRequest"
}
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

إستئناف وظيفة

استأنفت شركة pauseReason أولاً، مثل إضافة ائتمانات أو تحديث وثائق التفويض في التخزين، ثم استأنفت نفس الرقم Bulk ID.

البارامتراتالموقعالاحتياج
bulkIdpathمطلوب · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
نقطة النهاية
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/resume
X-API-Key: YOUR_API_KEY

وفّر resume_bulk_job.py in bulk-api/ beside bulk-created.json. عُلم النص الكامل ثمّ أدير القيادة تحته

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))
تشغيل من السوائب/
python resume_bulk_job.py

الردود

HTTPمعنى
200الوظيفة العامة الحالية
401التوثيق المطلوب أو غير صحيح
404الموارد التي لم يعثر عليها أو لا يملكها المتصل
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

إلغاء وظيفة

وقف تقديم عروض جديدة. الوظائف الحالية يمكن أن تظل finish و تُوجّه إليهم تهمهم العادية ولا تنشر الوظيفة الملغاة بيانا نهائيا.

البارامتراتالموقعالاحتياج
bulkIdpathمطلوب · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
نقطة النهاية
DELETE https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

وفّر cancel_bulk_job.py in bulk-api/ beside bulk-created.json. عُلم النص الكامل ثمّ أدير القيادة تحته

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))
تشغيل من السوائب/
python cancel_bulk_job.py

الردود

HTTPمعنى
200الوظيفة العامة الحالية
401التوثيق المطلوب أو غير صحيح
404الموارد التي لم يعثر عليها أو لا يملكها المتصل
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

احصل على نتائج

(أ) تتبع إعادة توجيه عملية تحميل بيان JSON، وتستخدم صلاتها باسترجاع ملفات النتائج. ووقعت فيتش على مخزن URLs بدون مفتاح API. لا تزال النتائج متاحة 24 بعد ساعات من كامل Bulk العمل يكتمل.

The authenticated API request returns 302 with a Location header. (أ) أن تخزن شركة HTTPS URL في طلب منفصل بدون X-API-Key. المثال ينقذ manifest.json. A 409 means results are not ready; 410 means they expired.

البارامتراتالموقعالاحتياج
bulkIdpathمطلوب · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
نقطة النهاية
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results
X-API-Key: YOUR_API_KEY

وفّر bulk_manifest.py in bulk-api/ beside bulk-created.json. عُلم النص الكامل ثمّ أدير القيادة تحته

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))
تشغيل من السوائب/
python bulk_manifest.py

الردود

HTTPمعنى
200ملف بيان JSON يُنزَّل بعد اتباع إعادة التوجيه
302إعادة توجيه إلى رابط R2 خاص قصير الصلاحية؛ يجب عدم تمرير بيانات اعتماد API إليه · Location
401التوثيق المطلوب أو غير صحيح
404الموارد التي لم يعثر عليها أو لا يملكها المتصل
409النزاع في حالة الموارد أو الافتراض
410انتهت صلاحية النتيجة المحتفظ بها
200 · application/json
{
  "type": "object",
  "additionalProperties": true
}

قطع الغيار

استخدام كل واحد parts[].number من manifest.json. وتعيد كل نقطة نهاية ملف 302 إلى ملف Gzip NDJSON؛ والتنزيل بدون مفتاح API، و decompress، ثم برد واحد من الجسم JSON لكل خط. انضم إلى الرقم القياسي الصفري. المثال يستعيد كل الأجزاء ويحتفظ بكلاهماndjson.gz وملفات (أندجون)

البارامتراتالموقعالاحتياج
bulkIdpathمطلوب · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
partNumberpathمطلوب · {"type":"integer","minimum":0}
نقطة النهاية
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results/{partNumber}
X-API-Key: YOUR_API_KEY

وفّر bulk_parts.py in bulk-api/ beside bulk-created.json. عُلم النص الكامل ثمّ أدير القيادة تحته

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)))
تشغيل من السوائب/
python bulk_parts.py

الردود

HTTPمعنى
200ملف NDJSON مضغوط باستخدام Gzip يُنزَّل بعد اتباع إعادة التوجيه
302إعادة توجيه إلى رابط R2 خاص قصير الصلاحية؛ يجب عدم تمرير بيانات اعتماد API إليه · Location
401التوثيق المطلوب أو غير صحيح
404الموارد التي لم يعثر عليها أو لا يملكها المتصل
409النزاع في حالة الموارد أو الافتراض
410انتهت صلاحية النتيجة المحتفظ بها
200 · application/x-ndjson
{
  "type": "string"
}

ولايات العمل والاحتفاظ بها

لا تزال النتائج متاحة 24 بعد ساعات من كامل Bulk العمل يكتمل. أنقذهم من قبل expiresAt. وسائل الإعلام في وجهة نظرك تتبع سياسة الاحتفاظ ببطنك ويمكن أن تشمل الوظيفة المنجزة أشرطة فيديو فاشلة؛ وقد رفضت سجلات شركة counts.invalid خطوط المدخلات.

الدولةالإجراء التالي:
awaiting_uploadارفعي الملف واتصلي بالبدء
runningاستطلع المعرّف نفسه مع تراجع تدريجي؛ يبيّن input.complete إن كان المسح قد اكتمل.
pausedاقرأ pauseReasonاصلحه ثم استأنفه
finalizingانتظروا حزمة النتائج و نشرة واضحة
completedتحميل البيان وكل جزء. تفحص حالة كل صف وخطأه
failed / cancelledتفحص الخطأ و انقذ الولاية ولا ينشر أي بيان ختامي.

تسليم المخازن

استخدموا الملعب لضبط مزود وفحصوا حقول الطلب بالضبط وتنتمي وثائق تفويض المخزن إلى الجسم المختار للتخزين؛ ولا توثق شركة X-API-Key إلا طلبات شركة FlashData API.

المصدرتقديم طلب ميدانيالتوصيل
البيانات الوصفية، المخطوطات، المقابض، التحقق من الترخيصoptions.result_storageاختياري. نسخ NDJSON أجزاء من النتائج ودليل على دلك
youtube_downloadoptions.storageمطلوب. إيصال وسائل الإعلام إلى دلو الخاص بك؛ result_storage و browser_delivery غير مقبولة.

اعثر على الملفات التي تم تسليمها

يُكتب سجل البيانات أخيرًا ويذكر مفاتيح الكائنات وأحجامها وبصمات SHA-256. وهو يختلف عن سجل FlashData الذي يذكر قيم API href. يستخدم YYYYMMDD في مسارات البيانات تاريخ إنشاء Bulk بتوقيت UTC؛ وفي مسارات الوسائط يستخدم تاريخ رفع كل فيديو بتوقيت UTC. يتطلب تسليم بيانات Bulk إلى OSS نقطة نهاية aliyuncs.com.

وتحتاج قيم أجهزة الإعلام الخاصة file_url إلى مخزنك SDK أو موقعة URL من ذلك المزود. ألف FlashData المفتاح لا يمنح دخول الدلو. وملفات الوجبات الفوقية الاختيارية مخزنة بجانب وسائط الإعلام. وتظهر عمليات التسليم في delivery.retryCount.

مخططات مواد البيانات
<prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz
<prefix>/<source>/<bulkId>/manifest.json

استلام موقع الإنجاز على شبكة الإنترنت(ح)

مكان عام HTTPS callback_url خيارات خارجية ولا ترسل شركة Bulk إلا بعد نشر البيان؛ فهي لا ترسل أي أحداث لكل فرد ولا أي حدث لإكمال الأعمال الفاشلة أو الملغاة. حافظ على إستطلاع الوضع كتراجع

  1. Persist and deduplicate delivery_id, then return 2x promptly. عمليات تسليم تصل إلى ثماني مرات مع التخلف.
  2. الأحداث غير موقّعة. طابق id وsource مع إيصالك المحفوظ؛ وتحقق من completed عبر Management API الموثَّق قبل وضع الاسترجاع في الطابور. تجاهل الروابط الواردة من حدث لم يُتحقق منه.
تقديم طلب مع ردة فعل
{
  "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"
    }
  ]
}

تعاريف الكيماويات

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