解決 OpenAI field messages is required 錯誤：Responses API 與 Chat Completions 請求格式詳解

作者注：深度解析 OpenAI API 調用時出現 field messages is required 錯誤的原因，詳解 Responses API 與 Chat Completions API 的請求格式差異，提供正確的代碼示例

調用 GPT-5-nano 等新模型時遇到 field messages is required 錯誤？這是許多開發者在遷移到 OpenAI 新版 API 時常見的問題。本文將深度解析 Responses API 與 Chat Completions API 的核心差異，幫助你快速定位並解決這類請求格式錯誤。

核心價值: 讀完本文，你將理解兩套 API 的請求格式差異，能夠正確調用 GPT-5 系列模型，徹底解決 field messages is required 錯誤。

field messages is required 錯誤核心要點

錯誤案例分析

根據您提供的錯誤信息：

{
  "original_error": {
    "status_code": 400，
    "error": {
      "message": "field messages is required"，
      "type": "shell_api_error"，
      "code": "invalid_text_request"
    }
  }，
  "request_params": {
    "model": "gpt-5-nano"，
    "instructions": "# Role\n\nYou generate alt text..."
  }
}

問題診斷: 請求中只有 model 和 instructions 參數，缺少了必需的 input 參數。Responses API 要求必須提供用戶輸入內容。

爲什麼會出現 field messages is required 錯誤

OpenAI 目前有兩套主要的文本生成 API：

1. Chat Completions API （/v1/chat/completions） – 使用 messages 數組
2. Responses API （/v1/responses） – 使用 input + instructions 分離式參數

當你的請求格式與目標 API 端點不匹配時，就會觸發 field messages is required 或類似錯誤。GPT-5 系列模型（包括 gpt-5-nano）默認推薦使用 Responses API。

Responses API 正確請求格式

極簡示例

以下是調用 GPT-5-nano 的正確方式：

import openai

client = openai.OpenAI（
    api_key="YOUR_API_KEY"，
    base_url="https://vip.apiyi.com/v1"
）

# Responses API 正確格式
response = client.responses.create（
    model="gpt-5-nano"，
    instructions="You generate alt text for images."，
    input="Describe the sunset photo"
）
print（response.output_text）

import openai
from typing import Optional

def call_responses_api（
    input_text: str，
    model: str = "gpt-5-nano"，
    instructions: Optional[str] = None
） -> str:
    """
    正確調用 OpenAI Responses API

    Args:
        input_text: 用戶輸入內容 （必需！）
        model: 模型名稱
        instructions: 系統指令

    Returns:
        模型響應內容
    """
    client = openai.OpenAI（
        api_key="YOUR_API_KEY"，
        base_url="https://vip.apiyi.com/v1"
    ）

    try:
        # Responses API 格式: input + instructions （分離式）
        response = client.responses.create（
            model=model，
            input=input_text，  # 必需參數！
            instructions=instructions
        ）
        return response.output_text
    except Exception as e:
        return f"Error: {str（e）}"

# 正確調用示例
result = call_responses_api（
    input_text="A golden sunset over the ocean with waves"，
    model="gpt-5-nano"，
    instructions="You generate alt text for HTML img tags. Keep it concise， under 125 characters."
）
print（result）

建議: 通過 API易 apiyi.com 獲取免費測試額度，平臺同時支持 Chat Completions 和 Responses API 格式，便於調試和驗證。

Chat Completions API 請求格式

如果你更熟悉 Chat Completions API，也可以繼續使用，但需要正確的格式：

import openai

client = openai.OpenAI（
    api_key="YOUR_API_KEY"，
    base_url="https://vip.apiyi.com/v1"
）

# Chat Completions API 正確格式
response = client.chat.completions.create（
    model="gpt-5-nano"，
    messages=[
        {
            "role": "system"，
            "content": "You generate alt text for HTML img tags."
        }，
        {
            "role": "user"，
            "content": "Describe the sunset photo"
        }
    ]
）
print（response.choices[0].message.content）

兩套 API 參數對比

常見錯誤及解決方案

錯誤 1: field messages is required

原因: 向 Responses API 端點發送了 Chat Completions 格式的請求

解決:

• 方案 A: 使用 input + instructions 替代 messages
• 方案 B: 改用 /v1/chat/completions 端點配合 messages

錯誤 2: invalid_text_request

原因: 請求體格式與目標 API 不匹配

解決: 檢查是否遺漏了必需參數（如 Responses API 的 input）

錯誤 3: Missing required parameter: tools[0].function

原因: Chat Completions 和 Responses API 的工具定義格式不同

解決: 參考對應 API 的工具定義規範重新編寫

常見問題

GPT-5-nano 模型規格

🎯 性價比提示: GPT-5-nano 是 GPT-5 系列中最便宜的模型，適合分類、摘要、簡單問答等任務。通過 API易平臺調用可享受額外優惠。

總結

field messages is required 錯誤的核心要點：

1. 根本原因: 向 Responses API 發送了 Chat Completions 格式的請求，或缺少必需的 input 參數
2. 解決方案: 使用正確的參數格式 —— Responses API 用 input + instructions，Chat Completions 用 messages
3. 最佳實踐: GPT-5 系列新項目推薦使用 Responses API，現有項目可繼續使用 Chat Completions

遇到 API 格式問題時，首先確認目標端點，然後檢查參數是否與該端點匹配。

推薦通過 API易 apiyi.com 快速驗證效果，平臺同時支持兩種 API 格式，提供免費測試額度。

參考資料

⚠️ 鏈接格式說明: 所有外鏈使用 資料名: domain.com 格式，方便複製但不可點擊跳轉，避免 SEO 權重流失。

1. OpenAI Responses API 文檔: 官方 Responses API 使用指南

   • 鏈接: platform.openai.com/docs/api-reference/responses
   • 說明: 瞭解 Responses API 完整參數和用法

2. OpenAI API 遷移指南: 從 Chat Completions 遷移到 Responses API

   • 鏈接: platform.openai.com/docs/guides/migrate-to-responses
   • 說明: 官方遷移指南和參數映射說明

3. GPT-5 nano 模型文檔: GPT-5-nano 規格和最佳實踐

   • 鏈接: platform.openai.com/docs/models/gpt-5-nano
   • 說明: 瞭解模型能力和適用場景

作者: 技術團隊
技術交流: 歡迎在評論區討論，更多資料可訪問 API易 apiyi.com 技術社區