What's the difference between deepseek-chat and deepseek-reasoner?

deepseek-chat is a general-purpose model optimized for latency and cost. deepseek-reasoner (R1) trades latency for accuracy on multi-step reasoning by emitting a hidden chain-of-thought before the final answer.

Is DeepSeek OpenAI-compatible?

Yes. The /v1/chat/completions endpoint accepts the same message format, streaming, tools, and response_format schema as OpenAI's API — most SDKs work by swapping the base URL and API key.

What does 'prefix caching' actually cache?

The leading tokens of your prompt that exactly match a recent request — typically the system prompt, few-shot examples, and tool schema. Matching prefixes bill at the cache-hit rate (~4× cheaper than a miss).

A token is the basic unit of text that the model processes and bills. It is usually about 4 characters of English text or roughly three-quarters of a word.

Can I run DeepSeek models locally?

Yes. The R1 and V3 weights are available under permissive licenses, and the smaller distilled variants can run on consumer GPUs via Hugging Face Transformers, Ollama, or vLLM.

What is a context window?

The maximum number of tokens a single request can contain, including both the prompt and the generated response. DeepSeek hosted models support 64K tokens.

What is the difference between cache hit and cache miss?

A cache hit means the leading tokens of your prompt matched a recently cached prefix, so those tokens are billed at a lower rate. A cache miss means they did not match, and you pay the full rate.

What does 'reasoning_content' mean?

It is the internal chain-of-thought that R1 generates before the final answer. It is returned separately in the API and counts toward output billing.

DeepSeek API glossary

Foundations

Token — the atomic unit of text billed by the API. Roughly 4 characters of English or ~0.75 words.
Context window — how many tokens (input + output) a single call can carry. DeepSeek hosted models: 64K.
Completion — the model's generated response, streamed or returned as one object.
Prompt — the input text you send to the model, including system instructions and prior messages.
System prompt — the first message that sets the model's role, style, and constraints for the conversation.

Architecture

MoE (Mixture of Experts) — only a subset of the model's parameters activate per token, cutting compute cost.
Distillation — training a smaller student model on outputs of a larger teacher. DeepSeek ships R1-distilled Llama/Qwen variants.
Chain-of-thought (CoT) — an intermediate reasoning trace generated before the final answer.
Reinforcement learning — the training signal used by R1 to learn reasoning behavior without supervised examples for every step.
KV cache — the stored key/value activations from earlier tokens, reused to avoid recomputation.

API surface

/v1/chat/completions — the OpenAI-compatible chat endpoint. Accepts messages, stream, tools, response_format.
/v1/models — lists the models available to your account.
reasoning_content — R1-only field carrying the model's chain-of-thought during streaming.
Tool calling / function calling — structured JSON invocation of app-defined tools by the model.
JSON mode — forcing the model to output valid JSON via response_format.
Streaming / SSE — Server-Sent Events that deliver tokens one at a time as they are generated.

Pricing

Cache hit / cache miss — whether the leading tokens of your prompt matched a recent request's prefix cache.
TPM / RPM — tokens-per-minute and requests-per-minute, the two rate-limit dimensions.
Prepaid balance — DeepSeek is prepaid; top up in the console before your balance hits zero.
Output tokens — every token the model emits, including reasoning_content and content.
Input tokens — the tokens in your prompt, billed at cache-hit or cache-miss rates.

Operations

429 Too Many Requests — you hit a rate limit; retry with backoff.
402 Payment Required — your balance is exhausted; top up.
SSE (Server-Sent Events) — the streaming transport used by chat completions when stream=true.
Fallback provider — a second host of the same model used when the primary 429s or 5xxes.
Circuit breaker — a pattern that stops requests for a cooldown period after repeated failures.
Exponential backoff — a retry delay that doubles each attempt, plus jitter to avoid thundering herds.

Related concepts

OpenAI-compatible — an API shape that mirrors OpenAI's /v1/chat/completions. DeepSeek, Mistral, Together, and many others support it.
Streaming — returning response tokens one at a time via SSE instead of one final JSON blob. Improves perceived latency.
JSON mode — forcing the model to emit valid JSON by setting response_format to { type: 'json_object' }.
System prompt — the initial message that sets behavior for the rest of the conversation.
Few-shot prompting — adding examples in the prompt to steer the model's output format or reasoning style.
Temperature — a sampling parameter controlling randomness. Lower is more deterministic; higher is more creative.
Top-p / nucleus sampling — another sampling control that limits the token pool to the smallest set whose cumulative probability exceeds a threshold.

Quick-start checklist

Create an API key and top up your balance.
Point your OpenAI SDK to https://api.deepseek.com/v1.
Start with deepseek-chat for general tasks; try deepseek-reasoner for hard reasoning.
Set client timeouts to 60s for R1 and 30s for chat.
Add exponential-backoff retries for 429/5xx errors.
Monitor cache-hit ratio and adjust prompts to reuse prefixes.
Set daily spend alerts and separate staging from production keys.

Where to learn more

For deeper reads, see the companion guides on this site: pricing, R1 reasoning, coding comparisons, and rate limits. The broader OpenAI-compatible ecosystem is also tracked by our sister sites, which cover Mistral's hosted API, Hugging Face's open model hub, and the dev platforms that make deploying LLM apps easier. Each guide is written to stand alone, but together they cover the full lifecycle of a production DeepSeek integration.

API errors and HTTP codes

Beyond 429 and 402, you may see 401 for invalid keys, 400 for malformed requests, and 5xx for provider-side failures. Log the full response body on errors because DeepSeek often returns a message explaining what went wrong. 408 and network timeouts are usually client-side; increase the timeout or retry once. 503 during peak load is normal; that is why backoff and fallback exist.

Deployment patterns

The simplest pattern is direct API calls from your backend. For higher scale, add a queue, cache, and fallback provider. For strict latency requirements, consider a self-hosted or edge-deployed model. For experiments, use a thin client wrapper. The right pattern depends on your traffic shape, budget, and tolerance for occasional provider hiccups. Most production systems end up as a hybrid: hosted API for flexibility, with caching and fallback for reliability.

Evaluation and safety terms

Hallucination — a confident but incorrect output. Jailbreak — an attempt to bypass safety instructions. Guardrail — a layer that checks or filters model outputs before they reach users. Red-teaming — structured testing to find failure modes. Benchmarks like HumanEval and SWE-bench measure code performance; MMLU measures broad knowledge. None of these scores replace testing on your own data.

Model names and variants

deepseek-chat is the general-purpose chat model. deepseek-reasoner (R1) is the reasoning model. V3 is the underlying base model architecture. Distilled R1 models are smaller student models trained on R1 output, available in sizes like 1.5B, 7B, 14B, and 32B parameters. The full R1 is larger and requires hosted inference or serious hardware. When you see these names in docs or in the /v1/models list, you now know which class each belongs to.

Sampling and decoding terms

Tokenizer — the byte-pair-encoding component that splits input text into tokens; DeepSeek uses its own tokenizer, close in behavior to GPT's but not identical, so token counts differ slightly from OpenAI counters.
Temperature — sampling randomness knob; 0 is nearly deterministic, 1 is default creative, above 1 is chaotic. Coding and extraction use 0.0–0.3; brainstorming uses 0.7–1.0.
Top-p (nucleus sampling) — restricts sampling to the smallest set of tokens whose cumulative probability exceeds p; 0.9 is a common default that trims the long tail without flattening variety.
Stop sequences — strings that force the model to stop generating when emitted; useful to end structured output cleanly (for example stopping at ``` after a code block).
max_tokens — the hard cap on output length, including R1 reasoning tokens; set high enough that the final answer is not truncated mid-sentence.
Seed — a value that makes sampling reproducible when supported; DeepSeek honors seed for chat completions to help with debugging and tests.

Prompting and tool terms

System prompt — the first message that sets role, tone, and constraints; keep it stable so DeepSeek's prefix cache can bill at the hit rate.
Few-shot prompting — including 1–5 worked examples in the prompt to steer format and style without fine-tuning.
Tool schema — the JSON Schema you attach to tools[]; simpler schemas fail less often than deeply nested ones.
Function calling — the mechanism by which the model emits a structured JSON call to one of your tools instead of a text reply.
Streaming — receiving tokens over SSE as they are produced; combined with reasoning_content for R1, it drives responsive UIs.
KV cache — the internal reuse of key/value activations across tokens in a single request; unrelated to prefix caching, which is cross-request.

Reliability and cost terms in one place

A tight vocabulary makes on-call conversations shorter: 429 = rate-limited, retry with backoff; 402 = out of balance, stop and alert; 5xx = provider fault, retry then fall back; 400 = validation error, do not retry; 401 = bad key, rotate. Cache-hit and cache-miss describe billing state, not correctness. TPM and RPM are the two rate-limit dimensions; you can hit either first. Fallback provider, circuit breaker, and exponential backoff are the three defensive patterns that keep a workload healthy. Reasoning tokens are billed as output tokens; input tokens are billed at cache-hit or cache-miss rates. Keep this glossary open in your engineering wiki so new teammates can join an incident channel and understand what everyone is saying.