著者: Jerry Fan

OpenAI Batch API の JSONL フォーマットガイド

OpenAI の Batch API でコストを 50% 削減するための JSONL ファイルの作り方を解説します

OpenAI Batch API とは?

OpenAI Batch API を使うと、大量の API リクエストを1つのバッチジョブにまとめて送信できます。個別に数千回の API 呼び出しを行う代わりに、すべてのリクエストを記述した JSONL ファイルをアップロードすると、OpenAI が 24 時間以内に非同期で処理します。

最大のメリットは、コストを削減できることです。バッチリクエストの料金は、リアルタイムの API 呼び出しより 50% 安くなります。そのため、コンテンツ生成、データ分類、埋め込みベクトルの計算、評価パイプラインなど、すぐにレスポンスを必要としないタスクに適しています。

バッチファイルの準備

OpenAI に送信する前に、無料ツールで JSONL バッチファイルを作成・検証し、内容を確認できます。

JSONL リクエストのフォーマット

バッチ処理の入力となる JSONL ファイルには、1行につき1つの API リクエストを記述します。各行は決められた構造に従い、3つの必須フィールドを含める必要があります。

custom_id — リクエストごとの一意な識別子です。リクエストとレスポンスを対応付けるために使います。512文字以内の任意の文字列を指定できます。
method — HTTP メソッドです。現在サポートされているのは POST のみです。
url — API エンドポイントのパスです。Chat Completions では /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 の最も一般的な用途は、複数の Chat Completions リクエストをまとめて送信することです。各行には、model、messages と、必要に応じて max_tokens や temperature などの任意パラメータを指定し、1件分のリクエストをすべて記述します。

1件のリクエスト

各行には、model、messages、任意パラメータを含め、1件分の Chat Completions リクエストをすべて記述します。

1件のリクエスト
{"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つの異なるタスクを記述した例です。

複数のリクエストを記述した 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 エンドポイントを指定します。

埋め込みベクトルの生成リクエストでは、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 ファイルが提供されます。各行には1件のリクエストに対するレスポンスが格納されます。レスポンスには元の 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 ファイルの作成から結果のダウンロードと解析まで、5つのステップで紹介します。

  1. 11行につき1つのリクエストを記述した JSONL ファイルを作成します
  2. 2purpose を batch に設定し、Files API でファイルをアップロードします
  3. 3アップロードしたファイルの ID を指定して、バッチジョブを作成します
  4. 4バッチのステータスが completed、failed、cancelled のいずれかになるまでポーリングします
  5. 5出力 JSONL ファイルをダウンロードして解析し、結果を取り出します
Batch API を使う一連の手順
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 フォーマットガイド.

JSONL ファイルをオンラインで扱う

最大 1GB の JSONL ファイルをブラウザ上で表示・検証・変換できます。アップロードは不要で、プライバシーは 100% 守られます。

よくある質問

参考資料