DeepSeek JSON Output: Return Valid JSON with the DeepSeek API

Quick answer: DeepSeek JSON Output is the API feature for asking the model to return a valid JSON string in the assistant message. In the current DeepSeek V4 API, use deepseek-v4-flash or deepseek-v4-pro, set response_format={"type":"json_object"}, clearly tell the model to return json, provide an example JSON shape, set enough max_tokens, then parse and validate the result in your application.

Use deepseek-v4-flash for fast, economical structured output such as classification, extraction, metadata generation, content labeling, ticket routing, and high-volume automation. Use deepseek-v4-pro when the JSON task needs harder reasoning, long-context analysis, complex code review, agentic planning, or careful multi-step synthesis.

Independent note: Chat-Deep.ai is an independent DeepSeek guide and browser access site. It is not affiliated with DeepSeek, DeepSeek.com, the official DeepSeek app, or the official DeepSeek developer platform. For official API keys, billing, account management, API limits, pricing, status, and production-critical behavior, use official DeepSeek resources.

Last verified: April 24, 2026.

Current DeepSeek API snapshot for JSON Output

• Current API model IDs: deepseek-v4-flash and deepseek-v4-pro
• Current API generation: DeepSeek-V4 Preview
• Base URL for OpenAI-compatible requests: https://api.deepseek.com
• JSON Output parameter: response_format={"type":"json_object"}
• Context length: 1M tokens
• Maximum output: 384K tokens
• JSON Output: supported on both current V4 API models
• Tool Calls: supported on both current V4 API models
• Thinking and non-thinking modes: supported on both current V4 API models
• Legacy aliases: deepseek-chat and deepseek-reasoner currently route to deepseek-v4-flash non-thinking and thinking modes
• Legacy alias retirement: DeepSeek says deepseek-chat and deepseek-reasoner will be retired after July 24, 2026, 15:59 UTC

This guide is updated to stay consistent with the current Chat-Deep.ai homepage, DeepSeek API guide, DeepSeek API pricing guide, DeepSeek Token Usage guide, DeepSeek Thinking Mode guide, DeepSeek Tool Calls guide, DeepSeek Python SDK guide, Node.js TypeScript guide, and DeepSeek for Coding guide.

Table of contents

• Critical update: use V4 model IDs, not old V3.2 wording
• What is DeepSeek JSON Output?
• Quick start: enable JSON Output
• DeepSeek JSON Output requirements
• Which V4 model should you use for JSON Output?
• Copy-paste JSON prompt template
• Python example with validation
• Node.js example with validation
• cURL example
• JSON Output with thinking mode
• JSON Output vs schema validation
• JSON Output vs Tool Calls
• Best use cases
• Common mistakes
• Troubleshooting
• Cost, token usage, and output length
• Production checklist
• FAQ
• Official sources

Critical update: use V4 model IDs, not old V3.2 wording

Older JSON Output examples may still show deepseek-chat and deepseek-reasoner as the primary model IDs. That wording is now outdated for new API documentation. For new DeepSeek JSON Output examples, use deepseek-v4-flash or deepseek-v4-pro directly.

Old wording	Current status	Recommended wording now
deepseek-chat as the default JSON model	Legacy compatibility alias	Use deepseek-v4-flash for fast and economical JSON Output
deepseek-reasoner for structured reasoning output	Legacy compatibility alias	Use deepseek-v4-pro when structured output needs harder reasoning
DeepSeek-V3.2 as the current hosted API family	Outdated for current hosted API pages	Use DeepSeek-V4 Preview as the current API generation
128K context as the current hosted API limit	Outdated for current V4 API docs	Use 1M context and 384K maximum output for current V4 API models
Old V3.2 pricing	Outdated	Use separate V4-Flash and V4-Pro pricing

Keep the old names only in migration notes. Do not use them as the main model names in new JSON Output code samples, FAQ answers, pricing explanations, or developer tutorials.

What is DeepSeek JSON Output?

DeepSeek JSON Output, also called JSON mode by many developers, is a Chat Completions API feature that asks the model to return a valid JSON string instead of normal natural-language text. The JSON appears in the assistant message content field, so your application can parse it with json.loads(), JSON.parse(), or a schema validation library.

JSON Output is useful when model output needs to flow into software systems: databases, dashboards, queues, CRMs, analytics pipelines, automation tools, moderation workflows, search-indexing systems, or product features that require normalized fields.

DeepSeek JSON Output should not be confused with Tool Calls. JSON Output returns a JSON object as the model’s answer. Tool Calls let the model request a function call that your application executes. If no external action is needed, JSON Output is usually simpler.

Quick start: enable JSON Output

To enable JSON Output, send a Chat Completions request with response_format set to {"type":"json_object"}. Also tell the model to return valid JSON in the prompt and show the target shape.

1. Use the DeepSeek Chat Completions endpoint.
2. Use a current model ID: deepseek-v4-flash or deepseek-v4-pro.
3. Set response_format to {"type":"json_object"}.
4. Include the word json in the system or user message.
5. Provide an example JSON object with expected keys and value types.
6. Set max_tokens high enough for the complete object.
7. Parse the returned string.
8. Validate required keys, types, enum values, ranges, and null handling.

For simple extraction and classification, use deepseek-v4-flash with thinking disabled. For complex reasoning that still needs a structured answer, use deepseek-v4-pro and parse the final content.

DeepSeek JSON Output requirements

JSON Output depends on both an API parameter and a clear prompt. Setting the parameter without instructing the model to output JSON can make the request appear stuck or produce unusable output.

Requirement	What to do	Why it matters
response_format	Set it to {"type":"json_object"}	This enables JSON Output for the assistant message
Prompt instruction	Tell the model to return only valid json	Without a JSON instruction, the model may emit whitespace until the token limit
Example shape	Show the expected keys and value types	JSON Output does not replace schema design
max_tokens	Set enough output budget for the whole object	Too small a value can cut off the JSON midway
Application validation	Parse and validate the returned object	Valid JSON can still have missing keys or wrong business values
Empty-content handling	Log, retry, or fallback safely	Official docs note that JSON Output may occasionally return empty content

Which V4 model should you use for JSON Output?

Most structured-output workflows should start with deepseek-v4-flash. Use deepseek-v4-pro when the JSON object depends on complex reasoning, long context, multi-step analysis, code review, legal-like policy parsing, or careful synthesis across many inputs.

Model	Best JSON Output use	Recommended mode
deepseek-v4-flash	Classification, extraction, metadata generation, product attributes, support-ticket routing, SEO fields, dashboards, summaries, and high-volume automation	Usually thinking: {"type":"disabled"}
deepseek-v4-pro	Hard reasoning, complex code review reports, long-context analysis, multi-document synthesis, agent planning summaries, and high-value structured decisions	Thinking enabled when reasoning matters
deepseek-chat	Migration only	Legacy alias to deepseek-v4-flash non-thinking mode
deepseek-reasoner	Migration only	Legacy alias to deepseek-v4-flash thinking mode

Copy-paste JSON prompt template

Use a system message that includes the word json, forbids Markdown, and shows the exact object shape.

Return only valid json.

Do not include Markdown, comments, explanations, or code fences.

Use this exact JSON shape:
{
  "title": "string",
  "summary": "string",
  "category": "api | pricing | models | troubleshooting | other",
  "confidence": 0.0,
  "needs_human_review": true
}

Rules:
- "confidence" must be a number between 0 and 1.
- "category" must be one of: "api", "pricing", "models", "troubleshooting", "other".
- "needs_human_review" must be boolean.
- If the input is unclear, still return valid json and set "confidence" below 0.5.

This template improves reliability, but it does not replace validation. Your application should reject or repair objects that do not match your expected schema.

Python example with validation

This Python example uses the OpenAI-compatible SDK with DeepSeek’s base URL, the current V4-Flash model ID, JSON Output, explicit non-thinking mode, and application-side validation.

import json
import os
from typing import Any

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

def validate_classification(value: Any) -> dict:
    if not isinstance(value, dict):
        raise ValueError("Expected a JSON object.")

    required = {"title", "summary", "category", "confidence", "needs_human_review"}
    missing = required - set(value)

    if missing:
        raise ValueError(f"Missing required keys: {sorted(missing)}")

    if not isinstance(value["title"], str):
        raise ValueError("title must be a string.")

    if not isinstance(value["summary"], str):
        raise ValueError("summary must be a string.")

    allowed_categories = {"api", "pricing", "models", "troubleshooting", "other"}
    if value["category"] not in allowed_categories:
        raise ValueError("category is not allowed.")

    if not isinstance(value["confidence"], (int, float)):
        raise ValueError("confidence must be a number.")

    if not 0 <= float(value["confidence"]) <= 1:
        raise ValueError("confidence must be between 0 and 1.")

    if not isinstance(value["needs_human_review"], bool):
        raise ValueError("needs_human_review must be boolean.")

    return value

system_prompt = """
Return only valid json.

Do not include Markdown, comments, explanations, or code fences.

Use this exact JSON shape:
{
  "title": "string",
  "summary": "string",
  "category": "api | pricing | models | troubleshooting | other",
  "confidence": 0.0,
  "needs_human_review": true
}
"""

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": system_prompt},
        {
            "role": "user",
            "content": "Classify this text: DeepSeek JSON Output helps developers return structured data.",
        },
    ],
    response_format={"type": "json_object"},
    max_tokens=700,
    extra_body={"thinking": {"type": "disabled"}},
)

choice = response.choices[0]
content = choice.message.content or ""

print("finish_reason:", choice.finish_reason)

if choice.finish_reason == "length":
    raise RuntimeError("The JSON may be truncated. Increase max_tokens or reduce the requested output.")

if not content.strip():
    raise RuntimeError("The response content was empty. Retry with a clearer json prompt.")

try:
    parsed = json.loads(content)
except json.JSONDecodeError as exc:
    print("Raw content:", content)
    raise RuntimeError("The response was not valid JSON or was truncated.") from exc

data = validate_classification(parsed)
print(data)

Use this pattern in production: clear prompt, current model ID, JSON Output parameter, output-length guard, parser, validator, and a safe fallback for empty or truncated content.

Node.js example with validation

This Node.js example uses the OpenAI JavaScript SDK with DeepSeek’s base URL. Keep the API key server-side; do not expose it in browser JavaScript.

import OpenAI from "openai";

const apiKey = process.env.DEEPSEEK_API_KEY;

if (!apiKey) {
  throw new Error("Missing DEEPSEEK_API_KEY");
}

const client = new OpenAI({
  apiKey,
  baseURL: "https://api.deepseek.com",
});

function validateClassification(value) {
  if (!value || typeof value !== "object" || Array.isArray(value)) {
    throw new Error("Expected a JSON object.");
  }

  const requiredKeys = ["title", "summary", "category", "confidence", "needs_human_review"];
  const missingKeys = requiredKeys.filter((key) => !(key in value));

  if (missingKeys.length > 0) {
    throw new Error(`Missing required keys: ${missingKeys.join(", ")}`);
  }

  const allowedCategories = ["api", "pricing", "models", "troubleshooting", "other"];

  if (typeof value.title !== "string") {
    throw new Error("title must be a string.");
  }

  if (typeof value.summary !== "string") {
    throw new Error("summary must be a string.");
  }

  if (!allowedCategories.includes(value.category)) {
    throw new Error("category is not allowed.");
  }

  if (typeof value.confidence !== "number" || value.confidence < 0 || value.confidence > 1) {
    throw new Error("confidence must be a number between 0 and 1.");
  }

  if (typeof value.needs_human_review !== "boolean") {
    throw new Error("needs_human_review must be boolean.");
  }

  return value;
}

const systemPrompt = `
Return only valid json.

Do not include Markdown, comments, explanations, or code fences.

Use this exact JSON shape:
{
  "title": "string",
  "summary": "string",
  "category": "api | pricing | models | troubleshooting | other",
  "confidence": 0.0,
  "needs_human_review": true
}
`;

const response = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [
    { role: "system", content: systemPrompt },
    {
      role: "user",
      content:
        "Classify this text: DeepSeek JSON Output helps developers build structured API workflows.",
    },
  ],
  response_format: { type: "json_object" },
  max_tokens: 700,
  thinking: { type: "disabled" },
});

const choice = response.choices[0];
const finishReason = choice?.finish_reason;
const content = choice?.message?.content ?? "";

console.log("finish_reason:", finishReason);

if (finishReason === "length") {
  throw new Error("The JSON may be truncated. Increase max_tokens or shorten the requested output.");
}

if (!content.trim()) {
  throw new Error("The model returned empty content. Retry with a clearer json prompt.");
}

let parsed;

try {
  parsed = JSON.parse(content);
} catch (error) {
  console.error("Raw content:", content);
  throw new Error("The response was not valid JSON or was truncated.");
}

const data = validateClassification(parsed);
console.log(data);

For TypeScript projects, consider validating with Zod, Ajv, Valibot, TypeBox, or another schema validation layer. Those libraries are not required by DeepSeek, but they are useful for production structured-output workflows.

cURL example

The same setup works with direct HTTP requests. This cURL example uses the current V4-Flash model ID and explicit non-thinking mode for a simple structured-output task.

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {
        "role": "system",
        "content": "Return only valid json with keys: title, summary, category, confidence, needs_human_review. Do not include Markdown."
      },
      {
        "role": "user",
        "content": "Classify this text: DeepSeek API JSON helps product teams normalize model output."
      }
    ],
    "response_format": {
      "type": "json_object"
    },
    "thinking": {
      "type": "disabled"
    },
    "max_tokens": 700,
    "stream": false
  }'

In a real application, do not simply print the response. Inspect choices[0].finish_reason, parse choices[0].message.content, validate the parsed object, and handle empty or truncated output.

JSON Output with thinking mode

For most structured extraction tasks, non-thinking mode is simpler and cheaper to control. Use thinking mode only when the JSON object depends on deeper reasoning or long-context analysis.

When using thinking mode, keep reasoning output separate from the final answer. Your application should parse the final assistant content, not a reasoning trace. Use deepseek-v4-pro for complex structured reasoning tasks and deepseek-v4-flash when you need a lower-cost reasoning path.

import json
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {
            "role": "system",
            "content": (
                "Return only valid json. "
                "Use keys: root_cause, evidence, risk_level, suggested_fix, tests_to_run. "
                "Do not include Markdown."
            ),
        },
        {
            "role": "user",
            "content": "Analyze this production error log and return a structured debugging report: ...",
        },
    ],
    response_format={"type": "json_object"},
    max_tokens=3000,
    reasoning_effort="high",
    extra_body={"thinking": {"type": "enabled"}},
)

message = response.choices[0].message
data = json.loads(message.content)
print(data)

Thinking mode can increase completion-side usage if the task requires more reasoning or longer output. Monitor completion_tokens and completion_tokens_details.reasoning_tokens when available.

JSON Output vs schema validation

JSON Output is not the same as a full JSON Schema enforcement layer. It is designed to return a valid JSON string, but production code still needs to validate the parsed object against business rules.

Layer	What it handles	What it does not guarantee
JSON Output	Helps the model return valid JSON in message.content	Exact schema, business correctness, allowed enum values, security, or data truth
Prompt shape	Guides the model toward your desired keys and value types	Reliable enforcement for every edge case
Application validation	Checks required keys, types, enums, ranges, nulls, and business rules	Model reasoning quality or external data truth
Tool Calls strict mode	Tighter function-argument schema behavior for tools	A replacement for user authorization, backend validation, or safe execution controls

For business-critical flows, use JSON Output as one part of the pipeline, not as the only guardrail.

DeepSeek JSON Output vs Tool Calls

JSON Output and Tool Calls are related but solve different problems. Choose JSON Output when you need a structured answer. Choose Tool Calls when the model needs to request a real function call that your backend executes.

Feature	Use it when	Output style
JSON Output	You want the assistant answer to be a JSON object	The model returns JSON in message.content
Tool Calls	The model needs to request an external function, database lookup, API call, or workflow	The model returns structured tool-call data; your application executes the function
Tool Calls strict mode	You need tighter function-argument schema behavior	The tool-call arguments follow a stricter supported schema subset

Example: use JSON Output to classify a support ticket into {"category":"billing","priority":"high"}. Use Tool Calls when the model needs to request get_order_status(order_id), search_docs(query), or another external function.

For implementation details, read the DeepSeek Tool Calls guide.

Best use cases for DeepSeek JSON Output

• Classification: categories, confidence scores, risk levels, intent labels, and routing decisions.
• Extraction: names, emails, dates, SKUs, prices, entities, IDs, and product attributes.
• Support operations: ticket summaries, urgency labels, escalation flags, and human-review markers.
• Developer tools: code review reports, test suggestions, issue severity, migration steps, and CI annotations.
• SEO workflows: title ideas, meta descriptions, content briefs, keyword intent labels, and internal link suggestions.
• Data pipelines: normalization of unstructured text into fields before storage or analytics.
• Moderation workflows: policy categories, severity labels, and explanation fields for human review.
• Product automation: structured summaries that downstream systems can inspect before taking action.

Common mistakes that break JSON Output

1. Setting response_format but not asking for JSON

The API parameter matters, but the prompt still matters. Include the word json and provide an example shape.

2. Asking for Markdown and JSON at the same time

Do not ask for “a JSON object inside a Markdown code block.” Ask for valid JSON only. Markdown fences make parsing harder.

3. Forgetting the expected shape

DeepSeek JSON Output can return valid JSON, but it does not infer your exact production schema automatically. Show the expected keys and value types.

4. Setting max_tokens too low

If the output is cut off, JSON parsing will fail. Treat finish_reason="length" as a likely truncation signal.

5. Trusting JSON without validation

Valid JSON can still be the wrong shape. Validate required keys, enum values, ranges, nulls, and business rules.

6. Using old model names in new examples

Do not present deepseek-chat or deepseek-reasoner as the primary current model IDs. Use deepseek-v4-flash or deepseek-v4-pro.

7. Treating API behavior as identical to web or app behavior

This guide covers DeepSeek API behavior. The official web chat, mobile app, independent browser chat pages, and API integrations can differ.

Troubleshooting DeepSeek JSON Output

Symptom	Likely cause	Fix
The request seems stuck	The prompt does not clearly ask for JSON	Add a system instruction that says “Return only valid json” and provide an example object
The response is empty	Known possible JSON Output edge case	Log the raw response, retry with a clearer prompt, reduce ambiguity, and use fallback logic
JSON parsing fails	Output contains Markdown, comments, extra text, or partial JSON	Improve the prompt, remove Markdown requests, increase max_tokens, and validate finish_reason
Output is cut off	max_tokens too low or output too large	Increase max_tokens, reduce requested fields, or split the job into smaller requests
The model returns wrong keys	Prompt shape is too vague	Provide an exact JSON example and reject invalid objects in your validator
400 Invalid Format	Malformed request body	Compare your request with the official Chat Completion schema
422 Invalid Parameters	Unsupported parameter, wrong model ID, or invalid value	Use deepseek-v4-flash or deepseek-v4-pro and remove unsupported fields
Confusion with Tool Calls	Trying to use JSON Output to trigger a real external action	Use Tool Calls when the model needs to request a function call

For HTTP-level debugging, read the DeepSeek Error Codes guide. For broader service issues, use the DeepSeek Status guide and confirm incidents on the official status page.

Cost, token usage, and output length

JSON Output has no separate public price line in the current official pricing table. Cost depends on the selected model and token usage: cache-hit input tokens, cache-miss input tokens, and output tokens.

Model	Input cache hit	Input cache miss	Output	JSON Output use
deepseek-v4-flash	$0.028 / 1M tokens	$0.14 / 1M tokens	$0.28 / 1M tokens	Default for cost-sensitive structured output
deepseek-v4-pro	$0.145 / 1M tokens	$1.74 / 1M tokens	$3.48 / 1M tokens	Use for complex reasoning or high-value JSON tasks

For production accounting, log the full usage object for every request. Track model ID, prompt tokens, completion tokens, cache-hit tokens, cache-miss tokens, finish reason, JSON parse failures, validation failures, retries, and empty-content cases.

For deeper accounting, read the DeepSeek Token Usage guide and the DeepSeek API Pricing guide.

Production checklist

• Use deepseek-v4-flash or deepseek-v4-pro in new examples.
• Keep deepseek-chat and deepseek-reasoner only as legacy migration aliases.
• Set response_format={"type":"json_object"}.
• Include the word json in the system or user prompt.
• Provide an example JSON object with expected keys.
• Set max_tokens high enough for the full object.
• Check finish_reason before parsing.
• Handle finish_reason="length" as possible truncation.
• Handle empty content with a controlled retry or fallback.
• Parse with json.loads(), JSON.parse(), or equivalent.
• Validate required keys, types, enum values, ranges, and null handling.
• Do not use Markdown fences if you need machine-readable JSON.
• Keep API keys out of frontend code and public repositories.
• Monitor token usage and pricing before production use.
• Log parse failures and validation failures separately.
• Use Tool Calls instead of JSON Output when the model must request a real external function.
• Remove old screenshots that show V3.2, 128K, old prices, or old aliases as current model IDs.

Related DeepSeek developer guides

• DeepSeek API Guide — current V4 model IDs, base URL, setup, and migration notes
• Create a DeepSeek Chat Completion — endpoint-level request and response details
• DeepSeek Python SDK Guide — Python examples, JSON, tools, streaming, and errors
• DeepSeek Node.js TypeScript Guide — TypeScript examples and server-side setup
• OpenAI SDK with DeepSeek — cross-language migration guide
• DeepSeek Tool Calls — function calling, strict mode, and tool loops
• DeepSeek Thinking Mode — reasoning fields and thinking-mode behavior
• DeepSeek Token Usage — usage object, streaming usage, and cost calculation
• DeepSeek Error Codes — 400, 401, 402, 422, 429, 500, and 503 fixes
• DeepSeek API Pricing — current V4 rates and billing explanation

FAQ

Conclusion

DeepSeek JSON Output is the right tool when your application needs a structured JSON answer from the model. Use response_format={"type":"json_object"}, clearly ask for valid JSON, show the expected shape, set enough output budget, and validate the parsed object before using it.

For current hosted API examples, use deepseek-v4-flash and deepseek-v4-pro. Keep deepseek-chat and deepseek-reasoner only as migration aliases. Use JSON Output for structured answers, and use Tool Calls only when the model needs to request a real external function that your backend will execute.

Official sources and last verified

Last verified: April 24, 2026. DeepSeek model names, JSON Output behavior, pricing, context limits, output limits, request parameters, and legacy alias behavior can change. Use the official sources below before shipping production code.

• DeepSeek-V4 Preview Release
• DeepSeek API Quick Start
• DeepSeek Models & Pricing
• DeepSeek Create Chat Completion API Reference
• DeepSeek JSON Output
• DeepSeek Tool Calls
• DeepSeek Thinking Mode
• DeepSeek Token & Token Usage
• DeepSeek Error Codes