本文根據 OpenAI 官方《Batch API》整理，資料核對於 2026-11-05。配圖為本站整理的示意圖，不是介面截圖。代碼裏的模型名取自官方當天示例，請以官方模型頁為準。本站（bigolab.com）不是 OpenAI 官方網站。API 是按用量計費的獨立服務，與 ChatGPT 訂閱分開計算，Key 的獲取見 /guides/openai-api-key。
適用於誰
- 有一大批不需要馬上出結果的任務：給幾千條評論分類、跑一遍評測、給內容庫批量做向量；
- 同步請求被限速卡住（見 /guides/openai-api-429-error），想換一條獨立限額的通道的人；
- 想在不改提示詞的前提下降低成本的人。
結論先說
- Batch API 是異步的：你把一批請求寫進一個
.jsonl文件，上載後創建批處理，過一陣再取結果。 - 官方在頁面上寫明三個好處：費用比同步接口低 50%；有獨立的、高得多的限速池；每個批次 24 小時內完成，往往更快。這是官方 2026-11-05 的寫法，價格以官方頁面當天為準，見 /guides/openai-api-price-official-table。
- 不適合要立刻看到結果的場景，比如聊天。
- 結果順序可能和輸入不同，必須用每個請求裏的
custom_id來對應。 - 同一個輸入文件只能用一個模型。
圖：本站根據 OpenAI 官方《Batch API》 整理的示意圖
一、準備 jsonl 文件
jsonl 是“每行一個 JSON”。每行是一個完整請求，含 custom_id（你自己起的唯一編號）、method、url 和 body。body 裏的參數就和直接調用那個端點時一樣。官方的兩行示例：
{"custom_id": "request-1", "method": "POST", "url": "/v1/responses", "body": {"model": "gpt-6-luna", "input": "Reply with the word blue.", "reasoning": {"effort": "none"}, "max_output_tokens": 64}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/responses", "body": {"model": "gpt-6-luna", "input": "Reply with the word green.", "reasoning": {"effort": "none"}, "max_output_tokens": 64}}官方列出的可用端點有：/v1/responses、/v1/chat/completions、/v1/embeddings、/v1/completions、/v1/moderations、/v1/images/generations、/v1/images/edits。
幾條規矩：
- 每個
custom_id必須唯一； - 一個文件只能含一個模型的請求，要用兩個模型就拆成兩個批次；
- 做 embeddings 時，一個批次的嵌入輸入總數同樣最多 50,000；
- 帶圖片時，官方建議盡量用
image_url引用遠程圖，而不是把 Base64 內容塞進文件，免得文件超過 200 MB 的上載上限。
二、一份完整的 Python 腳本
下面把官方的幾個步驟按順序串起來。輪詢等待和解析結果的部分是本站補充：
python
import json
import time
from openai import OpenAI
client = OpenAI()
# 1. 上載輸入文件，purpose 要填 batch
batch_input_file = client.files.create(
file=open("batchinput.jsonl", "rb"),
purpose="batch",
)
# 2. 創建批處理，completion_window 目前只能是 24h
batch = client.batches.create(
input_file_id=batch_input_file.id,
endpoint="/v1/responses",
completion_window="24h",
metadata={"description": "nightly eval job"},
)
print("批次編號：", batch.id, "狀態：", batch.status)
# 3. 定時查詢狀態（也可以過幾小時再手動查）
while batch.status in ("validating", "in_progress", "finalizing"):
time.sleep(60)
batch = client.batches.retrieve(batch.id)
print("狀態：", batch.status)
# 4. 讀取結果；輸出順序可能和輸入不同，用 custom_id 對應
if batch.output_file_id:
text = client.files.content(batch.output_file_id).text
for line in text.splitlines():
row = json.loads(line)
body = row["response"]["body"]
for item in body["output"]:
if item["type"] == "message":
print(row["custom_id"], item["content"][0]["text"])
# 5. 失敗的請求在 error_file_id 裏
if batch.error_file_id:
print(client.files.content(batch.error_file_id).text)Node.js 的調用方法名對應是 openai.files.create、openai.batches.create、openai.batches.retrieve、openai.files.content，參數名與上面一致，官方頁面有各步驟的 Node 示例。
三、狀態有哪些
官方列出的狀態：
validating：正在校驗輸入文件；failed：輸入文件沒有通過校驗；in_progress：校驗通過，正在運行；finalizing：已跑完，正在準備結果；completed：完成，結果可取；expired：24 小時窗口內沒跑完；cancelling：正在取消，最長可能要 10 分鐘；cancelled：已取消。
圖：本站根據 OpenAI 官方《Batch API》 整理的示意圖
四、結果和失敗的請求
輸出文件裏，成功的請求每個對應一行，裏面有 custom_id 和 response。失敗的請求資訊寫在錯誤文件裏，通過批次對象的 error_file_id 取。官方還說：輸出文件會在批次完成 30 天后自動刪除，需要的話要及時下載儲存。
結果裏的文字要從 response.body.output 裏讀 output_text 內容，這對應上面腳本里的解析部分。
五、過期與取消
- 取消：調用取消後狀態先變成
cancelling，等執行中的請求結束（最長約 10 分鐘）後變成cancelled； - 過期：沒在 24 小時內完成的批次進入
expired，未完成的請求被取消；已經完成的請求結果仍在輸出文件裏，這部分消耗的 token 會計費。過期的請求會寫進錯誤文件，錯誤碼是batch_expired，可以用custom_id找回它們的原始請求，再重新提交。
六、限額
官方說 Batch 有獨立的限速池，有三類限制：
- 單個批次：最多 50,000 個請求，輸入文件最大 200 MB；
- 每個模型的排隊 prompt token 數：具體數字在平台設定裏的限額頁面查看；
- 創建頻率：每小時最多創建 2,000 個批次。請求更多時，應該增加每個批次裏的請求數，而不是多建批次。
官方還說目前沒有輸出 token 的上限，並且用 Batch 不會消耗你常規的按模型限速額度，所以它也是提高處理量的一個辦法。想知道自己帳號的層級和提額條件，見 /guides/openai-api-usage-tiers-rate-limits。
常見問題
Q：所有模型都支持 Batch 嗎？
官方說大多數模型支持，具體看模型參考頁。圖像生成方面，官方頁面列出了 GPT Image 系列的部分模型支持批量生成和編輯，名稱以官方當天頁面為準。
Q：批次一直是 validating 或最後 failed？
failed 表示輸入文件沒通過校驗。先檢查 jsonl 是不是每行一個完整 JSON、custom_id 是否重複、整個文件是否只有一個模型、url 是否和創建批處理時的 endpoint 一致。這幾條裏前三條來自官方規則，最後一條是本站的合理推斷，官方沒有逐條列出校驗項。
Q：能隨時看到進度嗎？
批次對象裏有 request_counts，包含總數、已完成數、失敗數，查詢狀態時可以一併看到。
Q：怎麼用 Batch 做向量化？
端點選 /v1/embeddings，向量的用法見 /guides/openai-api-embeddings。
參考資料
- OpenAI 官方：Batch API — https://developers.openai.com/api/docs/guides/batch
0 條評論
還沒有評論，來搶沙發～