> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# max_tokens 是什么？不设置会怎样？

> 说明 max_tokens 在 Chat Completions、Responses、Anthropic Messages 和 Gemini 中的参数名与默认行为，老张API是否额外限制，输出被截断怎么判断，以及它和预扣费的关系。

`max_tokens` 是单次回复最多生成的 token 数。老张API不额外限制这个值，原样传给上游模型；不设置时使用模型自己的默认值。不同协议的参数名不同，填错名字会报错或被忽略。

| 协议 | 参数 | 是否必填 | 达到上限时的标记 |
| - | - | - | - |
| Chat Completions | `max_completion_tokens`（旧参数 `max_tokens`） | 否 | `finish_reason` 为 `length` |
| Responses | `max_output_tokens` | 否 | `status` 为 `incomplete`，原因 `max_output_tokens` |
| Anthropic Messages | `max_tokens` | 是 | `stop_reason` 为 `max_tokens` |
| Gemini 原生 | `generationConfig.maxOutputTokens` | 否 | `finishReason` 为 `MAX_TOKENS` |

## 设置大小有什么影响

* **太小**：回答被截断，只拿到一半内容。
* **太大**：不会让模型多写，模型写完就停；但上限越大，请求前的预扣费越高，余额紧张时可能被拒绝。
* **不设置**：使用模型默认值。各厂商默认值不同，有的允许输出到上下文用完，有的默认较小。

推理模型的思考过程也算在输出预算里，只是不出现在回复正文中。上限设得太小时，可能思考还没结束就用完了预算，返回空内容或被截断的回答。

## 不同协议怎么写

<Tabs>
  <Tab title="Chat Completions">
    OpenAI 已把 Chat Completions 的 `max_tokens` 标为弃用，推理模型（GPT-6、GPT-5.x、o 系列等）要用 `max_completion_tokens`：

    ```python theme={null}
    response = client.chat.completions.create(
        model="gpt-6-sol",
        messages=[{"role": "user", "content": "总结这篇文章"}],
        max_completion_tokens=4096,
    )
    print(response.choices[0].finish_reason)  # length 表示达到上限
    ```

    其他兼容模型如果不认 `max_completion_tokens`，改用 `max_tokens`，以模型说明和错误信息为准。
  </Tab>

  <Tab title="Responses">
    ```python theme={null}
    response = client.responses.create(
        model="gpt-6-sol",
        input="总结这篇文章",
        max_output_tokens=4096,
    )
    print(response.status)  # incomplete 时查看 response.incomplete_details
    ```
  </Tab>

  <Tab title="Anthropic Messages">
    `max_tokens` 必填，不传会直接返回 400：

    ```python theme={null}
    message = client.messages.create(
        model="glm-5.2",
        max_tokens=4096,
        messages=[{"role": "user", "content": "总结这篇文章"}],
    )
    print(message.stop_reason)  # max_tokens 表示达到上限
    ```
  </Tab>

  <Tab title="Gemini 原生">
    ```json theme={null}
    {
      "contents": [{"parts": [{"text": "总结这篇文章"}]}],
      "generationConfig": {"maxOutputTokens": 4096}
    }
    ```

    响应中 `candidates[0].finishReason` 为 `MAX_TOKENS` 表示达到上限。
  </Tab>
</Tabs>

示例里的 `client` 按各协议的配置创建，Base URL 见[老张API开发文档](/api-manual)。

## 建议设多少

建议每次请求都显式设置，避免不同模型的默认值让结果忽长忽短。常见取值：

* 普通对话：2048–4096；
* 代码生成：4096–8192；
* 长文写作：8192–16384，或改用流式分段输出。

各模型的最大输出 token 数以厂商官方文档为准，超过模型上限时，模型按自己的上限处理或返回参数错误。

## 和预扣费的关系

请求前，系统按模型价格、输入长度和预计输出长度先冻结一笔费用，完成后按实际用量结算。显式设置 `max_tokens` 会降低预计输出，预扣金额也随之降低。余额不多却要处理长输入时，合理的输出上限能避免请求在执行前被拒绝，详见[为什么还有余额但调用失败](/faq/balance-insufficient)。

## 常见问题

### 老张API会限制或改写 max\_tokens 吗？

不会。参数原样传给上游，唯一的限制来自模型本身的最大输出 token 数。

### 输出被截断了怎么办？

先看截断标记（见上表）确认是不是达到了上限。是的话：

1. 调大上限；
2. 推理模型适当调低思考档位，给正文留出预算；
3. 检查参数名是否与协议一致，例如推理模型在 Chat Completions 中要用 `max_completion_tokens`。

### 设置了上限，为什么回复还是很短？

上限只是天花板，模型认为答完了就会停。需要更长的内容时，在提示词里说明篇幅和结构要求。

## 相关文档

* [Chat Completions 请求格式与字段](/api-reference/chat-completions)
* [Claude 协议：Anthropic Messages 请求格式](/api-reference/claude)
* [Gemini 协议：generateContent 请求格式](/api-reference/gemini)
* [为什么还有余额但调用失败](/faq/balance-insufficient)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.