DeepSeek Thinking Mode: Versioned Integration Checklist

Why this URL says R1

This page used to explain DeepSeek-R1 and the deepseek-reasoner model, with 64K-context figures, R1-era prices, latency estimates and advice to log or display reasoning output. Those claims are historical and are not current guidance. The URL is kept so existing links work. Do not treat the historical R1 model as the same thing as a current model: on October 27, 2026 the official pricing page lists deepseek-flash (DeepSeek-V4.1-Flash-1017) and deepseek-v4-pro (DeepSeek-V4-Pro-0813), both supporting non-thinking and thinking modes, with thinking as the default. Pick a model and mode for your task, record the version you got, and recheck the docs when versions change.

Official controls by API format

The thinking mode guide documents different controls per format. OpenAI format: thinking is toggled with {"thinking": {"type": "enabled"}} or "disabled", and effort with reasoning_effort set to low, high or max. With the OpenAI Python SDK, the thinking object goes inside extra_body. Anthropic format and Responses API format use their own parameter shapes. Fields do not carry over automatically between formats, so copy the exact shape from the docs for the format you call. Default: thinking enabled, effort high. Other requested effort labels are mapped to low, high or max.

Parameters that behave differently

• temperature, presence_penalty and frequency_penalty have no effect in thinking mode. They do not raise an error, so a test that sets them can silently measure nothing.
• top_p is model-specific. The docs describe different behaviour for deepseek-flash and deepseek-v4-pro, and it also depends on mode and on whether tools are present. Do not apply one model's rule to the other; read the current table.
• reasoning_content is returned at the same level as content in thinking mode.

reasoning_content: protocol history vs public logs

Two separate questions are often mixed up. Protocol: if a request carries tools, the docs say the reasoning_content of all previous turns must be passed back in full, including turns where no tool was called; failing to do so returns a 400 error. If a request carries no tools, reasoning_content does not need to be passed back and is ignored if sent. Exposure: keeping a record for the next API call does not mean you should show it to users, write it to analytics, or keep it forever. Hold protocol history in short-lived, access-controlled request state, keep it out of public logs and tickets, strip secrets and personal data before any diagnostic copy, and delete it when the conversation ends. Reasoning text is not a trustworthy account of why the model answered; verify the answer itself.

Tool calls are proposals, not permission

When the model returns tool_calls it is proposing an action. Your code decides whether it happens. Validate the arguments against the JSON schema, check the tool name against an allowlist, confirm the user is authorized for that side effect, and require explicit confirmation for anything destructive or costly. Answer each tool_call_id with a role "tool" message, append the whole assistant record before those replies, and only then send the next request. The examples on this page are offline mocks: they show message shapes, not output the API is guaranteed to return, and they perform no real action.

Integration worksheet

Record one row per integration or test run. It turns an ad hoc integration into something you can compare after a model or docs change.

Offline fixtures: two flows

The conceptual fixtures below show the message history your code should send next. They are not captured API responses and are not copy-paste SDK code; field order, IDs and text are illustrative.

// Next request, no "tools" in it.
// reasoning_content from turn 1 is ignored by the API, so it can be omitted.
{
  "model": "deepseek-flash",
  "messages": [
    { "role": "user", "content": "<question 1>" },
    { "role": "assistant", "content": "<final answer 1>" },
    { "role": "user", "content": "<question 2>" }
  ]
}

// Next request, "tools" present. Keep the WHOLE assistant record,
// then answer each tool_call_id. Mock values; no real tool was run.
{
  "model": "deepseek-v4-pro",
  "tools": [ { "type": "function", "function": { "name": "get_weather", "parameters": { ... } } } ],
  "messages": [
    { "role": "user", "content": "<question>" },
    {
      "role": "assistant",
      "content": "",
      "reasoning_content": "<kept for protocol only>",
      "tool_calls": [ { "id": "call_mock_1", "type": "function",
        "function": { "name": "get_weather", "arguments": "{\"location\":\"<city>\"}" } } ]
    },
    { "role": "tool", "tool_call_id": "call_mock_1", "content": "<validated mock result>" }
  ]
}

Stream and finish-state checklist

• Missing or empty content is not by itself a final failure; check the finish reason and whether tool_calls were returned.
• Content alone is not completion, and neither is a stream ending or a finish_reason on its own. Treat a streamed answer as a candidate final answer only when the stream ended normally AND finish_reason is "stop" (a natural finish); then still verify the answer itself.
• finish_reason "length" means the turn was cut off: incomplete, not final. finish_reason "tool_calls" means the model is waiting for your tool results: not a final answer.
• Any other or missing finish_reason, an error event, or a transport close (connection dropped, timeout) leaves the turn unverified, even if text arrived.
• If a stream breaks with an unknown partial state, do not automatically repeat non-idempotent side effects (payments, emails, writes). Reconcile what already happened first.
• For HTTP errors and retry decisions, use the existing error diagnostic in the DeepSeek rate limits and retries guide rather than retrying blindly.

Open the DeepSeek error diagnostic →

Evaluation log, not benchmarks

This page publishes no benchmark scores and no latency guarantees. To decide between modes or models, log for each run: the task and its acceptance check, model and mode settings, effort, whether tools were present, how you measured latency (time to first token, time to finish, client or server side), the usage object returned, and whether the answer was verified correct by a test or reviewer. Compare cost per verified-correct task, not per call.

Cost: read usage, then current pricing

Thinking output is billed as output tokens, so cost comes from the usage object the API returns for each request, multiplied by the rates on the official pricing page for the model and time. The token usage docs say the returned usage is the source of truth; offline tokenizer counts are estimates. The pricing page lists peak hours as 01:00–04:00 and 06:00–10:00 UTC, Monday through Friday, excluding Chinese public holidays; whether a given request falls in peak depends on that calendar, so do not infer it from the clock alone. This guide deliberately omits numeric prices. See the pricing guide on this site, and confirm figures against the official page before budgeting.

Context and output budget

The official pricing page lists a 1M-token context length and a maximum output of 384K tokens for the current models. Your effective limit can still vary by model, endpoint, format or request settings, so check the current docs for what you call. The remaining budget must cover input, reasoning and final output together, and not every workload fits: long documents plus high effort can exhaust output before the answer finishes.

Sources and methodology

Checked October 27, 2026 against the official DeepSeek API docs listed below. Rules on this page summarize those docs; the worksheet, fixtures, checklist and privacy advice are authored guidance from deepseek.health, not official DeepSeek instructions. No API requests were made to write this page.