DeepSeek JSON Output: Return Valid JSON with the DeepSeek API

Last verified: April 27, 2026.

DeepSeek JSON Output is the Chat Completions feature for returning valid JSON in the assistant message content. Use deepseek-v4-flash or deepseek-v4-pro, set response_format: { "type": "json_object" }, include the word json in your prompt, show a target JSON shape, set enough max_tokens, then parse and validate the response in your application.

Independent site disclosure: Chat-Deep.ai is an independent DeepSeek guide and browser access site. It is not the official DeepSeek website, not the official DeepSeek app, not the official DeepSeek developer platform, and not affiliated with DeepSeek. For the broad overview, start with our DeepSeek AI. This page is focused only on DeepSeek JSON Output for developers.

Quick Answer: How to Enable DeepSeek JSON Output

To enable DeepSeek JSON Output, use the DeepSeek Chat Completions API and ask for a JSON object explicitly. The API can help produce valid JSON, but your application must still parse, validate, and handle failures safely.

1. Use the DeepSeek Chat Completions API.
2. Use a current model ID: deepseek-v4-flash or deepseek-v4-pro.
3. Set response_format to { "type": "json_object" }.
4. Tell the model to return only valid json.
5. Include an example JSON object with the exact fields you expect.
6. Set max_tokens high enough for the full object.
7. Read and parse message.content.
8. Validate the parsed object before using it.

If you need the general setup first, read create a DeepSeek chat completion and the DeepSeek API guide.

What Is DeepSeek JSON Output?

DeepSeek JSON Output, also called DeepSeek JSON mode in some developer discussions, is a Chat Completions setting that makes the model return a valid JSON string in the assistant’s final answer. It is useful when your application needs structured output instead of free-form text.

In normal chat, a model may answer with paragraphs, bullet points, Markdown, code blocks, or a mixture of formats. That is helpful for human reading, but it can be fragile for automation. JSON Output is designed for workflows where your backend needs to parse a predictable object.

Common use cases include:

• classifying support tickets into categories and priorities
• extracting entities from emails, forms, documents, or transcripts
• generating SEO titles, meta descriptions, slugs, and content briefs
• routing messages to the right team or automation pipeline
• building dashboard-ready metadata from unstructured text
• normalizing product, order, or customer support fields
• producing structured quality checks for content, code, or data records
• creating machine-readable summaries for data pipelines

DeepSeek JSON Output is not the same as executing a function. It returns structured data in the assistant message content. If your app needs the model to request a backend action, database lookup, external API call, or workflow action, compare it with DeepSeek Tool Calls.

Official Requirements for JSON Output

The safest implementation pattern is to combine the API setting, a clear JSON-only prompt, a target shape, enough output budget, and application-side validation.

Requirement	What to do	Why it matters
response_format	Set { "type": "json_object" }.	Enables JSON Output for the model response.
Prompt instruction	Include the word json and ask for valid JSON only.	Prevents whitespace-heavy or seemingly stuck output.
Example shape	Show target keys, value types, enums, and nullable fields.	Reduces schema drift and missing fields.
max_tokens	Set enough output budget for the full object.	Helps prevent truncated JSON.
Parsing	Parse message.content.	Converts the JSON string into an application object.
Validation	Validate schema, enums, ranges, and business rules.	Valid JSON can still contain wrong or unsafe values.
Empty-content handling	Retry or fallback safely with non-sensitive diagnostics.	Official docs note that empty content may occasionally happen.

The main rule is simple: JSON Output improves format reliability, but it does not remove your responsibility to validate the data.

Which Model Should You Use for JSON Output?

For new JSON Output integrations, use deepseek-v4-flash or deepseek-v4-pro. Older aliases are useful only when maintaining legacy integrations.

Model	Best for	Suggested mode
deepseek-v4-flash	Classification, extraction, summaries, metadata, support routing, and high-volume structured output.	Usually non-thinking.
deepseek-v4-pro	Complex reasoning, long-context synthesis, code review reports, multi-document extraction, and high-value structured decisions.	Thinking mode when reasoning matters.

For current API rates, check the official DeepSeek Models & Pricing page before production use. You can use the official DeepSeek Models & Pricing page and the independent DeepSeek API pricing guide for context. This article does not include fixed prices because pricing can change.

For a broader model overview, read DeepSeek models.

Copy-Paste Prompt Template for DeepSeek JSON Output

A strong prompt reduces schema drift. The prompt should say json, forbid Markdown, describe how to handle missing data, and include an example object.

Return only valid json.
Do not include Markdown, comments, explanations, or code fences.

Task:
Analyze the user input and return a structured JSON object.

Rules:
- Use only the keys shown in the JSON shape.
- Use null when a value is missing or unknown.
- Use only the allowed enum values.
- confidence must be a number between 0 and 1.
- human_review_required must be true when confidence is low, the input is ambiguous, or a required field is missing.
- Do not add extra keys.

JSON shape:
{
  "category": "billing | technical | account | sales | other",
  "priority": "low | medium | high",
  "summary": "short plain-English summary",
  "detected_entities": {
    "customer_name": "string or null",
    "order_id": "string or null",
    "product": "string or null"
  },
  "confidence": 0.0,
  "human_review_required": false
}

Do not ask for JSON inside Markdown fences. Ask for the raw JSON object only. Markdown wrappers make parsing more fragile and can cause avoidable JSON.parse or json.loads failures.

Minimal cURL Example

This cURL example calls the DeepSeek Chat Completions endpoint, uses deepseek-v4-flash, sets response_format to json_object, and asks for valid JSON only.

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. Do not include Markdown, comments, explanations, or code fences. Use this shape: {\"category\":\"billing | technical | account | other\",\"priority\":\"low | medium | high\",\"summary\":\"string\",\"confidence\":0.0,\"human_review_required\":false}"
      },
      {
        "role": "user",
        "content": "I reset my password twice and still cannot access my account."
      }
    ],
    "response_format": {
      "type": "json_object"
    },
    "thinking": {
      "type": "disabled"
    },
    "max_tokens": 500,
    "stream": false
  }'

In production, do not run secret-bearing requests from browser JavaScript. Keep the API key in a backend service, serverless function, or private server environment.

Python Example: Parse and Validate DeepSeek JSON Output

This Python example uses the OpenAI SDK configured with DeepSeek’s base URL. It checks for empty content, parses JSON with json.loads, checks finish_reason, and validates the object with a small local function.

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",
)

ALLOWED_CATEGORIES = {"billing", "technical", "account", "other"}
ALLOWED_PRIORITIES = {"low", "medium", "high"}


def is_ticket_label(value: Any) -> bool:
    if not isinstance(value, dict):
        return False

    if value.get("category") not in ALLOWED_CATEGORIES:
        return False

    if value.get("priority") not in ALLOWED_PRIORITIES:
        return False

    if not isinstance(value.get("summary"), str):
        return False

    confidence = value.get("confidence")
    if not isinstance(confidence, (int, float)):
        return False

    if confidence < 0 or confidence > 1:
        return False

    if not isinstance(value.get("human_review_required"), bool):
        return False

    return True


def classify_ticket(user_text: str) -> dict[str, Any]:
    system_prompt = """
Return only valid json.
Do not include Markdown, comments, explanations, or code fences.

Classify the support ticket into this JSON shape:
{
  "category": "billing | technical | account | other",
  "priority": "low | medium | high",
  "summary": "short summary",
  "confidence": 0.0,
  "human_review_required": false
}

Use human_review_required=true when the input is ambiguous or confidence is below 0.75.
""".strip()

    response = client.chat.completions.create(
        model="deepseek-v4-flash",
        messages=[
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": user_text},
        ],
        response_format={"type": "json_object"},
        extra_body={"thinking": {"type": "disabled"}},
        max_tokens=500,
        stream=False,
    )

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

    if choice.finish_reason == "length":
        raise RuntimeError(
            "JSON output may be truncated. Increase max_tokens, reduce fields, or split the task."
        )

    if not content:
        raise RuntimeError(
            "DeepSeek returned empty content. Clarify the prompt and retry with limits."
        )

    try:
        parsed = json.loads(content)
    except json.JSONDecodeError as exc:
        raise RuntimeError("Model output was not parseable JSON.") from exc

    if not is_ticket_label(parsed):
        raise RuntimeError("Parsed JSON did not match the expected schema.")

    return parsed


if __name__ == "__main__":
    result = classify_ticket(
        "I cannot log in after resetting my password. The reset link says it expired."
    )
    print(json.dumps(result, indent=2))

A safe retry strategy can retry once or twice after clarifying the prompt, increasing max_tokens, or reducing the requested fields. Avoid unbounded retries, and log only non-sensitive diagnostics.

For more Python setup context, read the DeepSeek Python SDK guide.

TypeScript Example: JSON.parse with a Type Guard

This server-side TypeScript example uses the OpenAI JavaScript/TypeScript SDK configured with DeepSeek’s base URL. Never expose DEEPSEEK_API_KEY in browser JavaScript.

import OpenAI from "openai";

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

type TicketLabel = {
  category: "billing" | "technical" | "account" | "other";
  priority: "low" | "medium" | "high";
  summary: string;
  confidence: number;
  human_review_required: boolean;
};

type DeepSeekJsonRequest =
  Parameters<typeof client.chat.completions.create>[0] & {
    thinking?: {
      type: "enabled" | "disabled";
    };
  };

function isTicketLabel(value: unknown): value is TicketLabel {
  if (!value || typeof value !== "object") return false;

  const candidate = value as Record<string, unknown>;

  const validCategory =
    candidate.category === "billing" ||
    candidate.category === "technical" ||
    candidate.category === "account" ||
    candidate.category === "other";

  const validPriority =
    candidate.priority === "low" ||
    candidate.priority === "medium" ||
    candidate.priority === "high";

  const validConfidence =
    typeof candidate.confidence === "number" &&
    candidate.confidence >= 0 &&
    candidate.confidence <= 1;

  return (
    validCategory &&
    validPriority &&
    typeof candidate.summary === "string" &&
    candidate.summary.length > 0 &&
    validConfidence &&
    typeof candidate.human_review_required === "boolean"
  );
}

export async function classifyTicket(input: string): Promise<TicketLabel> {
  const request: DeepSeekJsonRequest = {
    model: "deepseek-v4-flash",
    messages: [
      {
        role: "system",
        content: `
Return only valid json.
Do not include Markdown, comments, explanations, or code fences.

Classify the support ticket into this JSON shape:
{
  "category": "billing | technical | account | other",
  "priority": "low | medium | high",
  "summary": "short summary",
  "confidence": 0.0,
  "human_review_required": false
}

Use human_review_required=true when confidence is low or the input is ambiguous.
        `.trim(),
      },
      {
        role: "user",
        content: input,
      },
    ],
    response_format: { type: "json_object" },
    thinking: { type: "disabled" },
    max_tokens: 500,
    stream: false,
  };

  const response = await client.chat.completions.create(request);
  const choice = response.choices[0];

  if (choice?.finish_reason === "length") {
    throw new Error(
      "JSON output may be truncated. Increase max_tokens, reduce fields, or split the task."
    );
  }

  const content = choice?.message?.content;

  if (!content) {
    throw new Error(
      "DeepSeek returned empty content. Clarify the prompt and retry with limits."
    );
  }

  let parsed: unknown;

  try {
    parsed = JSON.parse(content);
  } catch (error) {
    throw new Error("Model output was not parseable JSON.");
  }

  if (!isTicketLabel(parsed)) {
    throw new Error("Parsed JSON did not match the expected schema.");
  }

  return parsed;
}

Some SDK typings may not always include DeepSeek-specific fields such as thinking. A narrow local typed request-body extension is safer than disabling TypeScript checks across the project.

For a full Node.js implementation, read DeepSeek Node.js TypeScript. For SDK migration notes, see OpenAI SDK with DeepSeek.

JSON Output with Thinking Mode

For simple JSON tasks such as classification, metadata generation, extraction, tagging, and support routing, start with deepseek-v4-flash and thinking disabled. This keeps the workflow direct and easier to debug.

For harder tasks, such as multi-document extraction, long-context synthesis, complex code review reports, or decisions that require careful reasoning, use deepseek-v4-pro with thinking mode enabled.

{
  "model": "deepseek-v4-pro",
  "thinking": {
    "type": "enabled"
  },
  "reasoning_effort": "high",
  "response_format": {
    "type": "json_object"
  }
}

In thinking mode, reasoning-related output is separate from the final answer. The JSON object your application parses should be in the final assistant content, not in raw reasoning fields. For user interfaces, show the final structured result or a human-readable rendering of it, not raw chain-of-thought style content.

For more detail, read DeepSeek Thinking Mode.

DeepSeek JSON Output vs Tool Calls

DeepSeek JSON Output and Tool Calls both use structured data, but they solve different problems. JSON Output is best when you want a structured answer. Tool Calls are best when the model needs to request a backend function that your application will execute.

Feature	JSON Output	Tool Calls
Purpose	Return a structured answer.	Let the model request a backend function.
Output location	Assistant content.	tool_calls.
Who executes action?	No action is executed; your app parses JSON.	Your application validates arguments and executes the function.
Best for	Classification, extraction, metadata, scoring, structured summaries.	Database lookup, API calls, account actions, workflow actions.
Validation needed?	Yes.	Yes, especially for tool arguments.

Do not use JSON Output to trigger real external actions when Tool Calls are the right tool. If the model needs to look up an order, update a record, send a message, or call an external service, use Tool Calls and validate every argument before execution.

For function-calling workflows, read DeepSeek Tool Calls.

Schema Validation: What JSON Output Does and Does Not Guarantee

JSON Output helps the model return valid JSON. It does not guarantee that the object follows your exact schema, business rules, permissions, or downstream workflow requirements.

Your application should validate:

• required keys
• allowed enum values
• number ranges
• date formats
• null handling
• confidence thresholds
• human-review flags
• business rules
• permission checks

For example, this is valid JSON but still bad application data:

{
  "category": "urgent_payment_reset",
  "priority": "extreme",
  "summary": "",
  "confidence": 9.7,
  "human_review_required": "no"
}

The object is parseable, but the category is not in the allowed enum, the priority is invalid, the summary is empty, confidence is outside the expected range, and human_review_required is a string instead of a boolean. Treat schema validation as a required production step, not an optional improvement.

Troubleshooting DeepSeek JSON Output

Most JSON Output failures come from vague prompts, missing JSON instructions, truncation, schema drift, or confusing JSON Output with Tool Calls.

Symptom	Likely cause	Fix
Request seems stuck	The prompt does not clearly ask for json.	Add a direct JSON-only instruction and an example shape.
Empty content	Known possible edge case.	Log safely, clarify the prompt, retry with limits, or fallback.
JSON.parse fails	Markdown, explanation text, or truncation.	Remove Markdown requests, increase max_tokens, and check finish_reason.
Missing keys	The prompt shape is too vague.	Provide an exact example, validate, and retry if appropriate.
Wrong enum values	No allowed list was provided.	Include allowed enum values and reject invalid output.
finish_reason="length"	Output is too large or max_tokens is too low.	Increase max_tokens, reduce fields, or split the task.
400	Invalid request format.	Compare the request body with the official schema.
422	Invalid parameters.	Remove unsupported parameters and use current model IDs.
Confusion with Tool Calls	An external action is needed.	Use Tool Calls instead of JSON Output.

Token Usage and Context Caching for JSON Workflows

For production JSON workflows, monitor usage fields to understand prompt size, completion size, and caching behavior. Use these fields for observability, capacity planning, and prompt optimization.

{
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0,
    "prompt_cache_hit_tokens": 0,
    "prompt_cache_miss_tokens": 0
  }
}

DeepSeek context caching is enabled by default. It can matter when repeated system prompts, fixed JSON schemas, or shared long-context prefixes appear across requests. Monitor prompt_cache_hit_tokens and prompt_cache_miss_tokens where available, especially in high-volume structured-output pipelines.

Do not hard-code pricing assumptions into JSON Output content or production estimates.

For more detail, read DeepSeek Context Caching. For current API rates, check the official DeepSeek Models & Pricing page before production use.

Legacy Migration: Old JSON Output Examples

Older tutorials may use deepseek-chat or deepseek-reasoner. For new DeepSeek JSON Output examples, use deepseek-v4-flash or deepseek-v4-pro instead.

The older names are legacy compatibility aliases. During the transition, deepseek-chat corresponds to non-thinking behavior of deepseek-v4-flash, and deepseek-reasoner corresponds to thinking behavior of deepseek-v4-flash. They are scheduled to be retired after July 24, 2026, 15:59 UTC.

Recommended migration

{
  "old_model": "deepseek-chat",
  "new_model": "deepseek-v4-flash",
  "thinking": {
    "type": "disabled"
  }
}

{
  "old_model": "deepseek-reasoner",
  "new_model": "deepseek-v4-pro",
  "thinking": {
    "type": "enabled"
  },
  "reasoning_effort": "high"
}

Legacy model names are for compatibility only and should not be treated as the current recommended model IDs for API integrations.

Production Checklist

• API key is stored server-side.
• Current model IDs are used.
• The prompt clearly asks for valid JSON.
• The prompt includes an example JSON shape.
• The prompt does not request Markdown output.
• max_tokens is large enough for the full object.
• Your code parses message.content.
• Your code validates the schema.
• Your code validates business rules.
• Your code checks finish_reason.
• Your code handles empty content.
• Retries have limits.
• Logs avoid sensitive data.
• No browser-side secret key is used.
• No static pricing assumptions are embedded.
• Official DeepSeek docs are verified before launch.

FAQ

Official Sources and Last Verified

Last verified: April 27, 2026.

DeepSeek model names, endpoint behavior, JSON Output behavior, beta features, output limits, and pricing can change. Use official DeepSeek documentation before shipping production code.

• DeepSeek API Docs Quick Start
• DeepSeek Create Chat Completion API reference
• DeepSeek JSON Output
• DeepSeek Tool Calls
• DeepSeek Thinking Mode
• DeepSeek Context Caching
• DeepSeek Error Codes
• DeepSeek V4 Preview Release
• DeepSeek Models & Pricing

Related Chat-Deep.ai guides: DeepSeek AI guide, DeepSeek API guide, create a DeepSeek chat completion, OpenAI SDK with DeepSeek, DeepSeek Node.js TypeScript, DeepSeek Python SDK, DeepSeek Tool Calls, DeepSeek Thinking Mode, DeepSeek Context Caching, DeepSeek models, and DeepSeek API pricing guide.