Updated 2026-06-27
DeepSeek JSON Output guide: use the official contract, not wishful prompting
DeepSeek's official JSON Output page is more specific than 'ask the model for JSON.' The docs say structured output is a contract with multiple parts: set `response_format` correctly, include the word `json` in the prompt, show the target shape, and keep `max_tokens` high enough that the response does not truncate midway. DeepSeek also warns that empty content can still appear occasionally in this mode, which makes this a useful support-query page instead of a generic API tutorial.
1. The official switch is `response_format={ type: 'json_object' }`
DeepSeek's first rule is explicit: JSON Output is not enabled by prose alone. The request must include `response_format` with `type` set to `json_object`.
If that field is missing, you are back in normal text-generation mode, even if the prompt asks politely for JSON.
response = client.chat.completions.create(
model="deepseek-v4-pro",
messages=messages,
response_format={"type": "json_object"},
)Sources checked
- DeepSeek official JSON Output guide - Primary source for the response_format rule, prompt requirements, and empty-content caveat.
2. DeepSeek wants the word `json` in the prompt and an example shape
The official docs do not rely on the transport flag alone. They say the system or user prompt should contain the word `json` and should provide an example of the desired JSON structure.
That means the strongest DeepSeek JSON requests are doubly constrained: the API is told to return a JSON object, and the prompt shows what keys and value shapes you actually want.
The user will provide some exam text. Please parse the "question" and "answer" and output them in json format.
EXAMPLE JSON OUTPUT:
{
"question": "Which is the highest mountain in the world?",
"answer": "Mount Everest"
}3. Keep `max_tokens` high enough to finish the object
DeepSeek's third warning is practical: set `max_tokens` reasonably so the JSON string does not cut off midway. A truncated object is often worse than plain text because downstream parsers fail hard.
This is especially important when the target object can grow, such as extraction tasks with long arrays or nested items.
4. Empty content is an official caveat, not a mystery bug
DeepSeek says the JSON Output feature can occasionally return empty content and notes that the team is still optimizing this issue.
That is a valuable support boundary. If your JSON-mode request sometimes comes back empty, do not immediately invent a transport failure or assume the API key is broken. First tighten the prompt, confirm the JSON example is clear, and retry with a payload that keeps the output bounded.
| Check | What to verify | Why |
|---|---|---|
| 1 | `response_format` is set to `json_object` | Without it, the request is not in JSON Output mode |
| 2 | Prompt includes the word `json` and an example shape | DeepSeek's official guide requires both |
| 3 | `max_tokens` is large enough | Truncation can break otherwise-correct JSON |
| 4 | Prompt scope is narrow enough | Huge or vague extraction tasks increase malformed or empty responses |
5. Parse only after you validate the contract
DeepSeek's own sample ends by calling `json.loads` on the returned content. That is the right order: constrain the output first, then parse it like a machine-readable object.
If your workload needs more open-ended reasoning plus tools, compare `/guides/deepseek-thinking-mode-tool-calls` next. If the real problem is preserving conversation context across turns, continue with `/guides/deepseek-chat-completions-stateless-history`.
6. Keep the commercial boundary disciplined
JSON Output is an API capability, not a new stocked product. It should not trigger changes to plan cards, plan copy, or inventory tables.
Use `/pricing` only when the user needs an in-stock DeepSeek key route that the site actually sells. The JSON mode feature itself does not imply any new product availability.
FAQ
How do I enable DeepSeek JSON Output officially?
Set `response_format` to `{"type": "json_object"}` and include the word `json` in the prompt with an example of the desired output shape.
Why does DeepSeek still return bad or empty JSON sometimes?
DeepSeek's official guide says JSON mode can occasionally return empty content. Tighten the prompt, keep the structure explicit, and make sure the output budget is large enough.
Do I need to show an example JSON object in the prompt?
Yes. DeepSeek explicitly recommends giving an example of the desired JSON format to guide the model.
Can `max_tokens` break valid JSON?
Yes. If `max_tokens` is too low, the object can truncate in the middle, leaving invalid JSON for downstream parsing.
Does this page mean DeepSeek sells a separate structured-output plan on `/pricing`?
No. This page explains an API feature only. Purchasable plans still depend on actual stocked inventory.
The practical DeepSeek JSON rule is simple: enable `json_object`, say `json` in the prompt, show the target shape, give the response room to finish, and treat empty content as an official edge case you design around instead of a mystery.
Related model comparisons
Continue from this guide into structured DeepSeek-first comparison pages with model tables, routing advice, and pricing context.