Depois que a DeepSeek abriu as ferramentas do app em 13 de novembro, como o JSON do deepseek-flash declara deepseek_web_search, deepseek_read_url e safety_check, e cobra tool_search à parte dos tokens?

O id do modelo não liga a busca. tools, thinking e safety_check decidem o JSON. A contagem cobrada é tool_search.

Definir model como deepseek-flash não liga a busca. Em 13 de novembro de 2026 a DeepSeek abriu na API as ferramentas por trás do app de chat. O id deepseek-flash é DeepSeek-V4.1-Flash-1017. Os ids antigos deepseek-v4-flash e deepseek-v4-flash-vision-exp ainda chegam aqui e são cobrados pelo preço Flash. O contexto tem 1.000.000 de tokens. A saída máxima tem 384.000. Pensar é o padrão.

Esta página está datada de 16 de novembro de 2026, a partir do registro de 13 de novembro, do guia de ferramentas web, do guia de Search e Fetch, do guia de segurança e da página de preços. Há três dias cobrimos o usage do Gemini 4 Carbon. Aqui os campos que mudam o pedido e a conta são tools, thinking, safety_check e usage.server_tool_use.

O que abriu em 13 de novembro

O mesmo modelo aceita as ferramentas em três pontos. Messages é POST https://api.deepseek.com/anthropic/v1/messages com x-api-key. Responses é POST https://api.deepseek.com/responses. Chat Completions é POST https://api.deepseek.com/chat/completions. Os dois últimos enviam Authorization: Bearer. Search, Fetch, OCR, ASR e TTS também existem como chamadas avulsas. A busca de imagens não está em POST /v1/tools/search. Ela só roda dentro de deepseek_web_search.

CapacidadeJSON que ligaO que volta
Busca na webdeepseek_web_search, pensar desligadoO modelo busca quando decide e cita
Busca com raciocíniodeepseek_web_search, pensar ligadosearch, open_page, find_in_page, cerca de 20 chamadas
Leitura de URLdeepseek_read_urlLinks da última mensagem do usuário, no máximo as 10 primeiras URL distintas
Segurançasafety_check.level = highRevisa entrada e saída. A DeepSeek exige isso num serviço público
Arquivosfile_id da API FilesPDF, Office e imagens são analisados antes do turno

JSON do pedido em três pontos

Messages nomeia cada ferramenta duas vezes, type e name. Responses e Chat enviam só type. tool_choice não pode nomear essas ferramentas. Isso devolve 400, deepseek_web_search cannot be forced. tool_choice none desliga toda ferramenta web declarada, inclusive a leitura de URL. Em Responses e Chat, required é tratado como auto.

Não envie allowed_domains, blocked_domains nem user_location. Não declare a mesma ferramenta duas vezes. Não misture outra ferramenta de servidor. O erro diz que outras ferramentas ainda não podem ser usadas com deepseek_web_search, deepseek_read_url, safety_check ou title. Em Responses, uma ferramenta web_search e um text.format diferente de text devolvem 400. Em Chat, web_search_options e um response_format diferente de text devolvem 400. JSON estruturado e essas ferramentas web não compartilham um pedido. Deixe o seu esquema para uma chamada seguinte. Veja o que é saída estruturada.

Pensar desligado é a busca com citações. Pensar ligado é a busca profunda. Se os dois estão ativos, a rodada não executa deepseek_read_url. Links são lidos quando pensar está desligado, ou quando só deepseek_read_url está declarado. Messages e Chat põem thinking.type em disabled ou enabled. O exemplo de Responses para a busca profunda põe reasoning.effort em high.

{
  "model": "deepseek-flash",
  "thinking": {
    "type": "disabled"
  },
  "safety_check": {
    "level": "high"
  },
  "tools": [
    {
      "type": "deepseek_web_search",
      "name": "deepseek_web_search"
    },
    {
      "type": "deepseek_read_url",
      "name": "deepseek_read_url"
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "What changed in the DeepSeek API on 13 November 2026?"
    }
  ]
}

Responses, com busca e raciocínio:

{
  "model": "deepseek-flash",
  "reasoning": {
    "effort": "high"
  },
  "safety_check": {
    "level": "high"
  },
  "tools": [
    {
      "type": "deepseek_web_search"
    },
    {
      "type": "deepseek_read_url"
    }
  ],
  "input": "Which official page states the height of Tokyo Tower?"
}

Blocos, kind e citações

Em Messages, cada chamada é um bloco server_tool_use mais um resultado. Combine-os por tool_use_id. Num fluxo, os dois blocos chegam inteiros em content_block_start. Leia o usage final em message_delta. O usage de message_start cobre só o primeiro passo de inferência.

input.actionnamekindResultado
searchdeepseek_web_searchdeep_search ao pensar, senão searchweb_search_tool_result
open_pagedeepseek_web_searchdeep_searchweb_fetch_tool_result. data é uma string vazia. Não há signature
find_in_pagedeepseek_web_searchdeep_searchA mesma forma. title é null. Não é cobrado
read_linkdeepseek_read_urlread_linkweb_fetch_tool_result mais signature

A busca de imagens põe kind em image_search ou deep_image_search. queries é um array vazio. Um resultado pode acrescentar image_url só para exibição. As citações de Messages ficam em blocos text como web_search_result_location. cited_text é o texto da resposta daquele bloco, não uma citação da página. encrypted_index é sempre uma string vazia. Uma URL no máximo por bloco. No fluxo elas chegam como citations_delta.

Responses põe a chamada num web_search_call com kind e action. A resposta é output_text com anotações url_citation. start_index e end_index contam pontos de código Unicode. Chat põe as chamadas em message.server_tool_calls. Cada passo tem reasoning_content e calls. message.content não tem marcas de citação. As citações ficam em message.annotations. message.reasoning_content é só o último passo.

Uma resposta que usou essas ferramentas não pode continuar. A API devolve 400 e pede para reenviar o pedido anterior. No turno seguinte, devolva o conteúdo do assistente sem alteração, inclusive kind e signature. Trechos de busca e o raciocínio anterior não voltam ao contexto. Só o texto da resposta. Uma página lida volta a partir de signature. Em read_link, data é sempre vazio. Sem a assinatura o pedido ainda sucede, mas a página some. Os códigos de falha são url_not_accessible, url_not_allowed e unavailable. url_not_allowed também cobre uma página que não passou na revisão de segurança.

Um item de busca do Responses:

{
  "type": "web_search_call",
  "id": "srvtoolu_s_00_3f2a9c",
  "status": "completed",
  "kind": "search",
  "action": {
    "type": "search",
    "queries": [
      "DeepSeek API 13 November 2026"
    ],
    "sources": [
      {
        "type": "url",
        "url": "https://example.com/news",
        "title": "Change log",
        "snippet": "Web search and URL reading are now API tools.",
        "published_at": "2026-11-13T00:00:00+00:00"
      }
    ]
  }
}

JSON avulso de Search e Fetch

Quando é o seu código, e não o modelo, que decide buscar, chame as APIs JSON cruas. Search é POST https://api.deepseek.com/v1/tools/search. query é obrigatório, de 1 a 128 caracteres, não só espaços. count vai de 1 a 50 e o padrão é 10. ori_question é opcional, também de 1 a 128 caracteres. localization é um IP opcional. need_content tem padrão false. Campos desconhecidos são ignorados. Operadores que passam intactos: site:, -site:, -, -"...", "...", lang:, after: e before:.

{
  "query": "DeepSeek site:api-docs.deepseek.com after:2026-11-01",
  "count": 10,
  "need_content": false
}

Fetch é POST https://api.deepseek.com/v1/tools/fetch. O único campo é url, no máximo 8.192 caracteres, HTTP ou HTTPS, com host e sem usuário nem senha. O corpo é title e content em Markdown. Sem título, é uma string vazia.

{
  "url": "https://api-docs.deepseek.com/updates"
}
CampoO que guardar
rerank_scoreDe 0 a 3. 1,5 ou mais é a faixa de alta qualidade do guia
authorityDe 0 a 4. −1 significa desconhecido. 3 ou mais é altamente autoritativo
snippet / summaryCurto para a interface, longo para o modelo
contentVazio se need_content não for true, ou se a página não tiver conteúdo
dateRFC 3339 em UTC, ou null

file_id, OCR e JSON de voz

A entrada de arquivo tem dois passos. POST https://api.deepseek.com/files, com purpose antes de file. text_recognition descarta gráficos. rich_layout_recognition recorta figuras no texto e gasta tokens de imagem. O objeto do arquivo só volta depois da análise. id tem a forma file-api-.... Uma desconexão não cancela uma análise que depois dá certo: o arquivo é guardado e cobrado. Não dá para baixar o original nem a análise. Chat Completions referencia assim:

{
  "role": "user",
  "content": [
    {
      "type": "file",
      "file_id": "file-api-xxxxxxxxxxxxxxxx"
    },
    {
      "type": "text",
      "text": "Summarize the revenue chart."
    }
  ]
}

Messages precisa do cabeçalho anthropic-beta: files-api-2025-04-14 e de um bloco document cujo source.type é file. Responses usa input_file e file_id. Um documento analisado não pode ir como bloco de imagem. Também não se cola os bytes nem uma URL de arquivo no pedido de chat. Um pedido cita no máximo 20 documentos e 8 MiB de texto. A análise completa fica no contexto nos turnos seguintes. Longo demais devolve 400. Nada é cortado em silêncio.

Limites: PDF, Word, PowerPoint e imagens comuns; o formato é lido nos bytes. 100 MiB, senão 413. 1.000 páginas. 120 segundos para enviar, senão 408. 120 segundos para analisar, senão 504. 15 envios de documento em andamento por conta. Arquivo com senha devolve 400. Texto puro, csv, json, código, xlsx, xls, epub e mobi usam purpose user_data e não são cobrados por página. Esses arquivos vão até 32 MiB, e o texto até 8 MiB. AZW3 e livros com DRM não são aceitos.

A análise custa US$ 0,225 por 1.000 páginas, uma vez, só se der certo. Turnos de chat seguintes cobram tokens de entrada, não as páginas de novo. OCR tem o mesmo preço por página em POST /v1/tools/ocr e não entra na API Files. É multipart, file mais purpose, não um corpo JSON. ASR é áudio multipart, não JSON. TTS é JSON, POST /v1/tools/tts:

O preço de tabela do TTS é US$ 0,45 por 10.000 caracteres, e o preço limitado publicado é US$ 0,225. Um caractere chinês conta como 2. Qualquer outro caractere conta como 1. As vozes são stella (padrão) e tide. Não há campo de idioma. O preço de tabela do ASR é US$ 0,116 por hora de áudio, preço limitado US$ 0,058, cobrado por segundo, e uma fração sobe para 1 segundo. A página de preços não dá data de fim para o meio preço.

{
  "text": "Hello from DeepSeek.",
  "voice_id": "stella",
  "format": "wav",
  "filter_markdown": true
}

safety_check e JSON de recusa

Para um serviço que o público alcança, ponha safety_check em {"level":"high"}. low equivale a omitir o campo. Qualquer outro nível é 400. O parâmetro não substitui os seus deveres de revisão, registro ou rotulagem. Uma entrada que não passa devolve 400 Content Exists Risk. Esses tokens de entrada ainda são cobrados, pelo preço de acerto de cache. Depois que o modelo termina, a conexão fica aberta enquanto a saída é revisada. Texto já transmitido não volta atrás. Troque o que você mostrou. Tokens usados antes da recusa são cobrados. Tokens de revisão estão dentro dos tokens de saída e também em usage.output_tokens_details.safety_tokens em Messages e Responses, ou em usage.completion_tokens_details.safety_tokens em Chat. Uma imagem bloqueada pode nomear um caminho como messages.1.content.0, em stop_details.explanation, um conteúdo de recusa ou message.refusal. Um pedido com as ferramentas web e sem safety_check ainda pode terminar em recusa.

APIJSON da recusa
Messagesstop_reason refusal, stop_details.type refusal. Sem fluxo, o raciocínio e o texto da resposta saem; ficam os blocos de ferramenta e um bloco text vazio
Responsesstatus incomplete, incomplete_details.reason content_filter. output só guarda os web_search_call já executados
Chatfinish_reason content_filter. content é uma string vazia. annotations é omitido. server_tool_calls fica, e o raciocínio de cada passo é esvaziado

Cobrar tool_search, não web_search_requests

Cobre tokens e ferramentas em linhas separadas. Os preços Flash são por 1.000.000 de tokens. O horário de pico é 01:00–04:00 e 06:00–10:00 UTC, de segunda a sexta, fora feriados chineses. Qualquer outra hora é fora de pico, inclusive fins de semana e feriados chineses o dia inteiro. Fora de pico é metade do pico. cache_creation_input_tokens permanece 0.

JanelaAcerto de cache / 1MFalha de cache / 1MSaída / 1M
Fora de pico$0.003$0.15$0.60
Pico$0.006$0.30$1.20

Busca e fetch na web custam US$ 0,75 por 1.000 usos bem-sucedidos, quer o modelo tenha chamado a ferramenta, quer você tenha chamado /v1/tools/search ou /v1/tools/fetch. Uma busca de ferramenta com resultados é cobrada por consulta, então três consultas contam como três. count não muda o preço da API Search. HTTP 200 com um array results vazio não é cobrado. Fetch só é cobrado quando o conteúdo da página volta. Uma página que a segurança depois troca por url_not_allowed ou unavailable já foi obtida, então é cobrada. Abrir de novo a mesma página na busca profunda é grátis. find_in_page é grátis.

Search fica em 100 pedidos por segundo por conta. Fetch em 25, mais um teto por domínio. Os tetos são por conta, não por chave, e ficam separados do limite de concorrência Flash de 2.500. No guia, uma busca citada com duas consultas informa web_search_requests 1 e tool_search 2. Guarde tool_search, tool_fetch e tool_image_search. Não some web_search_requests. Em Responses e Chat, server_tool_use omite esse trio quando os três são 0.

Se a geração falha depois que o status HTTP já é 200, o corpo é um erro mais usage. O fluxo de Messages termina num evento error, sem message_delta depois. Confira o corpo. Um SDK não lança exceção no status 200. O exemplo publicado dessa busca de duas consultas. thinking_tokens e safety_tokens não estão neste objeto. Eles aparecem à parte quando pensar está ligado, ou quando safety_check é high, e já estão dentro de output_tokens:

{
  "input_tokens": 1905,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 0,
  "output_tokens": 72,
  "service_tier": "standard",
  "server_tool_use": {
    "web_search_requests": 1,
    "web_fetch_requests": 0,
    "tool_search": 2,
    "tool_fetch": 0,
    "tool_image_search": 0
  }
}

JSON para conferir antes de publicar

  1. O corpo tem deepseek-flash. As ferramentas de Messages têm type e name. Pensar está disabled se você queria a busca com citações.
  2. Um app público envia safety_check.level high. response_format e text.format ficam em text nestas chamadas.
  3. O analisador combina tool_use_id e kind, e guarda signature para o turno seguinte.
  4. A conta usa tool_search, tool_fetch e tool_image_search, mais a entrada sem cache, a entrada com cache e a saída. Não soma web_search_requests.
  5. Uma query avulsa tem de 1 a 128 caracteres. count vai de 1 a 50. Resultados vazios não são uma cobrança.

Confira o JSON localmente com o validador JSON, JSONPath ($.usage.server_tool_use.tool_search) e JSON Diff contra o pedido anterior. Nada é enviado.

FAQ

thinking muda a busca?

Muda. thinking.type disabled é uma busca na web com citações, e kind é search. enabled é a busca com raciocínio profundo: search, open_page e find_in_page, cerca de 20 chamadas, e kind é deep_search. Pensar é o padrão. Se pensar e deepseek_web_search estão ligados, essa rodada não executa deepseek_read_url.

tool_choice pode forçar deepseek_web_search?

Não. Nomear a ferramenta devolve 400, deepseek_web_search cannot be forced. O modelo decide. tool_choice none desliga as ferramentas web declaradas, inclusive a leitura de URL. Em Responses e Chat, required é tratado como auto.

A conta deve usar web_search_requests?

Não. Essa contagem inclui erros e serve para exibir. Cobre tool_search, tool_fetch e tool_image_search. No guia, um bloco de busca com duas consultas informa web_search_requests 1 e tool_search 2. Uma busca com resultados é cobrada por consulta. Busca vazia ou com falha não é cobrada.

POST /v1/tools/search busca imagens?

Não. A busca de imagens só roda dentro de deepseek_web_search. kind é image_search ou deep_image_search, e queries fica vazio. Cada imagem conta como uma busca, e cada região que o modelo escolhe conta como mais uma.

O que um serviço público envia para a segurança?

A DeepSeek diz que um serviço aberto ao público liga safety_check com level high. low equivale a omitir o campo. Uma entrada de risco devolve 400 Content Exists Risk, e esses tokens de entrada ainda são cobrados pelo preço de acerto de cache. Uma recusa é stop_reason refusal, Responses incomplete com content_filter, ou Chat finish_reason content_filter.

Posso continuar uma resposta que buscou?

Não. Uma resposta que usou deepseek_web_search ou deepseek_read_url devolve 400. Reenvie o pedido anterior. No turno seguinte, devolva os blocos do assistente sem alteração, inclusive kind e signature. Sem uma assinatura válida o pedido ainda sucede, mas a página não volta ao contexto.

Resumo

As ferramentas de 13 de novembro de 2026 mudam o pedido, os blocos que você guarda e uma segunda linha da conta. Declare deepseek_web_search e deepseek_read_url em deepseek-flash. Desligue pensar para a busca com citações e ligue para a busca profunda. Apps públicos põem safety_check.level em high. Cobre tool_search, não web_search_requests.