OpenAI Batch API JSONL 格式指南

学习如何构建 OpenAI Batch API 的 JSONL 文件，节省 50% 的成本

最后更新：2026年2月

什么是 OpenAI Batch API？

OpenAI Batch API 允许您将大量 API 请求作为单个批处理任务发送。无需发起数千个独立的 API 调用，您只需上传一个包含所有请求的 JSONL 文件，OpenAI 会在 24 小时内异步处理它们。

核心优势是成本：批处理请求比实时 API 调用便宜 50%。这使得 Batch API 非常适合不需要即时响应的任务，例如内容生成、数据分类、嵌入向量计算和评估管道。

JSONL 请求格式

批处理输入 JSONL 文件中的每一行代表一个 API 请求。每行必须包含三个必填字段，并遵循特定的结构。

custom_id — 每个请求的唯一标识符。用于将请求与响应匹配。可以是最长 512 个字符的任意字符串。
method — HTTP 方法。目前仅支持 POST。
url — API 端点路径。聊天补全：/v1/chat/completions。嵌入向量：/v1/embeddings。
body — 请求体。与对应 API 端点的请求体格式相同。
基本请求结构
{"custom_id": "req-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}}

聊天补全批处理

Batch API 最常见的用例是发送多个聊天补全请求。每行包含一个完整的请求，包括 model、messages 和可选参数如 max_tokens 或 temperature。

单个请求

每行包含一个完整的聊天补全请求，包括模型、消息和可选参数。

单个请求
{"custom_id": "task-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Summarize the benefits of renewable energy."}], "max_tokens": 500}}

多请求 JSONL 文件

批处理文件通常包含数百或数千个请求。以下是一个包含三个不同任务的文件：摘要、分类和翻译。

多请求 JSONL 文件
{"custom_id": "summary-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Summarize: Solar energy is a renewable source of power that harnesses sunlight using photovoltaic cells."}], "max_tokens": 200}}
{"custom_id": "classify-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Classify this review as positive or negative: Great product, works perfectly!"}], "max_tokens": 50}}
{"custom_id": "translate-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Translate to French: Hello, how are you today?"}], "max_tokens": 100}}

嵌入向量批处理

Batch API 也支持嵌入向量请求，这对于处理大型文档集合非常有用。嵌入向量批处理使用相同的 JSONL 结构，但目标端点为 /v1/embeddings。

嵌入向量请求使用更简单的请求体结构，包含模型和输入文本。

嵌入向量请求格式
{"custom_id": "embed-001", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "JSONL is a text format for storing structured data."}}
{"custom_id": "embed-002", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "Each line contains one valid JSON object."}}
{"custom_id": "embed-003", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "JSONL files use the .jsonl extension."}}

响应格式

当批处理任务完成时，OpenAI 会提供一个输出 JSONL 文件，其中每行包含一个请求的响应。响应包含原始的 custom_id，便于将响应与请求匹配。

成功响应

成功的响应包含 custom_id、响应状态码和完整的 API 响应体。

成功响应
{"id": "batch_req_abc123", "custom_id": "task-001", "response": {"status_code": 200, "body": {"id": "chatcmpl-xyz", "object": "chat.completion", "choices": [{"index": 0, "message": {"role": "assistant", "content": "Renewable energy provides numerous benefits including reduced greenhouse gas emissions, lower long-term costs, and energy independence."}}]}}, "error": null}

错误响应

失败的请求包含一个错误对象，其中有错误代码和说明原因的消息。

错误响应
{"id": "batch_req_def456", "custom_id": "task-002", "response": null, "error": {"code": "invalid_request_error", "message": "The model 'gpt-5' does not exist."}}

完整的 Batch API 工作流程

以下是使用 Python SDK 执行 Batch API 的完整五步工作流程，从创建 JSONL 文件到下载和解析结果。

  1. 1创建 JSONL 文件，每行一个请求
  2. 2使用 Files API 上传文件，purpose 设为 batch
  3. 3创建批处理任务，引用上传的文件 ID
  4. 4轮询批处理状态，直到达到 completed、failed 或 cancelled
  5. 5下载并解析输出 JSONL 文件以提取结果
Python — Batch API Workflow
from openai import OpenAI
import json
import time


client = OpenAI()


# Step 1: Create the JSONL batch file
prompts = [
    "Summarize the benefits of renewable energy.",
    "Classify this text as positive or negative: Great product!",
    "Translate to French: Hello, how are you?",
]


requests = [
    {
        "custom_id": f"req-{i}",
        "method": "POST",
        "url": "/v1/chat/completions",
        "body": {
            "model": "gpt-4o-mini",
            "messages": [{"role": "user", "content": prompt}],
            "max_tokens": 200,
        },
    }
    for i, prompt in enumerate(prompts)
]


with open("batch_input.jsonl", "w") as f:
    for req in requests:
        f.write(json.dumps(req) + "\n")


# Step 2: Upload the file
batch_file = client.files.create(
    file=open("batch_input.jsonl", "rb"),
    purpose="batch",
)


# Step 3: Create the batch
batch = client.batches.create(
    input_file_id=batch_file.id,
    endpoint="/v1/chat/completions",
    completion_window="24h",
)
print(f"Batch created: {batch.id}")


# Step 4: Poll for completion
while True:
    status = client.batches.retrieve(batch.id)
    print(f"Status: {status.status}")
    if status.status in ("completed", "failed", "cancelled"):
        break
    time.sleep(60)


# Step 5: Download results
if status.output_file_id:
    content = client.files.content(status.output_file_id)
    with open("batch_output.jsonl", "wb") as f:
        f.write(content.read())

Batch API 与实时 API 对比

了解何时使用 Batch API 而非标准实时 API，有助于同时优化成本和性能。

功能
Batch API
实时 API
成本
50% 折扣
标准定价
延迟
最多 24 小时
秒级
速率限制
更高的限制
标准限制
输入格式
上传 JSONL 文件
单独的 API 调用
最适合
批量处理、评估、数据生成
交互式应用、实时聊天、流式传输

有关 OpenAI 微调的 JSONL 格式详情，请参阅我们的 OpenAI JSONL 格式指南.

准备您的批处理文件

使用我们的免费工具在提交到 OpenAI 之前创建、验证和检查您的 JSONL 批处理文件。

OpenAI JSONL format guide
JSONL splitter
JSONL validator

在线处理 JSONL 文件

直接在浏览器中查看、验证和转换最大 1GB 的 JSONL 文件。无需上传，100% 私密。

常见问题

OpenAI Batch API JSONL 格式 — 请求、响应与限制 | jsonl.co