Thunderbit Open API home page
支持API 控制台
指南

批量任务生命周期

同步 vs 异步、任务状态、部分结果与 Webhook

批量端点（/batch/distill、/batch/extract）是异步的。任务会在一个小型状态机中流转；理解这些状态有助于你在轮询和 Webhook 之间做选择，以及决定如何处理部分失败。

同步 vs 异步

同步（/distill、/extract）异步（/batch/distill、/batch/extract）
单次请求 URL 数1最多 100
响应HTTP 响应体里直接给完整结果返回任务 ID；结果单独拉
延迟一次请求、一次等待提交 → 轮询或 Webhook → 拉结果
适用场景实时 UX、Agent 工具、临时查询定时任务、RAG 入库、监控
失败模式一个坏 URL 让整次调用失败一个坏 URL 只让那一行失败，任务继续
并发开销每次调用占一个并发槽整个批量任务只占一个并发槽

拿不准时：单 URL → 同步；多 URL 或不急 → 异步。

任务状态

Status含义
PENDING任务已接收、排队中
PROCESSING至少有一个 URL 正在处理
COMPLETED所有 URL 都到达终态（成功或失败）
FAILED任务级致命错误（罕见 —— 通常只是单个 URL 失败，而不是整个任务）
CANCELLED用户通过 DELETE 主动取消

某个 URL 失败不会让任务失败。results[] 里每一项都自带 status：PENDING、PROCESSING、SUCCEEDED 或 FAILED。所有行都到达终态后，任务才转入 COMPLETED。

轮询 vs Webhook

任务规模推荐方式理由
< 10 URL每 5–10 秒轮询接 Webhook 的成本不划算
10–100 URLWebhook一个 5 分钟任务轮询要烧约 60 次往返
> 100 URL（多个批次）Webhook每个批次完成时只触发一次

Payload 形态、签名校验（HMAC-SHA256）和重试行为详见 Webhooks。

部分结果

任务还在 PROCESSING 时也能调 GET /batch/distill/{id} —— 你能拿到目前为止已完成的部分。适合那些行处理完就往前推的流式仪表盘。

import httpx, time

API = "https://openapi.thunderbit.com/openapi/v1"
H = {"Authorization": "Bearer YOUR_API_KEY"}

job = httpx.post(f"{API}/batch/distill", headers=H,
                 json={"urls": urls}).json()
batch_id = job["data"]["id"]

while True:
    body = httpx.get(f"{API}/batch/distill/{batch_id}", headers=H).json()["data"]
    fresh = [r for r in body["results"] if r["status"] == "SUCCEEDED"]
    yield_to_dashboard(fresh)
    if body["status"] in ("COMPLETED", "FAILED", "CANCELLED"):
        break
    time.sleep(5)

取消

DELETE /batch/distill/{id}（或 /batch/extract/{id}）只对 PENDING 或 PROCESSING 中的任务有效。任务一旦到达终态就停在那。被取消任务里已处理完的 URL 仍会计费；尚未完成的在途 URL 不计费。

目录

同步 vs 异步任务状态轮询 vs Webhook部分结果取消