OpenAI Batch API JSONL 格式指南

學習如何建構 JSONL 檔案以使用 OpenAI 的 Batch API，節省 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 等參數。

單一請求

每一行包含一個完整的聊天補全請求，包括 model、messages 和可選參數。

單一請求
{"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。

嵌入向量請求使用更簡單的 body 結構，包含 model 和輸入文字。

嵌入向量請求格式
{"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}

錯誤回應

失敗的請求包含一個 error 物件，帶有錯誤代碼和說明出錯原因的訊息。

錯誤回應
{"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
費用
5 折優惠
標準定價
延遲
最多 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