DeepSeek JSON Output com arquivo JSON e ícone de desenvolvimento

DeepSeek JSON Output: como gerar, analisar e validar JSON

Verificação documental: 23 de agosto de 2026. JSON Output consta como suportado em deepseek-v4-flash, deepseek-v4-pro e deepseek-v4-flash-vision-exp. O teste autenticado abaixo permanece datado de 29/07/2026, com V4 Flash textual, e não foi repetido nem recalculado.

Teste ao vivo: JSON válido e parseável

Testamos JSON Output em uma chamada autenticada e não streaming com V4 Flash, Thinking desativado e response_format: {"type":"json_object"}.

Resultado do teste DeepSeek JSON Output com status ok e parse local aprovado
Uma chamada V4 Flash retornou JSON sintaticamente válido e analisável. Isso não substitui validação de schema e regras de negócio.
ItemResultado
HTTP200
Latência observada325 ms
Conteúdo exato{"status":"ok"}
JSON.parse()Concluído sem erro
Entrada / saída / total49 / 5 / 54
Cache hit / miss0 / 49

O teste confirma apenas que esta chamada mínima retornou JSON sintaticamente válido. Não garante campos, tipos, enums, datas ou regras de negócio. Em produção, valide schema e trate finish_reason="length" antes do parsing.

Uma chamada simples não mede estabilidade em volume, schemas complexos, streaming ou respostas longas. Nenhum raciocínio bruto foi publicado.

Compare com Tool Calls, Error Codes e a documentação oficial.

Aviso de independência: DeepSeek Português é um guia de terceiros e não representa a DeepSeek. Os links oficiais estão identificados ao final da página.

O DeepSeek JSON Output faz a resposta de Chat Completions chegar como uma string JSON válida. Para ativá-lo, envie response_format: {"type":"json_object"}, mencione a palavra json no prompt, forneça um exemplo do formato desejado e reserve max_tokens suficiente.

Limite essencial: JSON Output garante o formato JSON da resposta normal, mas não garante que campos, tipos, valores ou regras do seu negócio estejam corretos. Faça JSON.parse e valide o objeto no servidor antes de salvar dados, chamar APIs ou executar ações.

Configuração mínima correta

  1. Use POST https://api.deepseek.com/chat/completions.
  2. Escolha deepseek-v4-flash ou deepseek-v4-pro para texto; use deepseek-v4-flash-vision-exp quando a entrada contiver imagem.
  3. Defina response_format.type como json_object.
  4. Inclua a palavra json na mensagem de sistema ou do usuário.
  5. Mostre um exemplo do objeto JSON esperado.
  6. Defina max_tokens de acordo com o tamanho esperado.
  7. Confirme finish_reason, trate conteúdo vazio, faça o parsing e valide o resultado.

Sem uma instrução explícita para produzir JSON, a referência da API alerta que o modelo pode gerar espaços em branco continuamente até atingir o limite de tokens, dando a impressão de que a chamada travou. Escrever apenas “responda de forma estruturada” não atende à orientação oficial: use literalmente json.

Modelos compatíveis e limites

Model IDJSON OutputEntradaContextoSaída máximaThinking padrão
deepseek-v4-flashSimTexto1 milhão384 milAtivado
deepseek-v4-proSimTexto1 milhão384 milAtivado
deepseek-v4-flash-vision-expSimTexto e imagem1 milhão384 milAtivado

Use Flash para extração textual em volume quando ele cumprir seus testes, Pro para tarefas mais ambíguas ou complexas e Vision Exp somente quando a extração depender de uma imagem. Os três aceitam Thinking e Non-Thinking; JSON Output continua exigindo parsing e validação local.

Em 29/07/2026, os aliases legados ainda responderam HTTP 200 nesta conta e retornaram V4 Flash, mas não apareceram em GET /models. Isso é compatibilidade residual observada, não garantia. Em projetos novos, use um dos três IDs explícitos atuais.

JSON a partir de uma imagem

O exemplo mantém response_format: {"type":"json_object"}, envia a imagem em uma mensagem user e usa o Vision Exp:

const response = await client.chat.completions.create({
  model: "deepseek-v4-flash-vision-exp",
  messages: [
    {
      role: "system",
      content: `Retorne somente json válido.
Exemplo: {"titulo":"Relatório","total":1250.50,"confianca":"baixa"}`,
    },
    {
      role: "user",
      content: [
        {
          type: "text",
          text: "Extraia o título e o total. Se não estiver legível, use null.",
        },
        {
          type: "image_url",
          image_url: {
            url: "https://example.com/imagem-autorizada.png",
            detail: "low",
          },
        },
      ],
    },
  ],
  response_format: { type: "json_object" },
  thinking: { type: "disabled" },
  max_tokens: 500,
});

As mesmas regras continuam valendo: inclua a palavra json, forneça exemplo, reserve saída suficiente, rejeite conteúdo vazio, verifique finish_reason, faça parsing e valide schema. JSON sintaticamente válido não prova que OCR, números ou interpretação visual estão corretos. Guarde evidência ou encaminhe para revisão humana quando o impacto for relevante.

Imagens são permitidas somente em mensagens user; system e assistant com imagem retornam erro 400. O Vision Exp aceita JPEG, PNG, GIF e WebP por URL, base64 ou file_id. A Files API aceita imagens para reutilização; não é upload genérico de PDF para extração.

Exemplo completo em Node.js

Instale o SDK com npm install openai. A chave deve ficar em variável de ambiente no backend; não a coloque no HTML, no JavaScript do navegador, em um aplicativo distribuído ou em um repositório.

import OpenAI from "openai"; const apiKey = process.env.DEEPSEEK_API_KEY; if (!apiKey) throw new Error("Defina DEEPSEEK_API_KEY no servidor."); const client = new OpenAI({ apiKey, baseURL: "https://api.deepseek.com", }); const systemPrompt = ` Extraia os dados do texto e retorne somente um objeto json. Não use Markdown e não acrescente explicações. Exemplo de json esperado: { "pedido_id": "PED-100", "cliente": "Ana", "itens": 2, "prioridade": "normal" } `; const response = await client.chat.completions.create({ model: "deepseek-v4-flash", messages: [ { role: "system", content: systemPrompt }, { role: "user", content: "Pedido PED-482, cliente Bruno, 3 itens, prioridade alta.", }, ], response_format: { type: "json_object" }, thinking: { type: "disabled" }, max_tokens: 500, }); const choice = response.choices[0]; if (!choice) throw new Error("A API não retornou uma choice."); if (choice.finish_reason === "length") { throw new Error("JSON truncado: aumente max_tokens ou reduza a entrada."); } if (choice.finish_reason !== "stop") { throw new Error(`Geração encerrada por: ${choice.finish_reason}`); } const raw = choice.message.content ?? ""; if (!raw.trim()) throw new Error("A API retornou conteúdo vazio."); let data; try { data = JSON.parse(raw); } catch (error) { throw new Error(`A resposta não pôde ser analisada como JSON: ${error.message}`); } function validarPedido(value) { if (!value || typeof value !== "object" || Array.isArray(value)) return false; return ( typeof value.pedido_id === "string" && typeof value.cliente === "string" && Number.isInteger(value.itens) && value.itens >= 0 && ["baixa", "normal", "alta"].includes(value.prioridade) ); } if (!validarPedido(data)) { throw new Error("JSON válido, mas incompatível com o schema do aplicativo."); } console.log(data);

Este fluxo separa três verificações diferentes: encerramento da geração, sintaxe JSON e regras do aplicativo. Um objeto como {"pedido_id":123} pode ser JSON válido e ainda ser inadequado porque o ID deveria ser string e outros campos estão ausentes.

Exemplo equivalente em Python

import json import os from openai import OpenAI api_key = os.environ.get("DEEPSEEK_API_KEY") if not api_key: raise RuntimeError("Defina DEEPSEEK_API_KEY no servidor.") client = OpenAI( api_key=api_key, base_url="https://api.deepseek.com", ) system_prompt = """ Extraia título, idioma e número de palavras. Retorne somente um objeto json, sem Markdown. Exemplo de json: {"titulo":"Guia","idioma":"pt-BR","palavras":1200} """ response = client.chat.completions.create( model="deepseek-v4-flash", messages=[ {"role": "system", "content": system_prompt}, {"role": "user", "content": "Título: API segura; idioma pt-BR; 850 palavras."}, ], response_format={"type": "json_object"}, max_tokens=300, extra_body={"thinking": {"type": "disabled"}}, ) choice = response.choices[0] if choice.finish_reason == "length": raise RuntimeError("JSON truncado: ajuste max_tokens ou a entrada.") if choice.finish_reason != "stop": raise RuntimeError(f"Geração encerrada por: {choice.finish_reason}") raw = choice.message.content or "" if not raw.strip(): raise RuntimeError("A API retornou conteúdo vazio.") try: data = json.loads(raw) except json.JSONDecodeError as error: raise RuntimeError(f"JSON inválido ou incompleto: {error}") from error required = {"titulo": str, "idioma": str, "palavras": int} for field, expected_type in required.items(): if field not in data or not isinstance(data[field], expected_type): raise RuntimeError(f"Campo inválido ou ausente: {field}") print(data)

Para schemas extensos, use uma biblioteca de validação mantida para seu ecossistema. Mesmo assim, mantenha validações de domínio — por exemplo, status permitidos, limites numéricos, IDs existentes e permissões do usuário.

Streaming de JSON sem quebrar o parser

Durante streaming, cada delta é apenas um fragmento: {, uma parte de uma string ou metade de um número não são documentos JSON completos. Acumule delta.content e faça JSON.parse somente depois do fim do stream.

const stream = await client.chat.completions.create({ model: "deepseek-v4-flash", messages: [ { role: "system", content: 'Retorne somente json. Exemplo: {"resumo":"...","tags":["..."]}', }, { role: "user", content: "Resuma: ..." }, ], response_format: { type: "json_object" }, thinking: { type: "disabled" }, max_tokens: 800, stream: true, }); let raw = ""; let finishReason = null; for await (const chunk of stream) { const choice = chunk.choices[0]; if (!choice) continue; raw += choice.delta?.content ?? ""; if (choice.finish_reason) finishReason = choice.finish_reason; } if (finishReason === "length") throw new Error("JSON truncado."); if (finishReason !== "stop") throw new Error(`Fim inesperado: ${finishReason}`); if (!raw.trim()) throw new Error("Conteúdo vazio."); const data = JSON.parse(raw); console.log(data);

Se o stream for interrompido pela rede, descarte o buffer parcial ou aplique uma estratégia de retomada idempotente. Não tente “consertar” silenciosamente JSON cortado e depois gravá-lo como se fosse uma resposta confiável.

JSON vazio, truncado ou não analisável

SintomaCausa provávelTratamento
String vaziaO JSON Output pode ocasionalmente retornar conteúdo vazioAjuste o prompt e faça poucas tentativas com backoff; nunca aceite como objeto válido
Muitos espaços ou chamada “travada”O prompt não instruiu explicitamente a saída em jsonInclua a palavra json e um exemplo
finish_reason: "length"Limite de saída ou contexto atingidoAumente max_tokens dentro dos limites ou reduza entrada/formato
JSON.parse falhaConteúdo vazio, truncamento, stream parcial ou transformação da respostaNão processe; registre o caso e gere novamente de forma controlada
JSON válido com valores erradosJSON mode não garante semântica ou regra de negócioValide schema, enums, intervalos, referências e permissões

A documentação reconhece especificamente a possibilidade de conteúdo vazio e recomenda modificar o prompt. Um retry deve ser limitado, usar backoff com jitter e ter idempotency control quando a chamada participa de um fluxo de gravação. Não presuma que uma resposta vazia ou falha não gera custo; reconcilie o uso retornado e sua conta.

JSON Output, JSON Schema e tool calls não são a mesma coisa

RecursoO que entregaO que não garante
JSON OutputResposta do assistant como JSON sintaticamente válido via json_objectConformidade com seu schema de negócio
Validação no backendRegras de campos, tipos, enums e domínio definidas pela aplicaçãoQue os fatos extraídos pelo modelo sejam verdadeiros
Tool CallsPedido para sua aplicação executar uma função, com argumentos em JSONExecução automática, permissão ou argumentos confiáveis
Tool Calls strict mode (Beta)Argumentos aderentes ao JSON Schema suportado da funçãoSaída geral do assistant em um schema arbitrário ou correção semântica

A documentação do JSON Output registra apenas response_format: {"type":"json_object"}; ela não documenta um tipo json_schema para a resposta geral. Se você encontrar exemplos de outros provedores com response_format.type: "json_schema", não os copie para a DeepSeek sem confirmação oficial.

Onde existe JSON Schema oficial: tool calls strict (Beta)

O uso documentado de JSON Schema estrito está separado em Tool Calls strict mode. Ele exige a base URL Beta https://api.deepseek.com/beta, strict: true em todas as funções e um schema aceito pelo servidor. Em objetos, todas as propriedades devem constar em required e additionalProperties deve ser false.

const betaClient = new OpenAI({ apiKey: process.env.DEEPSEEK_API_KEY, baseURL: "https://api.deepseek.com/beta", }); const tools = [{ type: "function", function: { name: "salvar_classificacao", description: "Salva uma classificação já validada pela aplicação.", strict: true, parameters: { type: "object", properties: { categoria: { type: "string", enum: ["suporte", "vendas", "financeiro"] }, urgente: { type: "boolean" }, }, required: ["categoria", "urgente"], additionalProperties: false, }, }, }];

Esse trecho apenas define a ferramenta; sua aplicação ainda precisa receber a tool call, validar autorização, executar a função e devolver o resultado. Como o modo é Beta e aceita um subconjunto de JSON Schema, confira a documentação antes de adotar cada keyword.

Prompts melhores para JSON Output

  • Escreva “retorne somente um objeto json”, não apenas “estruture a resposta”.
  • Inclua um exemplo pequeno com todas as chaves esperadas.
  • Defina como representar valores ausentes: null, string vazia ou omissão — e valide a escolha.
  • Liste enums permitidos e unidades, como centavos em vez de valor decimal ambíguo.
  • Peça uma chave de evidência quando a extração precisar ser auditável.
  • Delimite texto não confiável e instrua o modelo a tratá-lo como dados, não como comandos.
  • Evite schemas gigantes em uma única chamada; divida o trabalho se isso melhorar testes e recuperação.

O exemplo no prompt melhora a aderência, mas continua sendo orientação probabilística. Sua camada de validação é o limite de confiança.

Checklist de produção

  • Chave de API armazenada somente no servidor.
  • ID explícito: deepseek-v4-flash ou deepseek-v4-pro para texto; deepseek-v4-flash-vision-exp quando houver imagem.
  • response_format.type: "json_object".
  • A palavra json e um exemplo no prompt.
  • max_tokens dimensionado e finish_reason verificado.
  • Conteúdo vazio rejeitado.
  • Parsing com tratamento de exceção.
  • Schema e regras de negócio validados.
  • Dados factuais verificados quando a precisão importa.
  • Retries limitados, backoff e operações idempotentes.
  • Logs sem chaves, credenciais ou dados pessoais desnecessários.

Para diagnosticar respostas interrompidas, autenticação e falhas de capacidade, use DeepSeek error codes e DeepSeek não funciona: troubleshooting. Para integração completa, consulte OpenAI SDK com DeepSeek.

FAQ sobre DeepSeek JSON Output

Qual response_format devo usar?

Use {"type":"json_object"}. Também instrua o modelo a produzir json na mensagem de sistema ou do usuário.

JSON Output garante meu schema?

Não. Ele garante JSON sintaticamente válido em uma geração normal concluída, mas não a presença, o tipo ou o significado dos campos. Valide o objeto no backend.

Por que a resposta veio vazia?

A documentação oficial diz que JSON Output pode ocasionalmente retornar conteúdo vazio. Rejeite a resposta, ajuste o prompt e tente novamente com um limite controlado.

Posso analisar cada chunk do streaming?

Não como documento completo. Acumule os fragmentos e faça o parsing depois de receber o término com finish_reason: "stop".

Preciso ativar Thinking Mode para gerar JSON?

Não. JSON Output é um recurso separado. Para extração direta, Non-Thinking pode ser mais eficiente; para tarefas complexas, teste Thinking e compare qualidade, latência e tokens.

Tool call strict é o mesmo que JSON Output?

Não. Strict mode é um recurso Beta para argumentos de funções e exige a URL Beta e schemas compatíveis. JSON Output controla a mensagem JSON do assistant via response_format.

Vision Exp aceita JSON Output?

Sim. A tabela oficial marca JSON Output como suportado no deepseek-v4-flash-vision-exp. O recurso garante JSON válido quando a geração normal é concluída, mas não garante a correção da leitura visual, dos campos ou dos valores. Valide o objeto e trate conteúdo vazio ou truncado.

Fontes oficiais

DeepSeek Português é um site independente, criado por terceiros, sem afiliação, endosso ou representação oficial da DeepSeek. Confirme modelos, parâmetros e limites na documentação oficial antes de decisões de produção.