Max Tokens vs Max Output Tokens

TL;DR: "Max tokens" is at least four field names across three vendors, and none of them cap your prompt. OpenAI's Responses API calls it max_output_tokens; Chat Completions calls the current one max_completion_tokens and deprecated the old max_tokens. Anthropic requires max_tokens. Google uses maxOutputTokens. On OpenAI and Anthropic, reasoning tokens are billed against that same ceiling.

Wait, is this even a two-way comparison?

Not really, and that is the first thing worth correcting. "Max tokens vs max output tokens" sounds like a clean two-way split, but the moment you check each vendor's own reference, it turns into at least four separate field names spread across three companies, two of which run more than one API shape at once.

Here is the honest inventory, checked against each vendor's own published reference on September 3, 2026:

Four distinct field names, one of them reused twice by the same vendor for two different APIs with two different deprecation states. If your mental model was OpenAI uses max_tokens and everyone else copies it, that model is now actively wrong for the API you are most likely calling today.

What does the parameter actually limit?

Output only, on every vendor, every API, every version. None of the fields above ever caps your prompt.

OpenAI's own specification for the legacy Completions endpoint says it most plainly, because that endpoint predates every later naming split: "The token count of your prompt plus max_tokens cannot exceed the model's context length." Read that sentence carefully: the parameter itself is still only bounding the completion. The combined ceiling on prompt-plus-output is a separate, fixed number: the model's context window, which you cannot set. You can send a two-token prompt with a max_tokens of 4, or a 50,000-token prompt with the same value of 4. Both requests are equally valid with respect to that parameter. What changes is how much room is left in the context window for the two of them together.

This is the most common misconception worth correcting up front: people treat "max tokens" as a total budget, then are surprised when a short setting truncates a long answer to a short prompt. It was never a budget for the conversation. It is a ceiling on what comes out.

Context window and output cap are two different numbers that happen to interact. Confusing them is the single most common way people misdiagnose truncation — a topic covered in full here, including the four other reasons an answer can get cut short that have nothing to do with this parameter.

OpenAI: one name, three APIs, two different deprecation states

Start here because OpenAI has the most moving parts, and because it is the vendor whose old code is most likely to be silently wrong right now.

Chat Completions, the endpoint most existing code and most tutorials still target, exposes two fields for the same idea, at two different points in its lifecycle. OpenAI's published specification marks the old one deprecated in plain terms: "This value is now deprecated in favor of max_completion_tokens," and separately states it is not compatible with o-series models — meaning it silently does not work at all against OpenAI's reasoning-model line. The replacement field's own description is explicit about what it covers: "An upper bound for the number of tokens that can be generated for a completion," and the same spec entry states plainly that this includes both visible text and internal reasoning tokens.

The Responses API, OpenAI's newer, current-generation surface, drops both of those names for a third: max_output_tokens. Its own description reads almost identically to the Chat Completions replacement: "An upper bound for the number of tokens that can be generated for a response," again covering visible output plus reasoning tokens, with one addition Chat Completions does not carry: a documented floor. The field's schema sets a minimum of 16: you cannot ask for zero or a handful of tokens on this API the way legacy Completions technically allows.

The original Completions API, the oldest surface, used by legacy models like gpt-3.5-turbo-instruct, still calls its field max_tokens, and that name was never touched by the later rename, because the endpoint itself is frozen rather than actively developed. This is the third distinct meaning of the identical string "max_tokens" inside one vendor's own product line, and it is the reason "does OpenAI use max_tokens" cannot be answered with a plain yes or no.

Where OpenAI is explicit, and where this matters in practice, is reasoning-token billing. Its reasoning guide states outright: "While reasoning tokens are not visible via the API, they still occupy space in the model’s context window and are billed as output tokens." The practical failure mode that follows from this is one every reasoning-model user eventually hits: a cap set for the visible answer alone can be exhausted entirely by invisible thinking, and OpenAI's own docs describe exactly that outcome — "This might occur before any visible output tokens are produced," meaning you can be billed for input and reasoning tokens and receive nothing back at all.

Anthropic: one name, and it is mandatory

Anthropic keeps a single field, max_tokens, across its entire Messages API, with no split, no rename, and no legacy-vs-current split to track. The tradeoff is that this field is required on every request. Where OpenAI's Responses API lets you omit max_output_tokens and fall back to a default, Anthropic's API rejects a request that leaves max_tokens out.

The more consequential fact, and the one that mirrors OpenAI's reasoning-token behaviour almost exactly, is what happens when extended thinking is enabled. Anthropic's own extended thinking guide is direct about it: "Thinking tokens count toward the max_tokens limit for the turn, so the budget must leave room for the final response." The thinking budget itself, budget_tokens, carries its own floor relative to the same field — Anthropic's reference states plainly: "Minimum of 1,024 tokens. The API rejects smaller values." It also requires the value stay "Less than max_tokens." The guide is equally direct that the outer field does not bend to accommodate it: "The budget is a target rather than a strict cap. Actual token usage varies with the task, and Claude may stop reasoning well before the budget is exhausted; max_tokens remains the hard ceiling on total output."

That word, ceiling, is doing the same job here as OpenAI's "including visible output tokens and reasoning tokens" language. Two different vendors, two different words, the same underlying design: one number that reasoning and the final answer both draw from.

For anyone running Claude at higher reasoning effort, Anthropic's own guidance on sizing this field is worth quoting directly, because it gives a concrete number rather than a vague appeal to set it high: "When running Claude Opus 5 at xhigh or max effort, set a large max_tokens so the model has room to think and act across subagents and tool calls. Starting at 64k tokens and tuning from there is a reasonable default."

Google: a third name, and a genuinely different accounting model

Google's Gemini API drops both prior names for maxOutputTokens, nested inside a generationConfig object rather than sitting at the top level of the request. Its own reference describes it simply: "Optional. The maximum number of tokens to include in a response candidate." The value defaults to a per-model limit when you leave it unset, closer to OpenAI's optional-with-a-default pattern than to Anthropic's required field.

Where Google genuinely diverges from the other two is in how it accounts for thinking. OpenAI and Anthropic both state, in plain prose, that reasoning tokens are billed against the same output cap as the visible answer. Google's usage-reporting schema instead keeps a separate running total for thinking: its reference defines thoughtsTokenCount as "Number of tokens of thoughts for thinking models." That count is tracked apart from the visible answer's own count, and both roll into a totalTokenCount described as covering "prompt + thoughts + response candidates" as three distinct components rather than two.

That is a real, sourced structural difference, not a rounding error: Google's own numbers separate "thoughts" from "response candidates" as named quantities, where OpenAI and Anthropic fold reasoning directly into the same number as the visible answer. What Google's public reference does not state as explicitly as the other two vendors do is whether maxOutputTokens itself can be exhausted by thinking before any visible text appears, the way OpenAI and Anthropic both document happening on their own APIs. Its guide on thinking does confirm the tokens are real and billed — "Pricing is based on the full thought tokens the model needs to generate, despite only the summary being output from the API" — without connecting that spending directly to the maxOutputTokens ceiling in the same sentence the way Anthropic and OpenAI do. Treat that specific interaction as documented-but-less-explicit on Google's side rather than confirmed absent.

What happens when you actually hit the ceiling?

Three vendors, three different signals, and knowing which one you are looking at saves a debugging session.

None of these are errors in the HTTP sense: all three return a normal successful response with a field telling you generation was cut short rather than concluded naturally. In every case, whatever text or content had already been generated is typically still present in the response body, which is why the correct recovery is resuming from the tail of what you received rather than discarding it and regenerating from scratch. The exact technique (and the copy-paste continuation prompts for it) is covered in the ChatGPT truncation guide.

Copy-paste: setting the cap correctly on all three

Same job (cap the response, leave headroom for reasoning where the model supports it), written the way each API actually wants it.

# OpenAI — Responses API. Field is max_output_tokens, minimum 16.
curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "input": "Summarise this incident report in three bullet points.",
    "max_output_tokens": 2048,
    "reasoning": { "effort": "medium" }
  }'

# Anthropic — Messages API. max_tokens is REQUIRED; omit it and the call fails.
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 16000,
    "messages": [
      { "role": "user", "content": "Summarise this incident report in three bullet points." }
    ]
  }'

# Google — Gemini API. maxOutputTokens lives inside generationConfig.
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{ "parts": [{ "text": "Summarise this incident report in three bullet points." }] }],
    "generationConfig": {
      "maxOutputTokens": 2048
    }
  }'

Swap the model IDs for whatever is current when you read this; the field names and their behaviour are the durable part.

So what should you actually set?

Four rules that hold across all three vendors.

1. Match the field name to the API, not to habit. max_completion_tokens on OpenAI Chat Completions, max_output_tokens on OpenAI Responses, max_tokens on Anthropic, maxOutputTokens on Google. Porting a snippet between OpenAI's own two APIs is the single most common way this breaks, because the same vendor uses two different names.
2. On a reasoning or extended-thinking model, size the cap for thinking plus the answer, not just the answer. OpenAI's own guidance is to reserve at least 25,000 tokens for reasoning and output combined when you start experimenting with its reasoning line. Anthropic's equivalent guidance for high-effort Claude Opus 5 is to start at 64,000 tokens and tune down from there.
3. Never assume the cap includes your prompt. It never has, on any vendor's version of this field. The context window is the number that includes your prompt, and it is not something you set per request.
4. Treat a cutoff as a signal to resume, not to discard. incomplete_details.reason, stop_reason, and finishReason all exist so your code can tell a length cutoff apart from a genuine natural stop, and every vendor still returns whatever text was generated before the cutoff.

If you also need the cross-vendor picture for temperature, structured output, tool choice, and every other generation parameter, the LLM parameter cheat sheet keeps all of it on one page — this post is the deep dive on the one parameter people get wrong most often. And if the actual JSON shape of your prompt is the thing giving you trouble rather than the token cap, JSON prompts explained covers the prompt-side half of structured output.

Sources and access dates

Every claim above traces to a primary document, accessed September 3, 2026:

• OpenAI: the published OpenAPI specification (openapi.yaml, read directly from source rather than the rendered docs), and the reasoning models guide.
• Anthropic: the Messages API reference, the extended thinking guide, and the effort guide.
• Google: the Gemini API generating-content reference, the Gemini thinking guide, and the v1beta discovery document.

Field names and deprecation states move faster than most reference content. Anthropic's extended-thinking mechanics and OpenAI's Responses/Chat Completions split were both current as of this access date; check the vendor's own reference before trusting any cheat sheet, this one included.