バッチ推論

大規模言語モデル向けの Batch API は、多数の推論リクエストの非同期処理を可能にし、OpenAI API 標準と完全な互換性があります。 Batch API は、即時の推論結果が不要な場合に費用対効果の高いソリューションです。オンライン呼び出しよりも高いレート制限を提供し、24 時間という妥当な時間内に結果が提供されることを保証します。この API は次の用途に最適です。

評価とデータ分析の実施。
大規模データセットの分類。
オフラインモードでのドキュメント要約の生成。

サポートされているモデル:

クイックスタート

1. バッチファイルの準備

Batch API は入力として .jsonl 形式のファイルを使用し、各行は API 推論リクエストの詳細を表します。利用可能なエンドポイントには /v1/chat/completions と /v1/completions があります。

OpenAI API との互換性のため、endpoint パラメータを /v1/chat/completions または /v1/completions に設定してください。

各リクエストには、バッチ完了後に出力ファイル内で推論結果を特定するための一意の custom_id を含める必要があります。各行の body フィールド内のパラメータは、実際の推論リクエストパラメータとしてエンドポイントに送信されます。

単一のバッチ JSONL ファイル内のすべてのリクエストは、同じモデルを対象にする必要があります。1 つのバッチ内で異なるモデルへのリクエストを混在させないでください。

以下は 2 つのリクエストを含む入力ファイルの例です。

{"custom_id": "request-1", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "user", "content": "Hello, world!"}], "max_tokens": 400}}
{"custom_id": "request-2", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "Hello world!"}],"max_tokens": 1000}}

2. バッチ入力ファイルのアップロード

バッチ作成時に正確に参照できるように、バッチ入力ファイルをアップロードします。Files API を使用して .jsonl ファイルをアップロードし、purpose を batch に設定してください。ファイルは 15 日間保持されることに注意してください。

API key の取得方法については、API Key Management を参照してください。

コード例 Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)

batch_input_file = client.files.create(
    file=open("batch_input.jsonl", "rb"),
    purpose="batch",
)

print(batch_input_file)

Curl

export API_KEY="<Your API Key>"

curl --request POST \
  --url https://api.novita.ai/openai/v1/files \
  --header 'Authorization: Bearer ${API_KEY}' \
  --form 'file=@"/your/batch_input.jsonl"' \
  --form 'purpose="batch"'

ファイルのアップロードに成功した場合のサンプルレスポンス:

{
    "id": "file_d2co***as73c0cjd0",
    "object": "file",
    "bytes": 238,
    "filename": "batch_input.jsonl",
    "created_at": 1754894162,
    "purpose": "batch",
    "metadata": {
        "total_requests": 2
    }
}

3. バッチの作成

入力ファイルが正常にアップロードされたら、アップロード済み File オブジェクトの ID を使用してバッチを開始できます。完了ウィンドウは 24h に固定されており、現在は変更できません。コード例 Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)

batch = client.batches.create(
  input_file_id="file_d2cor0es1cas73c0cj60",
  endpoint="/v1/chat/completions",
  completion_window="24h"
)
print(batch)

Curl

export API_KEY="<Your API Key>"

curl --request POST \
  --url https://api.novita.ai/openai/v1/batches \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${API_KEY}' \
  --data '{
      "input_file_id": "file_d2co***as73c0cjd0",
      "endpoint": "/v1/chat/completions",
      "completion_window": "24h"
  }'

このリクエストは、以下の例に示すように、バッチに関するメタデータを含む Batch オブジェクトを返します。

{
    "id": "batch_d2cq***73a68lu0",
    "object": "batch",
    "endpoint": "/v1/chat/completions",
    "input_file_id": "file_d2co***as73c0cjd0",
    "output_file_id": "",
    "error_file_id": "",
    "completion_window": "24h",
    "in_progress_at": null,
    "expires_at": null,
    "finalizing_at": null,
    "completed_at": null,
    "failed_at": null,
    "expired_at": null,
    "cancelling_at": null,
    "cancelled_at": null,
    "status": "validating",
    "errors": "",
    "version": 0,
    "created_at": "2025-08-11T16:31:52.949816948+08:00",
    "updated_at": null,
    "created_by": "8f242aa1-f725-4a67-8***9-cb68025e0976",
    "created_by_key_id": "key_cc19f96c***e7390644a37da21",
    "remark": "",
    "total": 0,
    "completed": 0,
    "failed": 0,
    "metadata": null,
    "request_counts": {
        "total": 0,
        "completed": 0,
        "failed": 0
    }
}

4. バッチのステータス確認

最新のバッチ情報を取得するために、いつでもバッチのステータスを確認できます。 Batch オブジェクトのステータス列挙値は次のとおりです。

ステータス	説明
VALIDATING	バッチを開始する前に入力ファイルを検証しています
PROGRESS	バッチは処理中です
COMPLETED	バッチ処理は正常に完了しました
FAILED	バッチ処理に失敗しました
EXPIRED	バッチが期限を超過しました
CANCELLING	バッチをキャンセルしています
CANCELLED	バッチはキャンセルされました

コード例 Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)
batch = client.batches.retrieve("batch_d2cq***73a68lu0")
print(batch)

Curl

export API_KEY="<Your API Key>"

curl --request GET \
  --url https://api.novita.ai/openai/v1/batches/{batch_id} \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${API_KEY}'

5. 結果の取得

バッチ推論が完了したら、Batch オブジェクトの output_file_id フィールドを使用して結果出力ファイルをダウンロードできます。結果出力ファイルは、バッチ推論の終了から 30 日後に削除されるため、インターフェースを通じて速やかに取得してください。コード例 Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)

content = client.files.content("example-250811-1")
print(content.read())

Curl

export API_KEY="<Your API Key>"

curl --request GET \
  --url https://api.novita.ai/openai/v1/files/{file_id}/content \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${API_KEY}'

レスポンスは生のファイル内容を返します。バッチ出力ファイルでは、各行に次のようなレスポンスが含まれます。

{
  "custom_id": "request-2589",
  "error": null,
  "id": "batch_req_task_d2c",
  "response": {
    "body": {
      "id": "29e1432c-edfb-44a4-b531-c23c600abfae",
      "object": "chat.completion",
      "created": 1754902266,
      "model": "deepseek-test",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "Hello! 👋 How can I assist you today? 😊"
          },
          "finish_reason": "stop"
        }
      ],
      "usage": {
        "prompt_tokens": 5,
        "completion_tokens": 13,
        "total_tokens": 18
      }
    },
    "request_id": "request-2589",
    "status_code": 200
  }
}

手順

制限事項

各バッチには最大 50,000 件のリクエストを含めることができます。
バッチあたりの最大入力ファイルサイズは 100MB です。

エラー処理

バッチ処理中に発生したエラーは別のエラーファイルに記録され、error_file_id フィールドからアクセスできます。一般的なエラーコードは次のとおりです。

エラーコード	説明	解決策
400	無効なリクエスト形式	JSONL 構文と必須フィールドを確認してください
401	認証に失敗しました	API key を確認してください
404	バッチが見つかりません	batch ID を確認してください
429	レート制限を超過しました	リクエスト頻度を下げてください
500	サーバーエラー	お問い合わせください

バッチの有効期限切れ

24 時間以内に完了しなかったバッチは EXPIRED 状態に移行します。未完了のリクエストはキャンセルされ、完了済みのリクエストは出力ファイルを通じて提供されます。料金は完了したリクエストによって消費されたトークンに対してのみ発生します。バッチは 24 時間以内に完了するよう最大限努めます。

Get started

Model APIs

Agent Sandbox

GPUs

Observability

Resources

クイックスタート

1. バッチファイルの準備

2. バッチ入力ファイルのアップロード

3. バッチの作成

4. バッチのステータス確認

5. 結果の取得

手順

制限事項

エラー処理

バッチの有効期限切れ

すべての Batch API

​クイックスタート

​1. バッチファイルの準備

​2. バッチ入力ファイルのアップロード

​3. バッチの作成

​4. バッチのステータス確認

​5. 結果の取得

​手順

​制限事項

​エラー処理

​バッチの有効期限切れ

​すべての Batch API

クイックスタート

1. バッチファイルの準備

2. バッチ入力ファイルのアップロード

3. バッチの作成

4. バッチのステータス確認

5. 結果の取得

手順

制限事項

エラー処理

バッチの有効期限切れ

すべての Batch API