Max output tokens

How it works

Max output tokens is the ceiling on how many tokens a model can generate in one response. There are two numbers: the model's hard limit, published by the maker, and the per-request value you set (often called max_tokens), which must be at or below it.

On reasoning models, thinking tokens usually count toward this limit, so long reasoning leaves less room for the visible answer. When the limit is hit, generation stops and the API reports a stop reason such as "max_tokens" or "length" instead of a normal finish. Some APIs require the value; others apply a default lower than the model's maximum.

Set a limit that fits your longest expected answer plus reasoning headroom. A high limit is not billed by itself (you pay for tokens actually generated), but it raises the worst-case cost and latency of a single request.

Worked example

With an illustrative per-request limit of 8,000 tokens on a reasoning model: if it spends 6,500 tokens thinking, only 1,500 remain for the answer, roughly 1,100 words. A 3,000-word report would stop partway through.

Common mistakes

• 1Not checking the stop reason, so truncated replies are treated as complete (broken JSON, half-written files).
• 2Setting a low limit on a reasoning model and getting a short or empty answer because thinking used most of it.
• 3Confusing the model's published maximum with the API's default per-request value.