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 ファイルの各行は1つの API リクエストを表します。すべての行には3つの必須フィールドが含まれ、特定の構造に従います。
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"}]}}
Chat Completions バッチ
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 ファイル
バッチファイルには通常、数百〜数千のリクエストが含まれます。以下は要約、分類、翻訳の3つの異なるタスクを含むファイルです。
{"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}}
Embeddings バッチ
Batch API はエンベディングリクエストもサポートしており、大規模なドキュメントコレクションの処理に便利です。エンベディングバッチは同じ JSONL 構造を使用しますが、/v1/embeddings エンドポイントを対象とします。
エンベディングリクエストは 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}
エラーレスポンス
失敗したリクエストには、問題の原因を説明するコードとメッセージを含むエラーオブジェクトが含まれます。
{"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 ワークフロー
以下は、JSONL ファイルの作成から結果のダウンロードと解析まで、Python SDK を使用した Batch API の完全な5ステップワークフローです。
- 11行に1リクエストの JSONL ファイルを作成
- 2Files API を使用して purpose を batch に設定してファイルをアップロード
- 3アップロードしたファイル ID を参照してバッチジョブを作成
- 4バッチステータスが completed、failed、または cancelled になるまでポーリング
- 5出力 JSONL ファイルをダウンロードして解析し、結果を抽出
from openai import OpenAIimport jsonimport timeclient = OpenAI()# Step 1: Create the JSONL batch fileprompts = ["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 filebatch_file = client.files.create(file=open("batch_input.jsonl", "rb"),purpose="batch",)# Step 3: Create the batchbatch = 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 completionwhile True:status = client.batches.retrieve(batch.id)print(f"Status: {status.status}")if status.status in ("completed", "failed", "cancelled"):breaktime.sleep(60)# Step 5: Download resultsif 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 と Real-time API の比較
Batch API と標準のリアルタイム API のどちらを使用すべきかを理解することで、コストとパフォーマンスの両方を最適化できます。
OpenAI ファインチューニング用の JSONL フォーマットの詳細については、 OpenAI JSONL フォーマットガイド.
バッチファイルを準備する
無料ツールを使用して、OpenAI に送信する前に JSONL バッチファイルの作成、検証、確認を行えます。