Understanding Reasoning Control Parameters in Large Model APIs: A Deep Dive into reasoning_effort, thinking, and max_completion_tokens

Core Difference Between Reasoning and Non‑Reasoning Models

Traditional LLM APIs expose sampling knobs (temperature, top_p, top_k) that affect only the final output. Reasoning models add a new class of parameters that act like a resource scheduler, controlling how much computation the model spends thinking before producing an answer.

How deep should the model think?

Should the reasoning process be visible?

Maximum token budget for a single answer?

How are "thinking tokens" billed?

Thus the focus shifts from output style to thinking intensity.

Reasoning Model Characteristics (converted from table)

Generation mode : non‑reasoning – single‑stage direct output; reasoning – two‑stage (reasoning → output).

User‑visible content : non‑reasoning – only final answer; reasoning – final answer optionally accompanied by reasoning.

Parameter impact point : non‑reasoning – final output tokens; reasoning – both reasoning stage and output stage.

Cost composition : non‑reasoning – input + output tokens; reasoning – input + reasoning tokens + output tokens.

Typical models : non‑reasoning – GPT‑4o, Claude Sonnet, DeepSeek‑V3; reasoning – OpenAI o1, DeepSeek‑R1, Kimi k2.5‑thinking.

OpenAI o1 – reasoning_effort

reasoning_effort

tells the model how much "brainpower" to spend before answering. Allowed values are low, medium, and high, each with different latency and token consumption. low: shallow reasoning, fast response, few reasoning tokens. medium: moderate reasoning, balanced latency, moderate token use. high: deep reasoning for complex math, planning, scientific analysis; higher latency and token consumption.

When reasoning_effort is set, traditional sampling knobs ( temperature, top_p, presence_penalty, frequency_penalty) are locked. OpenAI expects users to trade randomness for higher correctness by increasing reasoning effort.

from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
    model="o1-2024-12-17",
    messages=[{"role": "user", "content": "一个池塘里的荷花每天增长一倍，30天长满整个池塘。问第几天长满一半？"}],
    reasoning_effort="high",
    max_completion_tokens=5000
)
print(response.choices[0].message.content)

Practical Guidance for reasoning_effort

Common‑sense Q&A or simple classification – use low (fast, cheap).

Code review, business‑logic analysis – use medium (balanced accuracy and latency).

Mathematical proofs, complex planning, scientific research – use high (max accuracy, higher cost).

Default recommendation: start with medium and adjust based on observed accuracy versus cost.

Anthropic Claude – thinking Parameter

Claude uses a top‑level thinking object with two fields: type: enabled or disabled – turns the reasoning stage on or off. budget_tokens: token budget for the thinking stage (usually ≥1024).

When enabled, the response includes a thinking field containing the model’s internal reasoning, useful for debugging and transparent business scenarios.

{
  "thinking": {
    "type": "enabled",
    "budget_tokens": 2048
  }
}

Why Claude Locks temperature

With thinking enabled, Claude requires temperature=1.0. This mirrors OpenAI’s design: the model’s correctness is driven by reasoning depth rather than sampling randomness.

DeepSeek‑R1 – thinking and reasoning_content

DeepSeek‑R1 provides a boolean thinking flag and returns reasoning_content in both streaming and non‑streaming modes.

response = client.chat.completions.create(
    model="deepseek-reasoner",
    messages=[{"role": "user", "content": "一个复杂的数学问题..."}],
    thinking=True,
    max_tokens=8192
)
reasoning = response.choices[0].message.reasoning_content
answer = response.choices[0].message.content

Key point: max_tokens limits the sum of reasoning and final output tokens. A too‑small budget can truncate the answer, leaving the reasoning exhausted before a complete answer is produced.

Kimi k2.5‑thinking – Minimal Parameter Set

Kimi locks most sampling parameters and controls length via max_completion_tokens. It also returns reasoning_content in streaming mode.

response = client.chat.completions.create(
    model="kimi-k2.5-thinking",
    messages=[{"role": "user", "content": "详细分析一下..."}],
    max_completion_tokens=8192,
    stream=True
)

Ensure the token budget is sufficient; otherwise the model will cut off the answer early.

Cross‑Platform Parameter Comparison (list format)

OpenAI o1 : reasoning_effort; sampling knobs locked; reasoning usually hidden; reasoning tokens are billed.

Anthropic Claude : thinking + budget_tokens; when enabled, temperature=1.0; reasoning field returned; reasoning tokens billed.

DeepSeek‑R1 : thinking (boolean) and reasoning_content; partial sampling control; reasoning tokens billed.

Kimi k2.5‑thinking : control via max_completion_tokens; most sampling knobs locked; streaming reasoning_content returned; reasoning tokens billed.

Google Gemini Thinking : model‑specific ability flag; partial sampling lock; reasoning field can be returned; reasoning tokens billed.

When to Use Reasoning Models

Reasoning models excel at multi‑step problems, complex math, code review, multi‑condition business logic, professional Q&A that requires derivation, and long‑document analysis. They are less suitable for casual chat, simple FAQ, basic translation, lightweight summarization, or formatting tasks.

Start
├── Does the task need multi‑step reasoning?
│   ├── Yes
│   │   ├── Need to show reasoning?
│   │   │   ├── Yes → DeepSeek‑R1 / Kimi / Gemini Thinking
│   │   │   └── No → OpenAI o1
│   │   └── Cost‑sensitive?
│   │       ├── Yes → Prefer DeepSeek‑R1
│   │       └── No → o1 / Claude Thinking
│   └── No → Use standard models (GPT‑4o, Claude Sonnet, DeepSeek‑V3)

Cost Management Strategies

Route simple requests to non‑reasoning models and reserve reasoning models for complex tasks.

Cache high‑value reasoning results that are reused frequently (e.g., legal Q&A, financial analysis, template‑based reports).

Set hard limits with max_completion_tokens, budget_tokens, or max_tokens to prevent runaway costs.

response = client.chat.completions.create(
    model="o1",
    messages=[...],
    reasoning_effort="medium",
    max_completion_tokens=3000
)

Key Takeaways

Non‑reasoning models tune output style; reasoning models tune thinking intensity.

Traditional sampling parameters are often locked in reasoning models because the design shifts from "randomness for style" to "computation for correctness".

Parameters such as reasoning_effort, thinking, and token‑budget fields directly balance accuracy, latency, and cost.

Visibility of the reasoning process (e.g., Claude’s thinking field, DeepSeek‑R1’s reasoning_content) is valuable for debugging and transparent user experiences.

Not every task needs a reasoning model; proper routing and budget caps are more important than blindly choosing the strongest model.

Series Navigation

Part 1 : Core parameter deep dive

Part 2 : Cross‑platform API comparison

Part 3 : Sampling parameter best practices

Part 4 : This article – reasoning control parameters

Part 5 : Function calling and tool usage

Part 6 : Multimodal parameters and output formats

Part 7 : Streaming responses and performance tuning

Part 8 : LLM API gateway and aggregation architecture