コンテンツへスキップ
JA
APIキーを取得する
ドキュメントを探す

API リファレンス

Bulk 処理 API

ファイルベースのYouTubeジョブを作成し、管理し、そのマニフェストと結果の部分を取得します。

このページの内容

API プレイグラウンド

ソースを選択し、完全なPythonまたはBashワークフロー、単一リクエスト、またはサンプル応答をコピーします。 プレイグラウンドはコードをプレビューします。ジョブを送信しません。 完全なワークフローは、すべての結果のアップロード、ステータスチェック、検索処理を処理します。

ソースパラメータ

Bulkワークフローの構築

ローカルエリア UTF-8 ファイル、1 YouTube ID ラインごとの、まで 2 ジブ。 入力条件.

結果の配達

FlashData APIで結果を取得するには、このオフを残してください。

Bulk 補完 webhookマニフェスト・コンプリート通知と検証
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)
すべての部品を作成、アップロード、開始、モニター、および取得X-API-Key認証

エンドポイント

すべてのエンドポイントは https://api.flashdata.dev/v2. を使用します ジョブの作成 → ビデオ-IDファイルをアップロード → スタート → モニター → は、マニフェストとすべての結果の部分を取得します。

メソッドパスパスアクション
POST/v2/bulk-jobsBulkジョブを作成する
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を要求します。

Bulk-api/ という名前の作業フォルダを作成し、これらの例をそこから実行します。 遊び場の完全なPythonワークフローは、Python 3.10+標準ライブラリを使用しています。 個々のPythonエンドポイントの例は、要求を必要とします。 cURLの例は、Bash、cURL 7.76+、jqとgzipを使用します。 各アクションの言語を1つ選択して、重複作業を作成したり、開始したりしません。

入力はあります UTF-8 1つのファイル 11-キャラクター YouTube ID ラインごとの、まで 2 ジブ。 IDs、URLs ではなく使用して下さい。 アップロードする前に、IDsを複製して削除します。 繰り返しIDsは別々に処理されます。

ソース共有オプション
youtube_metadatainclude_formats、include_chapters
youtube_transcript言語、自動
youtube_captions言語、自動
youtube_trainabilityオプションなし
youtube_downloadメディアのオプションと保存先
Pythonの依存性
python -m pip install requests

フィールドリクエストを作成する

フィールド種類利用条件
sourcestring必須項目 あらゆる入力 ID のための 1 つの支えられた源。
optionsobject共有ソースオプション。 データソースは、result_storageを設定することができます。 YouTube Downloadはストレージが必要です。
callback_urlstringオプションのパブリック HTTPS 補完コールバック。 マニフェスト出版物の後に送られます。

Bulkジョブを作成する

ジョブの作成、アップロード UTF-8 1つのテキストファイル 11-キャラクター YouTube ビデオ ID 行ごとに upload.hrefそれから開始を呼ぶ。 単独でジョブの作成は処理を開始しません。

この例では、video-ids.txt を記述し、201 のレシートを bulk-created.json に保存します。 後日リクエストごとに、job.idをプライベートに再利用しておきましょう。 awaiting_uploadでジョブの葉を作成します。 URLのアップロードは、15の分後に期限が切れます。

エンドポイント
POST https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEY

bulk-created.jsonの横のバルクAPI/でbulk_create.pyを保存します。 完全なスクリプトをコピーし、以下のコマンドを実行します。

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))
バルクapi/から実行
python bulk_create.py

応答とリクエストスキーマ

HTTPステータス意味する
201Bulk ジョブは、15-minute ダイレクトアップロード URL で作成
401認証が必要または無効
422リクエストの検証が失敗しました
503必要な依存性やカタログは一時的に利用できません。
リクエストボディ
{
  "$ref": "#/components/schemas/CreateBulkJobRequest"
}
201 · application/json
{
  "$ref": "#/components/schemas/BulkJobCreated"
}

アップロードと開始

アップロードしたUTF-8ビデオIDファイル、2 GiB(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-created.jsonの横のバルクAPI/でbulk_start.pyを保存します。 完全なスクリプトをコピーし、以下のコマンドを実行します。

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))
バルクapi/から実行
python bulk_start.py

対応機種

HTTPステータス意味する
200Bulk ジョブの開始またはその現在の重要状態
401認証が必要または無効
404発信者によって発見されていない、または所有されていないリソース
409リソースの状態または不在の競合
422リクエストの検証が失敗しました
503必要な依存性やカタログは一時的に利用できません。
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

ジョブステータスの取得

job.status、入力、カウント、pauseReasonおよび間違いを読んで下さい。 同じIDを遅延で再確認; 完了すると、マニフェストが公開されることを意味します, すべてのビデオが成功しないこと.

パラメータ地域必須条件
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-created.jsonの横のバルクAPI/でbulk_status.pyを保存します。 完全なスクリプトをコピーし、以下のコマンドを実行します。

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))
バルクapi/から実行
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

bulk-created.jsonの横のバルクAPI/でlist_bulk_jobs.pyを保存します。 完全なスクリプトをコピーし、以下のコマンドを実行します。

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))
バルクapi/から実行
python list_bulk_jobs.py

対応機種

HTTPステータス意味する
200Bulk ジョブページ
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

bulk-created.jsonの横のバルクAPI/でpause_bulk_job.pyを保存します。 完全なスクリプトをコピーし、以下のコマンドを実行します。

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))
バルクapi/から実行
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

bulk-created.jsonの横のバルクAPI/でupdate_bulk_job.pyを保存します。 完全なスクリプトをコピーし、以下のコマンドを実行します。

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))
バルクapi/から実行
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

bulk-created.jsonの横のバルクAPI/でresume_bulk_job.pyを保存します。 完全なスクリプトをコピーし、以下のコマンドを実行します。

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))
バルクapi/から実行
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

bulk-created.jsonの横のバルクAPI/でcancel_bulk_job.pyを保存します。 完全なスクリプトをコピーし、以下のコマンドを実行します。

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))
バルクapi/から実行
python cancel_bulk_job.py

対応機種

HTTPステータス意味する
200現在のバルク仕事の状態
401認証が必要または無効
404発信者によって発見されていない、または所有されていないリソース
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

結果マニフェストを入手する

リダイレクトに従って、JSONマニフェストをダウンロードし、結果ファイルを取得するリンクを使用します。 APIキーなしで署名された貯蔵URLsをフェッチして下さい。 結果は、Bulkジョブ全体が完了した後、24時間のために利用可能に残ります。

認証された API リクエストは、ロケーションヘッダで 302 を返します。 HTTPS ストレージ URL を別々のリクエストにX-API-Key を格納するフェッチ。 たとえば、manifest.json を保存します。 409 は結果が準備されていないことを意味します。 410 は期限切れを意味します。

パラメータ地域必須条件
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-created.jsonの横のバルクAPI/でbulk_manifest.pyを保存します。 完全なスクリプトをコピーし、以下のコマンドを実行します。

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))
バルクapi/から実行
python bulk_manifest.py

対応機種

HTTPステータス意味する
200JSONマニフェストはリダイレクト後にダウンロードしました
302短命プライベートR2 URLへのリダイレクト; APIの資格情報は転送されません · Location
401認証が必要または無効
404発信者によって発見されていない、または所有されていないリソース
409リソースの状態または不在の競合
410保持された結果が期限切れになりました
200 · application/json
{
  "type": "object",
  "additionalProperties": true
}

結果の部品をダウンロード

manifest.jsonから各parts[].numberを使用してください。 各エンドポイントは、302をgzip NDJSONファイルに戻ります。 APIキーなしでダウンロードし、解凍し、ラインごとに1つのJSONオブジェクトを解析します。 ゼロベースインデックスで登録してください。 この例では、すべての部品を取り出し、.ndjson.gz と .ndjson ファイルの両方を保持します。

パラメータ地域必須条件
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-created.jsonの横のバルクAPI/でbulk_parts.pyを保存します。 完全なスクリプトをコピーし、以下のコマンドを実行します。

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)))
バルクapi/から実行
python bulk_parts.py

対応機種

HTTPステータス意味する
200リダイレクト後にダウンロードしたGzip-compressed NDJSON
302短命プライベートR2 URLへのリダイレクト; APIの資格情報は転送されません · Location
401認証が必要または無効
404発信者によって発見されていない、または所有されていないリソース
409リソースの状態または不在の競合
410保持された結果が期限切れになりました
200 · application/x-ndjson
{
  "type": "string"
}

ジョブの状態と保持

結果は、Bulkジョブ全体が完了した後、24時間のために利用可能に残ります。 expiresAtの前にそれらを保存します。 目的地のメディアは、あなたのバケットの保持ポリシーに従います。 完了したジョブには、失敗したビデオが含まれている場合があります。counts.invalidレコードは入力行を拒否しました。

ステート次のアクション
awaiting_uploadファイルをアップロードし、開始を呼び出します。
runningバックオフと同じ ID を出力します。 input.complete はスキャンが終了するかどうかを示します。
pausedpauseReasonを読んで、それを修正してから、再開します。
finalizing結果の包装とマニフェストの出版物を待ってください。
completedマニフェストとすべての部分をダウンロードします。 各行のステータスとエラーを調べます。
failed / cancelledエラーを調べて保存した状態を調べます。 最終マニフェストは公開されていません。

貯蔵の配達

プレイグラウンドを使用して、プロバイダを設定し、正確なリクエストフィールドをプレビューします。 顧客ストレージの資格情報は、選択したストレージオブジェクトに所属しています。 X-API-KeyはFlashData APIリクエストのみを認証します。

ソースフィールドリクエストを作成する配送について
メタデータ、トランスクリプト、キャプション、ライセンスチェックoptions.result_storageオプション。 Copies NDJSON 結果の部分とあなたのバケツにマニフェスト.
youtube_downloadoptions.storage必須項目 result_storage と browser_delivery のメディアは受け付けていません。

配信されたファイルを見つける

データマニフェストは、最後に書かれており、オブジェクトキー、サイズ、およびSHA-256チェックサムをリストします。 FlashDataマニフェストとは違い、API href値がリストされます。 データパスのYYYMMDDはUTC Bulk作成日を使用します。メディアパスでは、各ビデオのUTCアップロード日を使用します。 Bulk OSSのデータ配信には、aliyuncs.comエンドポイントが必要です。

プライベートメディア file_url は、ストレージ SDK や、そのプロバイダから署名された URL を必要とします。 FlashDataキーは、バケットアクセスを付与しません。 必要に応じてメタデータコンパニオンファイルがメディアの横に保存されます。 delivery.retryCountに配達retriesが現れます。

データオブジェクトのレイアウト
<prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz
<prefix>/<source>/<bulkId>/manifest.json

完成したwebhookを受け取る

HTTPS callback_urlの外部オプションを配置します。 Bulk はマニフェストを出版した後にのみ完了します。それは、失敗またはキャンセルされたジョブのためのビデオイベントや完了イベントを送信しません。 ステータスをフォールバックとしてポーリングしてください。

  1. 主張し、重複する delivery_id2xx を速やかに返します。 バックオフで最大8回まで配送。
  2. イベントは無事です。 保存されたレシートにidとソースを一致させます。 認証された管理APIで完了して、検索結果をキューイングします。 URLsを統一したイベントから無視します。
コールバックで作成する
{
  "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."
    }
  }
}