OpenAI API max_tokens 参数怎么设置？

更新于 2026-10-24 · runapi.cfd

简答：先判断你调用的是哪一种 API：旧版 Completions 使用 max_tokens，Chat Completions 新请求优先使用 max_completion_tokens，Responses API 使用 max_output_tokens。它们都是“最大生成上限”，不是保证输出长度；建议先按任务预留空间，再根据 usage 和结束状态调小或调大。

定义：max_tokens 是限制模型最多生成多少 token 的参数，不等于固定输出长度，也不直接代表可见汉字数量。

先看接口：max_tokens 应该填在哪个参数里

截至2026年10月24日，参数选择首先取决于请求接口，而不是只看模型名称。Chat Completions 的官方参数说明已将 max_tokens 标为弃用，建议改用 max_completion_tokens；旧版 Completions 仍定义了 max_tokens。Responses API 则使用 max_output_tokens。可分别查看 Chat Completions 参数说明、Completions 参数说明和 Responses 参数说明。

接口	优先参数	适用结论
`/v1/chat/completions`	`max_completion_tokens`	新请求优先使用；它是生成上限，并可包含推理 token。
`/v1/responses`	`max_output_tokens`	限制 Responses 生成的 token 总量，官方参数名不是 `max_tokens`。
`/v1/completions`	`max_tokens`	旧版 prompt-completion 接口仍按该字段定义。
第三方 OpenAI Compatible 网关	按网关文档确认	不要只因接口名称相似就混用参数；先看其模型和路由说明。

不要同时发送互相替代的长度字段。如果你在 Chat Completions 中已经改用 max_completion_tokens，就先删除 max_tokens，再根据返回错误判断网关是否仍要求旧字段。官方文档还说明，max_tokens 与 o-series 模型不兼容；模型与参数支持情况应以对应接口文档为准。

数值怎么起步：把它当上限，不要当字数承诺

max_tokens、max_completion_tokens 或 max_output_tokens 只规定模型最多生成多少 token。模型可能因为已经完成回答、遇到 stop 序列、调用工具或内容过滤而提前结束，所以把数值设为 500，并不意味着一定返回 500 个 token。官方长度控制说明也建议结合明确提示词、示例、stop，以及部分模型支持的 verbosity 来控制实际长度，详见 OpenAI 关于控制响应长度的说明。

下面是工程上的起步建议，不是模型官方上限：

一句话问答或分类：从 64–128 起步。
短摘要、翻译、要点提取：从 128–256 起步，并在提示词中写明条数或字数。
代码解释或短代码生成：从 256–512 起步；如果要求完整文件，再根据实际输出增加。
长文、复杂分析或推理任务：先确认模型上下文和接口限制，再逐步增加，不要一次设置到未经核实的极大值。

中文 token 不能简单按“一个汉字等于一个 token”换算。输入内容、消息结构、工具、文件和模型都会影响 token 统计；官方建议使用 Tokenizer 或 token 统计能力估算，并在响应中读取 usage，参考 token 基础说明与 Token 统计指南。

可直接运行的最小 curl 示例：Chat Completions

如果你使用的是 Chat Completions，新请求可以先用 max_completion_tokens。下面命令不包含明文密钥，执行前请在当前终端设置 OPENAI_API_KEY；模型值 <你的模型ID> 必须替换为你账户和当前路由实际可用的模型 ID。

curl https://api.openai.com/v1/chat/completions -H "Authorization: Bearer $OPENAI_API_KEY" -H "Content-Type: application/json" -d '{"model":"<你的模型ID>","messages":[{"role":"user","content":"用三句话解释 API Key 的作用"}],"max_completion_tokens":128}'

如果你的目标接口明确要求旧版字段，则将最后的 max_completion_tokens 换成 max_tokens，不要两个字段一起传。若使用 Responses API，应改用 /v1/responses 和 max_output_tokens，不能把上面的 JSON 原样复制过去。

密钥安全方面，命令行中的环境变量仍可能被当前 shell、脚本日志或进程环境读取；测试结束后按你的系统方式清理变量，并避免把完整请求命令提交到 Git、工单或聊天记录中。

输出被截断时：先看 finish_reason、status 和 usage

Chat Completions 返回结果时，先查看 choices[0].finish_reason。官方响应定义中，length 表示达到请求中指定的最大 token 数；stop 通常表示自然结束或命中 stop 序列。相关字段可见 Chat Completion 返回字段说明。

排查顺序可以固定为：

确认请求发送的到底是 max_tokens、max_completion_tokens 还是 max_output_tokens，并与接口路径匹配。
读取 usage.prompt_tokens、usage.completion_tokens、usage.total_tokens；部分模型或响应还会提供推理 token 细分。
如果 Chat Completions 的 finish_reason 是 length，先把输出上限提高一档，或缩短输入与提示词，再重试。
如果使用 Responses API，检查响应的 status 和 incomplete_details.reason；官方定义中，原因可能是 max_output_tokens、max_messages 或 content_filter。
如果返回 400，不要只盯着数值大小：还要检查模型是否支持该字段、输入加输出是否超过上下文窗口，以及是否误把不同接口的参数混用。

需要特别注意，官方 token 统计说明指出，max_completion_tokens 和 max_output_tokens 可能同时限制不可见 token；推理模型因此可能消耗一部分上限后，留给可见文本的空间变小。想得到固定可见长度时，应在上限中预留余量，而不是把上限当成可见字数。

常见错误：过小、过大和参数不兼容分别怎么处理

现象	优先判断	处理方法
回答半句话结束	`finish_reason=length` 或 Responses 状态为 incomplete	提高对应接口的输出上限，并减少输入内容；同时让提示词规定回答结构。
返回 400	字段名、模型支持、上下文长度或 JSON 类型错误	核对接口参考；确认数值为非负整数，并确认输入 token 加输出预算没有超过模型上下文限制。
提示 unsupported_parameter	当前模型或兼容网关不接受所传字段	删除不兼容字段，改用该接口文档要求的参数；第三方路由按其文档确认。
设得很大但回答仍很短	模型已经自然结束、命中 stop 或提示词要求短答	不要只增加上限；检查 `finish_reason`，并调整提示词、示例或 stop 设置。
请求成本或限速压力增加	输出上限明显高于实际任务需要	让上限接近预期输出规模；官方限速说明也建议减少不必要的 `max_tokens` 预算，见限速说明。

最后一个边界很重要：输入 token 与输出上限不是两个互不相关的空间。旧版 Completions 参考明确说明，prompt token 加上 max_tokens 不能超过模型上下文长度；新接口也应按具体模型文档核对上下文能力，而不是凭经验填写一个极大值。

常见问题

max_tokens 和 max_completion_tokens 有什么区别？

在 Chat Completions 中，max_tokens 是旧字段且已被官方标为弃用；max_completion_tokens 是推荐替代字段，并且其上限可包含可见输出和推理 token。旧版 Completions 仍使用 max_tokens。

max_tokens 设置成 100，是不是一定返回 100 个 token？

不是。它只是最大生成上限。模型可能自然结束、命中 stop、调用工具或触发内容过滤，因此实际输出可能少于该数值；应结合 finish_reason、status 和 usage 判断。

Responses API 可以继续使用 max_tokens 吗？

不应直接照搬。Responses API 的长度参数是 max_output_tokens；请按 /v1/responses 的请求格式填写，并检查响应中的 status 与 incomplete_details。

max_tokens 设置越大越好吗？

不是。过大的预算可能增加上下文压力、成本或限速压力，而且不保证模型会写得更长。应从接近任务需求的起步值开始，再根据实际 usage 和截断状态调整。

中文内容应该按多少汉字换算一个 token？

不要使用固定的一比一换算。中文、英文、标点、消息结构、工具和模型都会影响 token 数量；应使用官方 Tokenizer 或 token 统计能力，并以 API 返回的 usage 为准。

Run API