GPT-5 API 请求参数调整，避坑指南（汇总）

[bull (牛爷爷)]

奥特曼试了一把 GPT-5，瘫痪在地，大喊：我的 API 怎么跑不通了？

本篇文章来捋一下 GPT-5 系列模型的 API 参数都有哪些变化，新增的参数，以及注意事项。

欢迎补充，本帖持续更新。

省流概览

reasoning_effort

可用参数 reasoning_effort，控制 GPT‑5 的推理耗时， 调高参数值可以优化输出质量，而降低参数值可以提升响应速度。

支持的参数值：minimal（GPT-5新增）、low、medium、high。

支持的模型：除gpt-5-chat-latest，其余均支持。

verbosity

新增参数 verbosity，帮助控制控制回答是简短扼要还是详尽全面，调控 GPT‑5 回答的默认长度。

支持的参数值：low、medium、high。

支持的模型：除gpt-5-chat-latest，其余均支持。

temperature

需要注意，GPT-5 的 temperature 参数，除了 gpt-5-chat-latest，其他均需要置为空或者设置为 1，不支持其他值。

web_search

无法使用，阅读了官方文档以及相关讨论帖，推断目前 GPT-5 系列模型不支持内置的Web Search功能。

查看推理内容

只有使用 Responses API（v1/responses），并将 store 参数设置为 true ，才能在上下文中保留推理内容。

此功能在 Chat Completions API（v1/chat/completions）中不支持。

案例演示

这里以 Poixe AI 提供的免费 GPT-5 模型 API 接口做演示，调试工具使用 Apifox。

此处仅测试 OpenAI 的 Chat Completions 接口协议（/v1/chat/completions）。

参数1：reasoning_effort 成功演示

以上实测数据

// 请求地址
POST https://api.poixe.com/v1/chat/completions

// 请求体
{
  "model": "gpt-5:free",
  "messages": [
    {
      "role": "user",
      "content": "hi"
    }
  ],
  "reasoning_effort": "minimal"
}

// 响应体
{
  "id": "chatcmpl-C2DohyoWXTHJTqzyFsUR1WpcrX3ra",
  "object": "chat.completion",
  "created": 1754645803,
  "model": "gpt-5-2025-08-07",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hi! How can I help you today?",
        "refusal": null,
        "annotations": []
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 7,
    "completion_tokens": 18,
    "total_tokens": 25,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "service_tier": "default",
  "system_fingerprint": null
}

参数2：verbosity 成功演示

以上实测数据

// 请求地址
POST https://api.poixe.com/v1/chat/completions

// 请求体
{
  "model": "gpt-5-mini:free",
  "messages": [
    {
      "role": "user",
      "content": "hi"
    }
  ],
  "verbosity": "high"
}

// 响应体
{
  "id": "chatcmpl-C2Dwm8zXHEXskZ3oGb4mWSiszhJc6",
  "object": "chat.completion",
  "created": 1754646304,
  "model": "gpt-5-mini-2025-08-07",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hi — nice to meet you! How can I help today?\n\nHere are some things I can do (pick one or tell me something else):\n- Answer a question or explain a concept (science, history, tech, etc.)\n- Write or edit text: email, resume bullets, cover letter, story, social post\n- Help with code: debug, optimize, or write snippets (paste the code and expected behavior)\n- Summarize or analyze text you paste in\n- Plan something: trip, study schedule, project roadmap, meal plan\n- Translate or rewrite in another tone (formal, casual, concise)\n- Brainstorm ideas: names, features, marketing angles\n- Walk through math or step-by-step problems\n- Roleplay or simulate an interview/practice conversation\n\nTell me what you want and any details I should know (length, tone, deadline, examples). If you prefer short answers or deep dives, say so.",
        "refusal": null,
        "annotations": []
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 7,
    "completion_tokens": 455,
    "total_tokens": 462,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 256,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "service_tier": "default",
  "system_fingerprint": null
}

参数3：temperature 失败演示

以上实测数据

// 请求地址
POST https://api.poixe.com/v1/chat/completions

// 请求体
{
  "model": "gpt-5-nano:free",
  "messages": [
    {
      "role": "user",
      "content": "hi"
    }
  ],
  "temperature": 0.5
}

// 响应体
{
  "error": {
    "message": "Unsupported value: 'temperature' does not support 0.5 with this model. Only the default (1) value is supported.",
    "type": "invalid_request_error",
    "source": "upstream"
  }
}

参数4：web_search 失败演示

以上实测数据

// 请求地址
POST https://api.poixe.com/v1/chat/completions

// 请求体
{
  "model": "gpt-5-nano:free",
  "messages": [
    {
      "role": "user",
      "content": "今天天气如何？"
    }
  ],
  "tools": [
    {
      "type": "web_search_preview"
    }
  ]
}

// 响应体
{
  "error": {
    "message": "Invalid value: 'web_search_preview'. Supported values are: 'function' and 'custom'.",
    "type": "invalid_request_error",
    "source": "upstream"
  }
}

参考文档

OpenAI 官方文档：

https://openai.com/zh-Hans-CN/index/introducing-gpt-5-for-developers/

https://platform.openai.com/docs/guides/reasoning

https://platform.openai.com/docs/guides/latest-model?lang=python&verbosity-mode=chat&reasoning-effort-mode=chat&custom-tools-mode=chat

https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat

Stackoverflow 讨论帖：

https://stackoverflow.com/questions/79598009/getting-web-search-is-not-supported-in-o4-mini-even-though-it-is-supported-and

写在最后

以上。