OpenAI Batch API 怎么用？JSONL 批量请求、24 小时任务与成本核算教程（2026）

如果你需要一次处理几百、几千甚至更多条摘要、分类、翻译或评测任务，逐条同步调用 API 往往会遇到并发限制、超时和成本难以控制的问题。Batch API 的思路是先把请求写入 JSONL 文件，再提交一个异步批处理任务，等任务完成后下载结果。

本文按照“准备 Key → 生成 JSONL → 上传 → 提交任务 → 查询和下载 → 处理失败”的顺序整理。批处理的模型、终点、价格、完成时间和文件限制会随官方文档调整；正式运行前，请以 OpenAI Batch API 官方文档 与 官方价格页 的当前说明为准。

先确认 API 入口

如果你还没有 API 项目，可先阅读本站的 ChatGPT API Key 与 Responses API 教程，了解 ChatGPT Plus 与 API 的区别、项目 Key 和安全配置。需要比较多模型兼容网关时，可以查看 ZeoAPI 注册入口，但它是独立第三方服务，不是 OpenAI 官方 API；Base URL、模型路由、价格、额度、日志和数据规则应以登录后的页面与服务条款为准。

一、Batch API 适合什么任务

Batch API 适合不要求用户立即看到结果、可以排队等待的离线工作：

任务	示例	提交前要固定的内容
文档处理	给 10 万条商品描述打标签	输入字段、标签集合、输出格式
内容生成	批量生成标题、摘要或翻译	语言、长度、禁止项和验收规则
数据评测	对问答集做分类或评分	评分标准、模型和版本
RAG 预处理	为知识库片段生成摘要或关键词	分块 ID、来源和去重规则

实时客服、登录验证、支付确认和用户正在等待的对话，通常应该使用普通的 Responses API 或流式请求。Batch 任务是异步的，不能当成同步接口等待即时返回。

二、开始前的准备

1. 在 OpenAI Platform 创建项目并生成 API Key；
2. 确认项目已经具备账单、模型和文件 API 权限；
3. 在 Models 页面复制项目实际可用的模型 ID；
4. 准备一组不含密钥、身份证号、银行卡号和客户隐私的测试数据；
5. 先提交 2～5 条小批次，确认输出格式和费用后再扩大规模。

API Key 只应放在服务器环境变量中：

$env:OPENAI_API_KEY = "你的项目密钥"
$env:OPENAI_MODEL = "控制台显示的模型 ID"

不要把真实 Key 写入 JSONL、Markdown、截图、前端代码或 Git 仓库。Batch 输入文件本身也可能含有用户资料，上传前要做脱敏和访问控制。

三、JSONL 文件怎么写

Batch 输入文件是一行一个 JSON 对象。每条请求至少要有一个唯一的 custom_id、请求方法、目标路径和请求体。下面示例使用 Responses API 的批量终点；终点和请求体字段应以官方文档当前示例为准：

{"custom_id":"summary-001","method":"POST","url":"/v1/responses","body":{"model":"MODEL_ID","input":"把这段会议记录整理成 3 条行动项：……"}}
{"custom_id":"summary-002","method":"POST","url":"/v1/responses","body":{"model":"MODEL_ID","input":"用一句话概括这份产品说明：……"}}

注意四点：

• 每行必须是独立、合法的 JSON，不能把整个文件写成一个 JSON 数组；
• custom_id 要稳定且唯一，建议包含业务记录 ID，不要用可能重复的随机短数字；
• MODEL_ID 只是占位符，提交前必须替换为项目当前可用的模型；
• 先限制输入长度和输出格式，避免一条异常数据拖累整个批次。

用 Python 生成 JSONL

import json
from pathlib import Path

model = "MODEL_ID"  # 替换成 Models 页面中项目可用的 ID
records = [
    {"id": "p-001", "text": "第一条待处理内容"},
    {"id": "p-002", "text": "第二条待处理内容"},
]

with Path("batch_input.jsonl").open("w", encoding="utf-8") as f:
    for item in records:
        row = {
            "custom_id": f"summary-{item['id']}",
            "method": "POST",
            "url": "/v1/responses",
            "body": {
                "model": model,
                "input": f"请用一句话摘要：{item['text']}",
            },
        }
        f.write(json.dumps(row, ensure_ascii=False) + "\n")

生成后先逐行解析并统计行数，确认没有空行、重复 ID 或意外的敏感字段，再上传文件。

四、上传文件并提交批处理任务

可以通过官方 SDK 或 HTTP 客户端完成上传。下面是 Python SDK 的示意流程，SDK 方法名和参数以当前 Files API 文档 与 Batch 文档为准：

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

with open("batch_input.jsonl", "rb") as f:
    input_file = client.files.create(file=f, purpose="batch")

batch = client.batches.create(
    input_file_id=input_file.id,
    endpoint="/v1/responses",
    completion_window="24h",
    metadata={"job": "summary-demo"},
)

print(batch.id, batch.status)

提交后保存 batch.id、输入文件 ID、提交时间、代码版本和本批次的业务范围。不要只依赖终端输出；生产系统应把这些信息写入自己的任务表，便于查询、重跑和审计。

五、查询状态与下载结果

批处理通常会经历验证、排队、进行中、完成或失败等状态。轮询时设置间隔和超时，不要每秒请求一次：

import time

while True:
    batch = client.batches.retrieve(batch.id)
    print(batch.status)
    if batch.status in {"completed", "failed", "cancelled", "expired"}:
        break
    time.sleep(30)

if batch.status == "completed" and batch.output_file_id:
    content = client.files.content(batch.output_file_id).text
    with open("batch_output.jsonl", "w", encoding="utf-8") as f:
        f.write(content)

if batch.error_file_id:
    errors = client.files.content(batch.error_file_id).text
    with open("batch_errors.jsonl", "w", encoding="utf-8") as f:
        f.write(errors)

输出顺序不一定与输入文件相同，因此必须根据 custom_id 回写到原业务记录，不能按行号直接覆盖数据库。先把结果落到临时表，校验数量、ID、错误字段和空结果，再合并到正式数据。

六、失败请求如何重试

Batch 完成后可能出现部分成功、部分失败。建议按下面的顺序处理：

1. 读取错误文件，按 HTTP 状态码和 custom_id 分组；
2. 修复输入格式、模型 ID、超长内容等确定性错误；
3. 只把可重试的限流、暂时性服务错误加入新批次；
4. 给重试任务增加后缀，例如 summary-p-001-retry-1；
5. 设置最大重试次数和总预算，避免坏数据无限循环。

401、403、模型不存在和 JSON 格式错误，通常需要修配置，反复提交不会修好。遇到 429 或暂时性 5xx，应查看响应信息后采用有上限的退避策略。生产任务还要记录输入哈希，防止重试造成重复写入。

七、成本、时效和配额怎么估算

Batch API 的核心价值是把可等待的任务集中处理，并根据官方当前规则核算费用。不要直接把旧文章里的固定单价复制到项目预算。上线前至少记录：

• 输入与输出 token 的估算值；
• 预计条数、最大输出长度和失败重试比例；
• 模型、缓存策略和批处理窗口；
• 文件大小、任务数、并发和项目限额；
• 实际 Usage、失败率和每条业务记录的平均成本。

可以先抽样 100 条做成本测试：

估算成本 ≈ 成功请求数 × 单条平均输入/输出用量 × 官方当前单价
          + 重试请求用量 + 文件与工具相关费用（如适用）

真实账单以 OpenAI Pricing 与项目 Usage 页面为准。若使用第三方兼容平台，第三方平台的价格、倍率、队列和数据保留规则要单独核对，不能与官方 Batch API 直接等同。

八、批处理的安全与质量检查

• 文件上传前删除 Key、Cookie、身份证号、联系方式和客户原文中的不必要字段；
• 只给任务服务账号必要的文件和项目权限；
• 结果先人工抽查，再写入搜索索引、账务或对外内容；
• 对自动生成的分类和摘要保留原文 ID、模型 ID、时间和版本；
• 设置最大文件、条数、并发、重试和总费用；
• 任务完成后按保留政策删除输入、输出和错误文件。

如果结果会触发退款、删库、发邮件或修改生产数据，先进入人工审核队列。批量完成并不等于业务事实正确。

九、和普通 Responses API 怎么选

需求	推荐方式
用户等待几秒钟得到回答	Responses API 或流式请求
夜间批量摘要、分类、评测	Batch API
需要实时工具调用	普通 Responses API，单独设计工具权限
结果可以延迟、希望统一管理任务	Batch API + 任务表

如果你还在设计第一版应用，可以先阅读 GPT-6 API 与自动化工作流教程，了解模型适配器、结构化输出、工具调用和错误处理；Batch API 更适合把已经验证过的单条请求扩展到离线队列。

常见问题 FAQ

Batch API 是实时接口吗？

不是。它是异步批处理，提交后需要查询状态，完成后再下载结果。需要即时回复的网页对话不适合用 Batch API。

JSONL 和 JSON 数组有什么区别？

JSONL 是每行一个独立 JSON 对象，适合流式生成和逐条定位错误；不能把多条记录包成一个数组再上传。

输出结果会按输入顺序返回吗？

不应假定会。使用 custom_id 将输出和原业务记录关联。

任务失败后可以直接再次提交吗？

先读错误文件并修复原因，只重试安全可重试的记录。为重试记录生成新的 ID，并设置上限。

Batch API 一定比普通 API 便宜吗？

是否便宜、如何计费以官方当前价格页和项目账单为准。还要把重试、失败、缓存、工具和数据处理费用纳入估算。

可以把第三方兼容平台当成官方 Batch API 吗？

不能直接等同。第三方平台可能只兼容普通 Chat Completions 或部分接口；是否支持文件上传、批处理、Responses API 和结果下载，要以其实时文档为准。

官方来源与站内相关阅读

• OpenAI Batch API 官方指南
• OpenAI Files API 官方指南
• OpenAI API Quickstart
• OpenAI API 模型目录
• OpenAI API 价格页
• ChatGPT API Key 与 Responses API 教程
• GPT-6 API 与自动化工作流教程
• Gemini API Key 与 400/403/429 排错

核查日期：2026 年 10 月 9 日。 OpenAI 的模型、接口、文件限制、批处理窗口、价格和可用地区可能变化，实际接入前请以官方文档与登录后的项目控制台为准。

---