Skip to main content
Reasoning models perform internal thinking before producing an answer. They are significantly stronger at math, code, planning and logic problems than ordinary models, but with higher latency and cost.

​
Supported models

VendorModel / suffixHow to enable
OpenAIo3-mini-low/medium/high, o3, gpt-5.5-low/medium/highBuilt into the model ID / reasoning_effort
Anthropicclaude-*-thinking, base model + thinking paramBuilt into the model ID / thinking param
Googlegemini-2.5-pro-thinking, -low/medium/highBuilt into the model ID / thinking_budget
DeepSeekdeepseek-r1Use the model ID directly

​
OpenAI

​
Via model ID

resp = client.chat.completions.create(
    model="o3-mini-high",
    messages=[{"role": "user", "content": "Prove that √2 is irrational"}],
    max_completion_tokens=4096,
)
print(resp.usage.completion_tokens_details.reasoning_tokens)

​
Via parameter (Responses API)

resp = client.responses.create(
    model="o3-mini",
    input="Prove that √2 is irrational",
    reasoning={"effort": "high"},
    max_output_tokens=4096,
)
Notes:
  • Reasoning models do not support some parameters like temperature, top_p, presence_penalty.
  • Use max_completion_tokens (new) rather than max_tokens.
  • reasoning_tokens are invisible but billed — be sure to leave enough budget.

​
Claude

resp = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    thinking={"type": "enabled", "budget_tokens": 8000},
    messages=[{"role": "user", "content": "Prove Fermat's little theorem"}],
)

for block in resp.content:
    if block.type == "thinking":
        print("[thinking]", block.thinking)
    elif block.type == "text":
        print("[answer]", block.text)
  • budget_tokens: the thinking budget ceiling, typically 1024-32000.
  • Thinking blocks are visible by default — unlike OpenAI, you can read the reasoning process.
  • Billing: thinking_tokens are billed additionally at the output price.

​
Gemini

resp = client.models.generate_content(
    model="gemini-3.1-pro-preview",
    contents="Prove Goldbach's conjecture",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_budget=8000),
    ),
)
print(resp.usage_metadata.thoughts_token_count)
Or use a preset ID:
IDBehavior
gemini-2.5-pro-thinkingDefault medium thinking budget
gemini-2.5-pro-thinking-128Force a 128-token thinking budget
gemini-2.5-flash-nothinkingThinking off (cheaper)
gemini-2.5-pro-highHigh reasoning effort

​
When to use a reasoning model

✅ Good for

  • Math proofs, complex logic problems
  • Code refactoring, bug localization
  • Multi-step planning, agent decisions
  • Long-document analysis, research reviews

❌ Not needed for

  • Ordinary Q&A, casual chat
  • Translation, summarization, rewriting
  • Simple classification, info extraction

​
Billing reminders

  • Reasoning tokens are not shown in content but are still billed at the output price.
  • The console log breaks out thinking / answer into two parts.
  • When setting max_completion_tokens / max_output_tokens, leave plenty of headroom (≥ 4096 recommended), or the answer may come back empty due to token exhaustion.

​
Streaming

Reasoning models can stream, but during the thinking phase there are no delta contents — the client sees a blank period first (possibly several seconds) before the answer starts arriving. Add a loading state in your UI. Claude / Gemini streaming can receive thinking-block deltas, enabling a “visible thinking process.”