跳转到正文
中文
获取 API 密钥
浏览文档

API 参考

Bulk 处理 API

创建和控制基于文件的 YouTube 任务,再获取清单与结果分片。

本页内容

API Playground

选择来源,复制完整 Python 或 Bash 工作流、单个请求或响应示例。Playground 仅预览代码,不会提交任务。完整工作流包含上传、状态检查和所有结果分片获取。

数据源参数

构建文件批处理流程

本地 UTF-8 文件,每行一个 YouTube ID,最大 2 GiB。 输入要求.

结果交付

关闭此选项时,通过 FlashData API 获取结果。

文件批处理完成 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-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 下载需要所有者访问与 options.storage。

创建 bulk-api/ 工作目录,在其中运行示例。Playground 的完整 Python 工作流使用 Python 3.10+ 标准库;下方各端点的 Python 示例需要 Requests;cURL 示例使用 Bash、cURL 7.76+、jq 和 gzip。每个操作选择一种语言,避免重复创建或启动任务。

输入为最大 2 GiB 的 UTF-8 文件,每行一个 11 字符 YouTube ID。使用 ID,不使用 URL。上传前去重,重复 ID 会分别处理。

来源共用选项
youtube_metadatainclude_formats, include_chapters
youtube_transcriptlanguage, auto
youtube_captionslanguage, auto
youtube_trainability无选项
youtube_download媒体选项与存储目标位置
Python 依赖
python -m pip install requests

创建请求字段

字段类型用途
sourcestring必填。为全部输入 ID 选择一种支持的来源。
optionsobject共用来源选项。数据来源可设置 result_storage;YouTube 下载必须设置 storage。
callback_urlstring可选的公开 HTTPS 完成回调,在清单发布后发送。

创建 Bulk 任务

创建任务,将每行包含一个 11 位 YouTube 视频 ID 的 UTF-8 文本文件上传至 upload.href,再调用 start。仅创建任务不会开始处理。

此示例写入 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_create.py 保存到 bulk-api/,与 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))
在 bulk-api/ 中运行
python bulk_create.py

响应与请求结构

HTTP 状态含义
201文件批处理任务已创建,并提供有效期为 15 分钟的直接上传 URL
401需要身份验证,或身份验证无效
422请求校验失败
503必需的依赖项或目录暂时不可用
请求体
{
  "$ref": "#/components/schemas/CreateBulkJobRequest"
}
201 · application/json
{
  "$ref": "#/components/schemas/BulkJobCreated"
}

上传并启动

开始处理已上传的 UTF-8 视频 ID 文件,最大支持 2 GiB(2147483648 字节)。开始后请勿更改输入文件。

先使用 upload.contentType 将 video-ids.txt PUT 到回执中的 upload.href,不发送 X-API-Key。示例仅在上传成功后调用 start。启动后保持上传文件不变。

参数位置要求
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 保存到 bulk-api/,与 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))
在 bulk-api/ 中运行
python bulk_start.py

响应

HTTP 状态含义
200文件批处理任务已启动,或返回其当前幂等状态
401需要身份验证,或身份验证无效
404未找到资源,或资源不属于调用者
409资源状态或幂等性冲突
422请求校验失败
503必需的依赖项或目录暂时不可用
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

获取任务状态

读取 job.status、input、counts、pauseReason 与 error。间隔一段时间后检查同一 ID;completed 表示清单已发布,不表示每个视频都成功。

参数位置要求
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 保存到 bulk-api/,与 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))
在 bulk-api/ 中运行
python bulk_status.py

响应

HTTP 状态含义
200文件批处理任务状态
401需要身份验证,或身份验证无效
404未找到资源,或资源不属于调用者
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

列出任务

响应包含 data 与 pagination。将 pagination.nextCursor 作为下一次请求的 cursor 查询参数,直到它为 null。limit 范围为 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 保存到 bulk-api/,与 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))
在 bulk-api/ 中运行
python list_bulk_jobs.py

响应

HTTP 状态含义
200文件批处理任务页面
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 保存到 bulk-api/,与 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))
在 bulk-api/ 中运行
python pause_bulk_job.py

响应

HTTP 状态含义
200已暂停的文件批处理任务或其当前幂等状态
401需要身份验证,或身份验证无效
404未找到资源,或资源不属于调用者
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

更新任务选项

可在等待上传时,或已暂停且尚未读取全部输入时更新 options。已提交的任务保持原设置。如暂停尚未完成并返回 409,请等待后重试。读取全部输入后仅允许更新交付凭据。将 callback_url 设为 null 可移除回调。

此示例移除完成回调。修改来源选项时改为发送 options 对象。先暂停并等待暂停生效;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 保存到 bulk-api/,与 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))
在 bulk-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

将 resume_bulk_job.py 保存到 bulk-api/,与 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))
在 bulk-api/ 中运行
python resume_bulk_job.py

响应

HTTP 状态含义
200当前文件批处理任务状态
401需要身份验证,或身份验证无效
404未找到资源,或资源不属于调用者
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

取消任务

停止提交新任务。已提交的任务仍可能完成并正常计费。取消的任务不会发布最终清单。

参数位置要求
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 保存到 bulk-api/,与 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))
在 bulk-api/ 中运行
python cancel_bulk_job.py

响应

HTTP 状态含义
200当前文件批处理任务状态
401需要身份验证,或身份验证无效
404未找到资源,或资源不属于调用者
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

获取结果清单

跟随跳转下载 JSON 清单,再通过清单中的链接获取结果文件。访问签名存储 URL 时不要携带 API Key。结果在整个 Bulk 任务完成后保留 24 小时。

认证后的 API 请求返回 302 与 Location 头。另发请求读取该 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_manifest.py 保存到 bulk-api/,与 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))
在 bulk-api/ 中运行
python bulk_manifest.py

响应

HTTP 状态含义
200跟随跳转后下载的 JSON 清单
302重定向至短期有效的私有 R2 URL;不得转发 API 凭证 · Location
401需要身份验证,或身份验证无效
404未找到资源,或资源不属于调用者
409资源状态或幂等性冲突
410保留的结果已过期
200 · application/json
{
  "type": "object",
  "additionalProperties": true
}

下载结果分片

使用 manifest.json 中各项 parts[].number。每个端点返回 302,指向 gzip NDJSON 文件;下载时不携带 API Key,解压后逐行解析 JSON。使用从零开始的 index 匹配输入。示例获取所有分片,并保留 .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_parts.py 保存到 bulk-api/,与 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)))
在 bulk-api/ 中运行
python bulk_parts.py

响应

HTTP 状态含义
200跟随跳转后下载的 gzip 压缩 NDJSON
302重定向至短期有效的私有 R2 URL;不得转发 API 凭证 · Location
401需要身份验证,或身份验证无效
404未找到资源,或资源不属于调用者
409资源状态或幂等性冲突
410保留的结果已过期
200 · application/x-ndjson
{
  "type": "string"
}

任务状态与保留期限

结果在整个 Bulk 任务完成后保留 24 小时,请在 expiresAt 前保存。目标存储中的媒体遵循你的存储桶保留策略。已完成任务可能包含失败视频,counts.invalid 记录被拒绝的输入行。

状态下一步
awaiting_upload上传文件并调用 start。
running使用退避轮询同一 ID;input.complete 表示扫描是否完成。
paused读取并解决 pauseReason,然后恢复。
finalizing等待结果打包与清单发布。
completed下载清单与全部分片,检查每行的 status 与 error。
failed / cancelled检查 error 与已保存状态,不会发布最终清单。

存储交付

在 Playground 中配置提供商,预览完整请求字段。客户存储凭据放在对应的存储对象中;X-API-Key 仅用于认证 FlashData API 请求。

来源创建请求字段交付内容
元数据、转录文本、字幕、许可检查options.result_storage可选。将 NDJSON 结果分片与清单复制到你的存储桶。
youtube_downloadoptions.storage必需。将媒体交付到你的存储桶,不接受 result_storage 或 browser_delivery。

查找交付文件

数据清单最后写入,列出对象 key、大小与 SHA-256,与列出 API href 的 FlashData 清单不同。数据路径中的 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

接收完成 Webhook

将公网 HTTPS callback_url 放在 options 之外。Bulk 仅在清单发布后发送 completed,不发送逐视频事件,也不为 failed 或 cancelled 任务发送完成事件。保留状态轮询作为后备。

  1. 持久化并按 delivery_id 去重,然后及时返回 2xx。交付按退避策略最多尝试八次。
  2. 事件未签名。将 id 和 source 与已保存回执匹配,并通过认证的管理 API 验证 completed 后才排队获取结果。忽略未验证事件提供的 URL。
包含回调的创建请求
{
  "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."
    }
  }
}