ChatGPT APIの「InvalidRequestError: Unrecognized request argument」エラー原因と解決方法

このエラーで何が起きているか

「InvalidRequestError: Unrecognized request argument」というエラーは、ChatGPT APIに送信したリクエストに、そのバージョンが認識できないパラメータ（引数）が含まれていることを示しています。つまり、APIの仕様に存在しないキーをJSONで渡してしまっているということです。

具体的には以下のような形でエラーが出ることがあります。

InvalidRequestError: Unrecognized request argument: 'json_mode'

または

InvalidRequestError: Unrecognized request argument: 'vision_model'

Chat Completions APIを利用する際に特に報告されるエラーで、Stack Overflowなどの開発コミュニティでも定期的に質問される一般的なトラブルです。月1000回以上検索されているとされ、多くの開発者が直面する問題でもあります。

このエラーが出ると、APIへのリクエストが完全に拒否されるため、チャット機能やテキスト生成が全く動作しなくなります。開発中はもちろん、本番環境でも同じことが起きれば、ユーザーに迷惑がかかります。

よくあるパターンが「バージョンの不一致」です。2023年11月のopenai 1.0.0リリースで openai.ChatCompletion という使い方が廃止されました。旧バージョン（openai < 1.0.0）の書き方で新しいバージョン（openai >= 1.0.0）のライブラリを実行すると、Pythonが「そんな引数は知りません」という意味のエラーを返します。また、2024年以降もOpenAIはAPIを頻繁にアップデートしており、古いドキュメントに基づいて実装したコードが動かなくなるケースが増えています。

エラーが発生する主な原因

1. パラメータ名のタイプミスまたは古い名前の使用

最も多い原因は、APIドキュメントに記載されていないパラメータ名をリクエストに含めることです。例えば、以下のようなケースが考えられます。

• 古いドキュメントやブログ記事を参考にして、廃止されたパラメータ名を使っている
• パラメータ名を間違えて入力している（スペルミスなど）
• 別のAI APIのパラメータ名と混同している
• キャメルケース（camelCase）とスネークケース（snake_case）が混在している（例：maxTokens → max_tokens）

Chat Completions APIの仕様では、以下のようなパラメータが使われます。

OpenAIの公式APIドキュメントでは定期的に仕様が更新されるため、参考ページの日付をきちんと確認することが重要です。

2. モデル非対応のパラメータを使用している

ChatGPT APIの各モデルは異なる機能セットをサポートしています。例えば、gpt-4-vision-previewでresponse_formatパラメータを指定してJSON形式を強制しようとすると、このエラーが発生します。

# ❌ エラーが出るコード例
import openai

response = openai.ChatCompletion.create(
    model="gpt-4-vision-preview",
    messages=[{"role": "user", "content": "こんにちは"}],
    response_format={"type": "json_object"}  # このモデルでは非対応
)

モデルごとのパラメータ対応状況を把握しておくことが重要です。以下に主要モデルの機能対応をまとめます。

# 各モデルで使える機能の目安（2026年時点）
model_capabilities = {
    "gpt-3.5-turbo": {
        "json_mode": False,   # 一部バージョンは非対応
        "vision": False,
        "function_calling": True
    },
    "gpt-4-turbo": {
        "json_mode": True,
        "vision": True,
        "function_calling": True
    },
    "gpt-4o": {
        "json_mode": True,
        "vision": True,
        "function_calling": True
    }
}

使用しているパラメータが対象モデルでサポートされているか、公式ドキュメントで必ず確認してください。

3. messages 内のフィールド名が間違っている

messages 配列の中身のフィールド名を誤ると、このエラーが出ることがあります。Chat Completions APIでは、各メッセージオブジェクトは以下の構造が必須です。

{
    "role": "user|assistant|system",
    "content": "テキスト内容"
}

content の代わりに text を使ったり、余分なフィールドを追加したりすると、OpenAIサーバーがそれを認識できずエラーになる可能性があります。

4. APIバージョンの不一致

使用しているSDK（Python、JavaScript、Node.jsなど）のバージョンが古い場合、最新のOpenAI APIで追加されたパラメータに対応していないことがあります。逆に、古いAPIを使用しているのに新しいパラメータを送信しても、エラーが発生します。

5. JSONの構造や型の指定が間違っている

リクエストボディのJSON形式が不正な場合、APIが想定外のキーとして解釈することがあります。また、パラメータ自体は合っていても、値の型が誤っている場合もエラーが発生します。

# ❌ 型が誤っている例（文字列で指定）
response = client.chat.completions.create(
    model="gpt-4",
    messages=[...],
    temperature="0.7"  # 文字列はNG
)

# ✅ 正しい指定（数値で指定）
response = client.chat.completions.create(
    model="gpt-4",
    messages=[...],
    temperature=0.7  # 数値で指定
)

ネストが深すぎる、キー名がダブルクォートで囲まれていない、カンマが抜けているなど、JSON構文のエラーが原因になることもあります。

原因の確認：自分のバージョンはどちらか

まずは今インストールされているopenai ライブラリのバージョンを確認しましょう。

pip show openai

実行結果がこんな感じで表示されます：

Name: openai
Version: 1.12.0
Summary: The official Python library for the OpenAI API
...

バージョンが 1.0.0 以上なら、コード側を新しい形式に書き直す必要があります。

エラーが起きるコード（旧形式）

この書き方だとエラーになります：

import openai

openai.api_key = "sk-xxxx..."

response = openai.ChatCompletion.create(
    model="gpt-3.5-turbo",
    messages=[
        {"role": "user", "content": "こんにちは"}
    ]
)

print(response.choices[0].message.content)

上記を openai >= 1.0.0 で実行すると：

AttributeError: module 'openai' has no attribute 'ChatCompletion'

または：

InvalidRequestError: Unrecognized request argument supplied: messages

というエラーが出ます。

解決方法1：コードを新形式に書き直す（推奨）

openai >= 1.0.0 では、APIキーの設定方法と呼び出し方法が両方変わりました。以下が新しい正しい形式です：

from openai import OpenAI

client = OpenAI(api_key="sk-xxxx...")

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "こんにちは"}
    ],
    temperature=0.7,
    max_tokens=100
)

print(response.choices[0].message.content)

何が変わったか

環境変数から自動でAPIキーを読み込む場合

from openai import OpenAI

# 環境変数 OPENAI_API_KEY が自動的に読み込まれます
client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "こんにちは"}
    ]
)

print(response.choices[0].message.content)

この場合、事前に以下のコマンドで環境変数を設定しておいてください：

Linux/Mac の場合：

export OPENAI_API_KEY='sk-xxxx...'

Windows PowerShell の場合：

$env:OPENAI_API_KEY='sk-xxxx...'

Windows コマンドプロンプト の場合：

set OPENAI_API_KEY=sk-xxxx...

解決方法2：ステップバイステップで原因を確認する

ステップ1：エラーメッセージの全文を確認する

まず、エラーメッセージ全体をよく読みましょう。エラー内容に「Unrecognized request argument supplied: 」と続いて、問題のパラメータ名が書かれています。

InvalidRequestError: Unrecognized request argument supplied: messages

という場合、messages パラメータが OpenAI API 側で認識されていません。エラーハンドリングを使って詳細情報を取得する方法も有効です。

from openai import OpenAI, AuthenticationError, APIError

client = OpenAI(api_key="your-api-key")

try:
    response = client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "こんにちは"}],
        unknown_param="value"
    )
except AuthenticationError as e:
    print(f"APIキーが間違っています: {e}")
except APIError as e:
    if "Unrecognized request argument" in str(e):
        print(f"パラメータが非対応です: {e}")
    else:
        print(f"その他のAPIエラー: {e}")

ステップ2：パラメータ名を公式ドキュメントと照らし合わせる

OpenAI公式ドキュメントの Chat Completions APIページを開いて、使っているパラメータ名がそのまま載っているか確認します。特に以下を確認します。

• パラメータ名の綴り（スペル）が完全に一致しているか
• 大文字と小文字が一致しているか
• messages 配列内のフィールド名（role、content など）が正しいか

よく間違えられるパラメータ名を以下に示します。

ステップ3：リクエスト全体をログ出力して確認

APIリクエストを送る前に、リクエストの内容を画面に出力してみましょう。

import json
import openai

request_body = {
    "model": "gpt-4o",
    "messages": [
        {"role": "user", "content": "Hello"}
    ],
    "temperature": 0.7
}

# リクエスト内容をデバッグ出力
print("Sending request:")
print(json.dumps(request_body, indent=2, ensure_ascii=False))

response = openai.chat.completions.create(**request_body)

このコードを実行すれば、実際に何が送られようとしているか目で見て確認できます。誤字があれば、このタイミングで気づきやすくなります。

ステップ4：SDKをアップデートする

Python、Node.js、JavaScriptなどのSDKを使っている場合、古いバージョンが原因かもしれません。以下のコマンドでアップデートしてください。

Python の場合：

pip install --upgrade openai

Node.js / JavaScript の場合：

npm install openai@latest

アップデート後、古いコードが新しいSDKで正しく動作するかテストしてください。SDKの新しいバージョンでは、パラメータ名が変更されていたり、バリデーションが厳しくなっていたりする場合があります。

ステップ5：直接 HTTP リクエストで試す

SDK経由でエラーが出ている場合、直接 HTTP リクエストでも試してみる価値があります。curlコマンドで送ってみれば、APIそのものの問題か、SDKの解析の問題かを区別できます。

curl -X POST https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

このリクエストが成功すれば、API仕様は正しいということになり、SDK側の設定に問題がある可能性が高まります。

また、JavaScript（Node.js）での正しいリクエスト形式は以下の通りです：

const OpenAI = require('openai');

const openai = new OpenAI({
    apiKey: process.env.OPENAI_API_KEY
});

async function chat() {
    try {
        const response = await openai.chat.completions.create({
            model: "gpt-4o",
            messages: [
                {
                    role: "user",
                    content: "こんにちは"
                }
            ],
            temperature: 0.7,
            max_tokens: 100
            // 以下のような古いパラメータはNG：
            // "max_completion_tokens": 100,  // ← 廃止されたパラメータ
            // "frequency_penalty_range": [0, 2]  // ← 存在しないパラメータ
        });

        console.log(response.choices[0].message.content);
    } catch (error) {
        console.error("Error:", error.message);
    }
}

chat();

解決方法3：モデル対応のパラメータに変更する

使用しているモデルが特定のパラメータに対応していない場合、対応するモデルに変更するか、パラメータを削除して対処します。

JSON形式出力を使いたい場合：

from openai import OpenAI
import json

client = OpenAI(api_key="sk-xxx")

# ✅ gpt-4-turbo は response_format に対応
response = client.chat.completions.create(
    model="gpt-4-turbo",
    messages=[
        {"role": "user", "content": "ユーザーの年齢を25、職業をエンジニアとして、JSON形式で返してください"}
    ],
    response_format={"type": "json_object"}
)

# レスポンスはJSON文字列なので parse する
result = json.loads(response.choices[0].message.content)
print(result)

画像入力機能を使いたい場合：

画像入力（Vision）機能が必要な場合は、gpt-4o以上を使用し、画像データをメッセージ内に含めます。

from openai import OpenAI
import base64

client = OpenAI(api_key="sk-xxx")

# 画像ファイルをBase64エンコード
with open("image.jpg", "rb") as img:
    image_data = base64.standard_b64encode(img.read()).decode("utf-8")

# ✅ gpt-4o なら画像入力に対応
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{image_data}",
                        "detail": "low"  # または "high", "auto"
                    }
                },
                {"type": "text", "text": "この画像に写っているものを説明してください"}
            ]
        }
    ]
)
print(response.choices[0].message.content)

Function Calling を使う場合：

Function Calling（tools パラメータ）では、構造の不備もエラーの原因になります。

from openai import OpenAI

client = OpenAI()

# ❌ 不完全な定義（description と parameters が欠けている）
# tools = [{"type": "function", "function": {"name": "get_weather"}}]

# ✅ 正しい形式
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "指定された場所の天気を取得します",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "都市名（例：東京）"
                    }
                },
                "required": ["location"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="gpt-4-turbo",
    messages=[{"role": "user", "content": "東京の天気を教えてください"}],
    tools=tools,
    tool_choice="auto"
)

if response.choices[0].message.tool_calls:
    for tool_call in response.choices[0].message.tool_calls:
        print(f"Function name: {tool_call.function.name}")
        print(f"Arguments: {tool_call.function.arguments}")

複数パラメータを段階的にテストしたい場合：

複数のパラメータを同時に使う場合、どれが原因かわかりづらいことがあります。以下のように1つずつ追加しながらテストしてください。

# まずは基本的なリクエスト
response = client.chat.completions.create(
    model="gpt-4-turbo",
    messages=[{"role": "user", "content": "テスト"}]
)
print("✓ 基本リクエストは成功")

# JSON Modeを追加
response = client.chat.completions.create(
    model="gpt-4-turbo",
    messages=[{"role": "user", "content": "テスト"}],
    response_format={"type": "json_object"}
)
print("✓ JSON Mode対応確認")

# temperature を追加
response = client.chat.completions.create(
    model="gpt-4-turbo",
    messages=[{"role": "user", "content": "テスト"}],
    response_format={"type": "json_object"},
    temperature=0.7
)
print("✓ temperature 対応確認")

解決方法4：旧バージョンを使い続ける

コードを修正できない理由がある場合は、openai ライブラリを旧バージョンに落とすことも可能です。ただ、セキュリティアップデートが適用されなくなるため、本来は推奨されません。

pip install 'openai<1.0.0'

旧バージョンであれば、openai.ChatCompletion.create() の書き方がそのまま動きます。

ただし、この方法は一時的な回避策と考えてください。 長期的には必ず新形式に書き直した方がいいです。

よくあるつまずきポイント

1. messages と message の違いを混乱する

Chat Completions APIは messages（複数形） です。単数形の message を使うとエラーになります。これは英語のネイティブスピーカーでも間違えることがあるほど、よくある誤りです。

# ❌ 間違い：パラメータ名が異なる
response = openai.ChatCompletion.create(
    model="gpt-4o",
    message=[  # 誤字：messages ではなく message
        {"role": "user", "content": "Hello"}
    ]
)

# ✅ 正解：正しいパラメータ名
response = openai.ChatCompletion.create(
    model="gpt-4o",
    messages=[  # 正しい
        {"role": "user", "content": "Hello"}
    ]
)

IDE（ビジュアルスタジオコード、PyCharmなど）のオートコンプリート機能を信頼しすぎず、パラメータ名は手動で確認する習慣をつけると防げます。

2. 古いブログ記事やStack Overflowの回答を参考にしてしまう

インターネットには2023年以前の古い記事が大量に存在します。OpenAIのAPIは仕様が頻繁に変更されるため、記事の日付をきちんと確認してください。特に以下のパラメータは過去に名前が変わっているので注意が必要です。

• max_tokens は正しい（max_completion_tokens ではない）
• presence_penalty と frequency_penalty が存在する（両方を同時に指定可能）
• prompt（廃止）→ messages を使う

3. メッセージの結果を辞書として扱おうとするとエラー

新形式では結果がオブジェクトなので、こういう書き方は動きません：

# NG: 新形式ではこう書くと KeyError が出ます
message = response["choices"][0]["message"]["content"]

正しい書き方：

# OK: オブジェクトのドット記法で値を取得
message = response.choices[0].message.content

4. JSON の括弧の閉じ忘れと誤検出

messages 配列の構造が複雑で、括弧の閉じ忘れがあると、一見するとパラメータ名エラーのように見えることがあります。

# ❌ 括弧が不完全
messages = [
    {"role": "user", "content": "Hello"
]  # 閉じ括弧がない

# ✅ 括弧が正しい
messages = [
    {"role": "user", "content": "Hello"}
]

5. メッセージ形式の誤り

messagesパラメータは、各メッセージがroleとcontentキーを持つ辞書配列である必要があります。

# ❌ 形式が誤っている
messages = [
    "こんにちは",  # 辞書ではなく文字列
    {"role": "user", "content": "質問です"}
]

# ✅ 正しい形式
messages = [
    {"role": "user", "content": "こんにちは"},
    {"role": "assistant", "content": "こんにちは。何かお手伝いできることはありますか？"},
    {"role": "user", "content": "質問です"}
]

6. SDKのバージョンと公式ドキュメントが異なるバージョンを参考にしている

OpenAI公式のPythonクライアントは v0.x から v1.0 への移行時に、コードの書き方が大きく変わりました。古い v0.x のコードを v1.0 以上のSDKで実行すると、当然エラーが出ます。自分が使っているSDKのバージョンに対応したドキュメントを確認するようにしましょう。

# Python の場合
import openai
print(openai.__version__)

7. TypeScriptで型定義がない場合

TypeScriptを使っている場合、IDEの型チェックがエラーを事前に警告してくれることがあります。型定義を活用すれば、無効なパラメータをコンパイル時に発見できます。

import OpenAI from "openai";

const openai = new OpenAI({
    apiKey: process.env.OPENAI_API_KEY
});

async function chat() {
    const response = await openai.chat.completions.create({
        model: "gpt-4o",
        messages: [
            {
                role: "user",
                content: "こんにちは"
            }
        ],
        temperature: 0.7,
        max_tokens: 100
        // IDEが無効なキーをリアルタイムで指摘する
    });

    console.log(response.choices[0].message.content);
}

chat();

8. REST クライアントツール（Postman など）でのヘッダー設定忘れ

Postman や Insomnia などのREST クライアントでAPIを直接叩く場合、Content-Type ヘッダーを application/json に設定しないと、リクエストがうまく解析されず、このエラーが出ることがあります。

Postman での設定方法：

1. Headers タブを開く
2. Key に Content-Type、Value に application/json を入力

9. Pythonの予約語との衝突

自身のコードで使用している変数名と、OpenAIのパラメータ名がぶつかる場合があります。

# NG：format は Python の組み込み関数
format = {"type": "json_object"}
response = client.chat.completions.create(
    response_format=format  # 予期しない動作
)

# 正しい書き方
json_format = {"type": "json_object"}
response = client.chat.completions.create(
    response_format=json_format
)

10. APIキーが間違っていないのにエラーが出る場合

“Unrecognized request argument” というメッセージの場合、実は API キーの問題ではなく、コードの書き方が問題です。再度上記の「新形式」コードと見比べて、形式が一致しているか確認しましょう。エラーメッセージを見ると、どのパラメ

参考：Claude APIでのパラメータ検証パターン

Claude APIでも同種のパラメータエラーを防ぐための、リクエスト前バリデーションの実装例です。

import anthropic

client = anthropic.Anthropic()

VALID_PARAMS = {"model", "max_tokens", "messages", "system", "temperature", "tools", "tool_choice"}

def safe_claude_request(**kwargs) -> dict:
    """Claude APIに送る前に、不明なパラメータがないか検証"""
    unknown_params = set(kwargs.keys()) - VALID_PARAMS
    if unknown_params:
        return {
            "status": "error",
            "message": f"不明なパラメータ: {unknown_params}。Claude APIドキュメントを確認してください"
        }

    if "max_tokens" not in kwargs:
        return {"status": "error", "message": "max_tokensは必須パラメータです"}

    try:
        response = client.messages.create(**kwargs)
        return {"status": "success", "text": response.content[0].text}
    except anthropic.BadRequestError as e:
        return {"status": "error", "message": f"リクエストエラー: {e.message}"}

# 使用例
result = safe_claude_request(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "こんにちは"}]
)
print(result)

# 誤ったパラメータ名を使った場合、送信前に検出される
bad_result = safe_claude_request(
    model="claude-sonnet-4-5",
    max_token=1024,  # ← タイプミス（正しくはmax_tokens）
    messages=[{"role": "user", "content": "こんにちは"}]
)
print(bad_result)  # → エラーで停止（APIに到達する前に検出）

送信前にパラメータ名を検証する層を挟むことで、タイプミスによるAPIエラーを本番環境に到達する前に検出できます。

あわせて読みたい

• Claude Code 403 Forbiddenエラー【原因・解決手順】APIキー・権限設定
• Claude Code「Connection timeout」エラーの原因と解決方法｜3つの対処法
• Claude Code「Extension Not Found」エラーの原因と解決方法｜3ステップで直す