Guia de configuração da busca na web e do upload de arquivos na API da DeepSeek

Em 13 de novembro de 2026, a DeepSeek colocou os recursos do app atrás de parâmetros de API. A busca integrada é controlada pelo modelo e cobrada por consulta com resultados; o Search/Fetch independente é controlado pelo código e cobrado por requisição bem-sucedida; já o upload de arquivos passa por uma Files API separada e usa file_id.

Uma chamada com o modo de raciocínio ativado pode disparar cerca de 20 chamadas de ferramentas, cobradas como consultas e buscas de páginas. Este guia mostra como ativar os recursos, fazer upload de arquivos, calcular os custos por tarefa e escolher a abordagem mais adequada.

O que foi liberado na DeepSeek App API em 13 de novembro

O anúncio da DeepSeek, The full DeepSeek App experience, now via API, disponibiliza busca na web, entrada de arquivos e leitura de URLs pela API para o modelo deepseek-flash (DeepSeek-V4.1-Flash).

O mesmo conjunto de recursos pode ser acessado por três interfaces: Messages API, Responses API e Chat Completions API, de acordo com o Build a Chatbot guide. As chamadas de ferramentas e a montagem do contexto acontecem no servidor; o cliente apenas renderiza os blocos estruturados e os devolve sem alterações. Um demo de navegador open source mostra essa integração, mas é identificado como uma demonstração, não como código pronto para produção.

Ativando a busca na web e a leitura de URLs

Declare duas ferramentas no array tools da requisição, usando deepseek-flash, conforme a documentação do Web Tools guide:

"tools": [{"type": "deepseek_web_search"}, {"type": "deepseek_read_url"}]

Com o raciocínio desativado, deepseek_web_search funciona como a busca do chat: o modelo decide se precisa pesquisar, uma chamada pode conter várias consultas e a resposta chega com citações. Com o raciocínio ativado, a mesma ferramenta vira uma busca de raciocínio profundo, alternando open_page e find_in_page com as etapas de análise, em até cerca de 20 chamadas de ferramentas antes da resposta.

O Web Tools guide define quatro limitações importantes:

• Contam apenas as URLs presentes na mensagem mais recente do usuário, limitadas às 10 primeiras URLs distintas; o modelo decide quais serão lidas.
• Não é possível forçar uma ferramenta com tool_choice: indicar uma ferramenta retorna HTTP 400, e "none" também desativa a leitura de URLs.
• Quando as ferramentas web, o nível alto de segurança ou a geração de títulos estão ativados, temperature, top_p e vários campos de controle das ferramentas são ignorados silenciosamente.
• Uma resposta que usou ferramentas web não pode ser continuada; é preciso reenviar a requisição.

"A US$ 0,75 por 1.000 requisições, quero saber quantas chamadas um agente faz em segundo plano. Alguém calculou o custo de uma tarefa de pesquisa típica?" — u/Glum-Guitar-5083 no r/DeepSeek

A cobrança muda conforme o caminho escolhido. A busca web integrada cobra cada consulta que retorna resultados — três consultas em uma chamada contam como três —, enquanto o fetch integrado cobra cada página acessada, inclusive páginas que depois são substituídas por url_not_allowed ou unavailable durante a análise de segurança. Links que não podem ser acessados não são cobrados. No Search/Fetch independente, a cobrança ocorre apenas com HTTP 200 e resultados não vazios ou conteúdo retornado. Buscas com falha ou sem resultados não são cobradas em nenhum dos dois caminhos.

Faça upload de arquivos sem criar seu próprio parser

A Files API permite fazer o upload uma vez e referenciar o arquivo depois usando file_id. O fluxo mínimo é este:

curl https://api.deepseek.com/files \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -F purpose="rich_layout_recognition" \
  -F file="@report.pdf"
# -> {"id": "file-api-xxxxxxxxxxxxxxxx", ...}

# then reference it in chat (Chat Completions shape):
# {"model": "deepseek-flash", "messages": [{"role": "user",
#   "content": [{"type": "text", "text": "Compare this with today's numbers"},
#   {"type": "file", "file_id": "file-api-xxxxxxxxxxxxxxxx"}]}]}

O campo purpose define o processamento e, para documentos, precisa ser enviado antes do campo file. user_data aceita imagens (JPEG, PNG, GIF, WebP), texto simples, planilhas e ebooks; text_recognition converte PDFs, arquivos do Word e do PowerPoint, além de imagens, apenas em texto; rich_layout_recognition retorna texto e figuras, preservando tabelas e colunas. Enviar um PDF como user_data retorna HTTP 400, e documentos processados não podem ser reutilizados como imagens nem baixados depois.

Os arquivos pertencem à conta, não à chave, e o mesmo ID funciona nas famílias compatíveis com OpenAI e Anthropic. No segundo caso, é necessário enviar o cabeçalho anthropic-beta: files-api-2025-04-14. O processamento acontece durante o upload, portanto o file_id só é retornado depois que a operação termina com sucesso.

Ferramentas integradas ou Search e Fetch independentes?

Use as ferramentas integradas quando o modelo deve decidir se pesquisa ou lê algo dentro de uma conversa. Prefira as APIs independentes da documentação Search & Fetch guide quando essa decisão ficar por conta do seu código: POST https://api.deepseek.com/v1/tools/search faz a descoberta ordenada, com até 50 resultados, rerank_score de 0 a 3 — sendo 1,5 ou mais considerado de alta qualidade — e authority de 0 a 4; POST https://api.deepseek.com/v1/tools/fetch busca uma URL e a converte em Markdown. O Search independente ainda não oferece busca de imagens, enquanto as ferramentas web oferecem.

Os limites de requisição são definidos por conta e funcionam de forma independente: 100 QPS para Search, 25 QPS para Fetch, além de um limite de Fetch por domínio. Acima da cota, a API retorna HTTP 429. Tente novamente em casos de 408, 429 e 5xx; para os demais erros 4xx, corrija a requisição. O Search independente aceita operadores como site:, -site:, "exact phrase", lang: e after:/before:.

Quanto isso custa na prática

As tarifas das ferramentas são somadas ao custo dos tokens: Search e Fetch custam US$ 0,75 por 1.000 requisições bem-sucedidas de cada tipo. OCR, ASR e TTS têm preços próprios, além de promoções por tempo limitado detalhadas no anúncio. Alterar count muda o volume de resultados, mas não o preço.

Comparações de preços feitas pela comunidade colocam a busca da DeepSeek perto de US$ 0,75 por 1.000 requisições, contra cerca de US$ 10 por 1.000 nas buscas da OpenAI e da Claude, segundo relatos de desenvolvedores (@berryxia). Só nas tarifas das ferramentas, a diferença chega a aproximadamente 13 vezes.

Uma resposta com uma única consulta custa menos de um décimo de centavo em tarifas de ferramentas. Já uma execução com raciocínio profundo, usando 8 consultas e 6 aberturas de páginas, cobra cerca de 8 buscas mais 6 fetches — ainda menos de dois centavos antes dos tokens. O risco está no volume: um agente que entra em um loop com dezenas de buscas multiplica rapidamente as unidades de US$ 0,75. Faça o orçamento com base nas chamadas bem-sucedidas, limite a profundidade da busca avançada e registre tool_search e tool_fetch no objeto de uso final. O campo web_search_requests desse objeto serve apenas para exibição e não representa a quantidade cobrada.

Checklist de publicação: citações, segurança e demo

As citações chegam em blocos web_search_result_location com URL, título e trecho citado, conforme o Web Tools guide. Em streams, elas aparecem como eventos citations_delta, com no máximo uma URL por bloco de texto, e são ignoradas se forem reenviadas em requisições posteriores. Preserve os campos signature e os blocos de ferramentas exatamente como recebidos entre os turnos: as páginas lidas são restauradas a partir da assinatura. Mesmo com uma assinatura inválida ou ausente, a requisição é concluída, mas a página é descartada. No rastreamento de exemplo do chatbot, o contexto cresce de 40 tokens de entrada para 9.078 depois das ferramentas, com 4.096 tokens atendidos pelo cache. Planeje, portanto, o contexto considerando o histórico inflado pelas buscas.

Em apps públicos, a DeepSeek exige a verificação de segurança e deixa a moderação, o registro do modelo e a identificação de conteúdo gerado por IA a cargo do desenvolvedor. Use a análise integrada como uma primeira camada, trate explicitamente os motivos de parada refusal e esteja preparado para receber url_not_allowed quando uma página falhar na revisão. Esses fetches bloqueados continuam sendo cobrados. O demo do chat mostra a integração, mas mantém tudo no navegador; antes de ir para produção, implemente seu próprio backend.

Perguntas frequentes

Posso obrigar o modelo a pesquisar em toda requisição?

Não. O modelo decide quando as ferramentas serão acionadas, e indicar uma ferramenta web em tool_choice retorna 400.

Quais modelo e endpoints oferecem busca na web e upload de arquivos?

deepseek-flash nas interfaces Messages, Responses e Chat Completions. As referências de arquivos por file_id funcionam tanto nas famílias compatíveis com OpenAI quanto nas compatíveis com Anthropic.

É possível combinar arquivos enviados com busca na web?

Sim. Esse é o padrão documentado para chatbots: contexto de arquivo combinado com busca no servidor e citações.

Quantas buscas uma tarefa típica de agente dispara?

Uma chamada com algumas consultas para respostas simples; em pesquisas com o raciocínio ativado, até cerca de 20 chamadas de ferramentas. Meça tool_search e tool_fetch por tarefa: as ferramentas integradas cobram por consulta ou página, enquanto as independentes cobram por requisição bem-sucedida — ambas a US$ 0,75 por 1.000.

Comece com uma requisição de busca integrada e um upload de arquivo no demo. Leia os contadores tool_search e tool_fetch do objeto de uso final e só então decida se o gasto com ferramentas por tarefa é mais vantajoso do que manter sua própria camada com Tavily ou SearXNG.