解决 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 技术社区