DeepSeek API: busca na web, leitura de URLs, preços e erros 400
Configure a busca na web e a leitura de URLs pelo servidor com deepseek-flash usando Chat Completions, Messages ou Responses. Aprenda a escolher o modo thinking, preservar signature entre turnos, calcular os custos de busca e leitura de páginas junto com os tokens e corrigir erros 400. Entenda também quando usar as APIs independentes Search, Fetch, OCR, ASR e TTS.
Conteúdo

Se o seu chatbot precisa consultar a web e citar fontes, use deepseek-flash com deepseek_web_search e desative thinking. Ative thinking para pesquisas em várias etapas ou declare deepseek_read_url para ler os links enviados pelo usuário. Comece pela API oficial do DeepSeek, porque gateways compatíveis podem não preservar todos os campos e resultados específicos dessas ferramentas de servidor.
O DeepSeek lançou esses recursos em 13 de novembro de 2026. Buscas, leitura de URLs, processamento de arquivos e serviços de voz têm cobranças adicionais ao custo normal dos tokens do modelo.
Este guia explica como enviar requisições nas três APIs compatíveis, verificar as respostas, calcular os custos e corrigir erros comuns. Também mostra quando vale usar as APIs independentes.
O que mudou na API do DeepSeek em 13 de novembro?
O DeepSeek disponibilizou aos desenvolvedores vários recursos que antes estavam associados principalmente ao seu aplicativo de chat.
Segundo as notas oficiais de lançamento de 13 de novembro, o DeepSeek V4.1 Flash, acessado pelo identificador deepseek-flash, agora oferece:
- Busca na web e de imagens com citações das fontes.
- Busca profunda, que pesquisa, abre páginas e procura trechos durante várias etapas de raciocínio.
- Leitura de URLs presentes na mensagem do usuário.
- Entrada de arquivos PDF, documentos do Office e imagens, com extração de texto ou análise detalhada do layout.
- Verificação de segurança das entradas e saídas do modelo.
Esses recursos funcionam nas APIs Messages, Responses e Chat Completions. O DeepSeek executa as chamadas às ferramentas no próprio servidor e adiciona os resultados ao contexto do modelo.
Ao usar as ferramentas integradas, seu aplicativo não precisa executar as buscas ou baixar as páginas por conta própria.
O DeepSeek também oferece as APIs independentes Search, Fetch, OCR, ASR e TTS. Elas retornam diretamente ao seu código resultados de busca, texto extraído, transcrições ou áudio.
Como escolher o modo de busca
A configuração thinking determina como deepseek_web_search se comporta.
| Modo | Ferramenta declarada | Thinking | Comportamento |
|---|---|---|---|
| Busca normal na web | deepseek_web_search | Desativado | O modelo busca quando necessário e responde com citações |
| Busca profunda | deepseek_web_search | Ativado | Pesquisa, abre páginas e localiza textos em várias etapas |
| Leitura de URLs | deepseek_read_url | Desativado ou ativado sem busca na web | Analisa os links da última mensagem do usuário |
| Busca e leitura de URLs | As duas ferramentas | Desativado | O modelo escolhe entre buscar ou ler os URLs fornecidos |
Na busca profunda, o modelo pode fazer aproximadamente até 20 chamadas de ferramentas antes de responder. Esse é um limite aproximado documentado, não uma quantidade garantida de chamadas.
Existe uma interação importante entre as duas ferramentas. Quando thinking está ativado e deepseek_web_search foi declarado, a rodada usa a busca profunda. Nesse caso, o comportamento separado de leitura do deepseek_read_url não é executado.
Se o aplicativo precisa examinar URLs específicos fornecidos pelo usuário, declare somente deepseek_read_url.
Declarar uma ferramenta não obriga o modelo a usá-la. O próprio modelo decide quando buscar ou recuperar uma página.
Para entender melhor o modelo e os custos em tarefas de programação, consulte o guia do DeepSeek V4.1 Flash para código e preços.
Como ativar deepseek_web_search no Chat Completions?
Envie uma requisição POST https://api.deepseek.com/chat/completions, selecione deepseek-flash e inclua a ferramenta no array tools.
Você precisa de uma chave de API ativa do DeepSeek, do shell Bash, do cURL e do jq.
O exemplo Bash abaixo ativa a busca normal e a verificação de segurança do conteúdo. O primeiro comando recebe a chave sem exibi-la. Quando ele aguardar a entrada, cole a chave criada na plataforma DeepSeek.
read -rs DEEPSEEK_API_KEY && export DEEPSEEK_API_KEY
curl -sS https://api.deepseek.com/chat/completions \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-flash",
"thinking": {"type": "disabled"},
"tools": [
{"type": "deepseek_web_search"}
],
"safety_check": {"level": "high"},
"messages": [
{
"role": "user",
"content": "What did DeepSeek announce on November 13, 2026? Cite the official sources."
}
]
}' | jq '{
error: .error,
answer: .choices[0].message.content,
citations: .choices[0].message.annotations,
tool_calls: .choices[0].message.server_tool_calls,
finish_reason: .choices[0].finish_reason,
usage: .usage
}'
Uma resposta bem-sucedida com busca pode conter:
choices[0].message.content: texto da resposta.choices[0].message.annotations: URLs das fontes e posições das citações.choices[0].message.server_tool_calls: etapas de busca executadas pelo servidor.usage.server_tool_use: contadores de uso de buscas e recuperação de páginas.
Uma resposta completa apresenta choices[0].finish_reason = "stop". O valor length indica que a resposta foi interrompida pelo limite de saída. content_filter indica recusa pela verificação de conteúdo.
Se server_tool_calls não aparecer, isso não significa necessariamente que a requisição falhou. O modelo pode ter decidido não buscar. Faça uma pergunta que exija informações recentes e confira o resultado novamente.
Ativar a busca profunda
Mantenha a declaração da busca e altere a configuração de thinking:
{
"thinking": {"type": "enabled"},
"tools": [
{"type": "deepseek_web_search"}
]
}
Use esse modo quando a pergunta exigir várias consultas ou comparação de informações entre diferentes fontes.
A busca profunda pode abrir páginas e pesquisar textos dentro delas. Por isso, pode consumir mais tokens de inferência e gerar mais recuperações de páginas cobradas do que a busca normal.
O modelo determina quais etapas serão realmente executadas.
Ler URLs sem fazer buscas
Substitua a declaração por deepseek_read_url e inclua o link na última mensagem do usuário:
{
"thinking": {"type": "disabled"},
"tools": [
{"type": "deepseek_read_url"}
],
"messages": [
{
"role": "user",
"content": "Summarize https://api-docs.deepseek.com/updates/ and identify the November 13 changes."
}
]
}
Use o mesmo endpoint do Chat Completions, modelo, autenticação e configuração de segurança do primeiro exemplo.
A leitura de URLs segue estas regras:
- Somente a última mensagem do usuário é examinada para encontrar URLs.
- URLs repetidos contam uma única vez.
- No máximo os primeiros 10 URLs diferentes são considerados.
- O modelo decide quais URLs elegíveis serão lidos.
- Quando várias páginas extensas são lidas, parte do conteúdo pode ser truncada.
Essas regras estão no guia oficial de Web Tools.
Se o link aparece apenas em uma mensagem anterior, não espere que a próxima requisição faça outra leitura automaticamente.
Como declarar as mesmas ferramentas em Messages e Responses?
As três APIs aceitam as novas ferramentas, mas usam formatos de requisição e estruturas de resposta diferentes.
| API | Endpoint | Declaração documentada | Controle de thinking |
|---|---|---|---|
| Chat Completions | /chat/completions | {"type":"deepseek_web_search"} | thinking.type |
| Messages | /anthropic/v1/messages | {"type":"deepseek_web_search","name":"deepseek_web_search"} | thinking.type |
| Responses | /responses | {"type":"deepseek_web_search"} | reasoning.effort |
Os três usam https://api.deepseek.com como host.
Nos exemplos oficiais de Messages, a declaração contém os campos type e name. Esses exemplos não demonstram que name seja obrigatório em toda requisição válida.
Messages usa o cabeçalho x-api-key. Chat Completions e Responses usam Authorization: Bearer.
Antes de migrar entre formatos, consulte o guia de compatibilidade de Messages, Chat Completions e Responses. O mesmo identificador de modelo não garante que as estruturas de ferramentas e histórico sejam iguais.
Exemplo da Messages API
Esta requisição Bash lê uma URL usando o formato Messages compatível com Anthropic.
curl -sS https://api.deepseek.com/anthropic/v1/messages \
-H "x-api-key: ${DEEPSEEK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-flash",
"thinking": {"type": "disabled"},
"tools": [
{
"type": "deepseek_read_url",
"name": "deepseek_read_url"
}
],
"safety_check": {"level": "high"},
"messages": [
{
"role": "user",
"content": "Summarize https://api-docs.deepseek.com/updates/"
}
]
}' | jq '{
content: .content,
stop_reason: .stop_reason,
usage: .usage
}'
A resposta aparece em blocos content. As chamadas de ferramentas usam blocos server_tool_use, seguidos pelos blocos de resultados.
As citações ficam associadas aos blocos de texto. Uma resposta concluída apresenta stop_reason = "end_turn".
Ao usar streaming, leia o consumo total no último evento message_delta. O usage de message_start cobre apenas a primeira etapa de inferência.
Exemplo da Responses API
Na Responses API, o controle de raciocínio é reasoning.effort, não thinking.type.
Defina none para desativar thinking. Os valores low, high e max ativam o recurso com o nível de esforço solicitado.
curl -sS https://api.deepseek.com/responses \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-flash",
"reasoning": {"effort": "high"},
"tools": [
{"type": "deepseek_web_search"}
],
"safety_check": {"level": "high"},
"input": "Research the November 13, 2026 DeepSeek API update and compare the official documentation."
}' | jq '{
status: .status,
output: .output,
usage: .usage
}'
A Responses API retorna a atividade das ferramentas como itens web_search_call em output. A resposta final aparece como um item message, com as fontes nas anotações de output_text.
Uma resposta completa apresenta status = "completed". Se o limite de saída for atingido ou houver uma recusa de conteúdo, o status pode ser incomplete. Uma falha de geração pode retornar failed.
Verifique incomplete_details.reason ou error.code antes de decidir se vale tentar novamente.
Não use a mesma estrutura para interpretar respostas dos três protocolos. A diferença é especialmente importante ao preservar o histórico de ferramentas.
Por que preservar signature entre os turnos da conversa?
Quando deepseek_read_url lê uma página com sucesso, o DeepSeek devolve uma representação criptografada do conteúdo em signature.
O texto completo da página não aparece como texto comum no bloco de resultado. Os campos url, title, data e published_at servem principalmente para exibição.
Nos próximos turnos, o DeepSeek utiliza a assinatura para restaurar o conteúdo da página no contexto da conversa.
Envie as respostas anteriores do assistente sem alterações, incluindo kind, signature e toda a estrutura de chamadas ao servidor.
O exemplo em Python abaixo usa Chat Completions e preserva a mensagem completa do assistente entre dois turnos.
Instale requests e exporte DEEPSEEK_API_KEY antes de executar o código.
import os
import requests
endpoint = "https://api.deepseek.com/chat/completions"
headers = {
"Authorization": f"Bearer {os.environ['DEEPSEEK_API_KEY']}",
"Content-Type": "application/json",
}
tools = [{"type": "deepseek_read_url"}]
messages = [
{
"role": "user",
"content": (
"Read https://api-docs.deepseek.com/updates/ "
"and summarize the November 13, 2026 entry."
),
}
]
def complete_turn(history):
response = requests.post(
endpoint,
headers=headers,
json={
"model": "deepseek-flash",
"thinking": {"type": "disabled"},
"tools": tools,
"safety_check": {"level": "high"},
"messages": history,
},
timeout=180,
)
response.raise_for_status()
data = response.json()
if data.get("error"):
raise RuntimeError(data["error"])
choice = data["choices"][0]
if choice["finish_reason"] != "stop":
raise RuntimeError(
f"Incomplete response: {choice['finish_reason']}"
)
return choice["message"]
first_reply = complete_turn(messages)
# Preserve the complete assistant object, including server_tool_calls.
messages.append(first_reply)
messages.append(
{
"role": "user",
"content": "Which developer features does that entry list?",
}
)
second_reply = complete_turn(messages)
print(second_reply["content"])
O código demonstra o formato de conversa documentado. Ele não representa um teste executado com uma chave de API real.
Examine first_reply["server_tool_calls"] para confirmar se o modelo leu o URL. Se não houver uma chamada read_link, a primeira resposta não terá uma assinatura de página lida para preservar.
Nos outros protocolos, mantenha as estruturas correspondentes:
| API | O que devolver na próxima requisição |
|---|---|
| Messages | Blocos content anteriores do assistente, com kind e signature |
| Responses | Itens anteriores de output, com web_search_call, kind e signature |
| Chat Completions | Mensagem completa do assistente, incluindo server_tool_calls |
Se uma biblioteca ou gateway remover signature, a próxima requisição ainda poderá funcionar. Porém, a página lida anteriormente não será restaurada no contexto.
Resultados de buscas, páginas abertas na busca profunda e etapas anteriores de raciocínio não são preservados automaticamente com todo o conteúdo. Nos turnos seguintes, normalmente permanece apenas o texto da resposta anterior. A assinatura válida da leitura de URL é a exceção documentada.
Por isso, não reduza o histórico do assistente a role e content quando precisar manter o conteúdo das páginas.
Quando usar Search, Fetch, OCR, ASR e TTS separadamente?
Escolha as APIs independentes quando seu aplicativo precisar controlar diretamente a obtenção ou o processamento dos dados.
Diferentemente das ferramentas integradas, elas devolvem o resultado ao seu código. Assim, você pode validar, filtrar, armazenar e decidir quais informações serão enviadas ao modelo.
Endpoints e entradas das APIs independentes
| API | Endpoint em https://api.deepseek.com | Entrada obrigatória | Resultado |
|---|---|---|---|
| Search | POST /v1/tools/search | JSON com query | results estruturados |
| Fetch | POST /v1/tools/fetch | JSON com url | title e content da página em Markdown |
| OCR | POST /v1/tools/ocr | Campos multipart file, purpose | pages[].text e page_count |
| ASR | POST /v1/tools/asr | Arquivo de áudio multipart file | Transcrição text e duration_ms |
| TTS | POST /v1/tools/tts | JSON com text | Áudio WAV ou PCM |
As cinco APIs usam autenticação Bearer.
Os comandos Bash abaixo mostram como chamar cada interface com a variável DEEPSEEK_API_KEY exportada anteriormente.
# Search for pages and return structured results.
curl -sS https://api.deepseek.com/v1/tools/search \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"query":"DeepSeek API release","count":5,"need_content":true}' \
| jq '.results[] | {title, url, summary, content}'
# Fetch one page as Markdown.
curl -sS https://api.deepseek.com/v1/tools/fetch \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"url":"https://api-docs.deepseek.com/updates/"}' \
| jq '{title, content}'
# Extract text from a local PDF.
curl -sS https://api.deepseek.com/v1/tools/ocr \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-F purpose="text_recognition" \
-F file="@document.pdf" \
| jq '{page_count, pages}'
# Transcribe a local audio file.
curl -sS https://api.deepseek.com/v1/tools/asr \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-F file="@speech.wav" \
| jq '{text, duration_ms}'
# Generate a WAV file.
curl -sS https://api.deepseek.com/v1/tools/tts \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"text":"Hello from DeepSeek.","voice_id":"stella"}' \
--output speech.wav
Os exemplos de OCR e ASR exigem arquivos locais. O comando de TTS cria speech.wav no diretório atual.
Principais limites documentados em 14 de novembro de 2026:
- Search:
queryaceita 1–128 caracteres Unicode.countpermite pedir de 1 a 50 resultados. Limite por conta: 100 QPS. - Fetch: um URL HTTP ou HTTPS por requisição, sujeito às políticas de acesso do site. Limite por conta: 25 QPS, além de um limite QPS por domínio.
- OCR: arquivo de até 100 MiB e 1,000 páginas. Até 15 reconhecimentos simultâneos por conta.
- ASR: até 120 segundos de áudio e 8 MiB por requisição. Suporta 16-bit PCM WAV e Ogg Opus.
- TTS: até 10,000 caracteres faturáveis por requisição. Oferece síntese completa e streaming por WebSocket.
A API Search independente aceita operadores como site:, lang: e after:. Em 14 de novembro de 2026, a interface documentada não oferece busca de imagens. Essa função está disponível pelas ferramentas web integradas.
Consulte os requisitos completos nas documentações de Search e Fetch, OCR, ASR e TTS.
Qual é a diferença entre entrada de arquivos e OCR?
Use a entrada de arquivos quando quiser que o modelo responda a perguntas sobre um documento. Prefira o OCR independente quando seu aplicativo precisar receber o texto extraído.
Para consultar um documento com o modelo:
- Envie o arquivo para
POST https://api.deepseek.com/filesusandomultipart/form-data. - Envie o campo
purposeantes defile. Inverter a ordem pode gerar400. - Escolha
text_recognitionourich_layout_recognitionno campopurpose. - Receba o
file_idapós o processamento bem-sucedido e use-o em uma requisição adeepseek-flash.
O exemplo Bash faz o upload de um PDF local:
curl -sS https://api.deepseek.com/files \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-F purpose="text_recognition" \
-F file="@report.pdf" \
| jq '{id, filename, purpose}'
As opções -F criam um formulário multipart. Preserve a ordem purpose, depois file. Não configure manualmente o delimitador do Content-Type: o cURL o gera.
A resposta do upload contém id, que você deve usar como file_id na conversa. O arquivo é processado durante o upload, sem necessidade de consultar outro endpoint para acompanhar o status.
text_recognition extrai somente texto e descarta gráficos, fotografias e diagramas para a interpretação do modelo. rich_layout_recognition também fornece as figuras detectadas nas posições correspondentes do documento.
No Chat Completions, a referência ao arquivo em uma mensagem do usuário tem este formato:
{
"role": "user",
"content": [
{"type": "file", "file_id": "file-api-xxxxxxxxxxxxxxxx"},
{"type": "text", "text": "Summarize the key points of this document."}
]
}
Substitua o identificador ilustrativo pelo file_id real retornado no upload.
Cada requisição pode referenciar no máximo 20 documentos. O texto extraído de todos eles não pode ultrapassar 8 MiB.
O processamento é cobrado uma única vez quando o upload termina com sucesso. Nas requisições seguintes, o conteúdo do documento gera cobrança de tokens de entrada do modelo.
Leia o guia de processamento de arquivos antes de implementar o fluxo.
Quanto custam as ferramentas web e as outras APIs do DeepSeek?
Em 14 de novembro de 2026, o DeepSeek cobra separadamente a inferência do modelo e a utilização das ferramentas.
A página oficial de preços apresenta estas tarifas em dólares americanos:
| Recurso | Unidade de cobrança | Preço |
|---|---|---|
| Busca de texto na web | 1,000 buscas faturáveis | $0.75 |
| Busca de imagens | 1,000 buscas faturáveis | $0.75 |
| Fetch ou leitura de URL | 1,000 recuperações faturáveis | $0.75 |
| Processamento de arquivos ou OCR | 1,000 páginas processadas com sucesso | $0.225 |
| ASR | 1 hora de áudio | $0.058 promocional; $0.116 preço de tabela |
| TTS | 10,000 caracteres faturáveis | $0.225 promocional; $0.45 preço de tabela |
Os descontos de ASR e TTS são anunciados como temporários. As páginas de preços e os guias consultados não informam a data de encerramento.
No TTS, cada caractere chinês conta como dois caracteres faturáveis. Os demais caracteres, incluindo espaços, contam como um.
A duração do áudio no ASR é medida em segundos. Frações de segundo são arredondadas para cima.
Quais campos de usage representam cobranças?
Nas ferramentas web integradas, use estes contadores:
usage.server_tool_use.tool_search: buscas de texto faturáveis.usage.server_tool_use.tool_image_search: buscas de imagens faturáveis.usage.server_tool_use.tool_fetch: recuperações de páginas faturáveis.
Não calcule os custos com web_search_requests ou web_fetch_requests.
Esses campos contam blocos de resultados, inclusive blocos com erros. Servem para exibição, não para representar unidades faturáveis.
Uma chamada de busca pode executar várias consultas. Se fizer três consultas bem-sucedidas, tool_search pode aumentar em três.
Buscas que falham ou não retornam resultados não são cobradas.
Na busca de imagens, cada imagem conta como uma busca. Cada região selecionada pelo modelo dentro de uma imagem conta como outra busca. Buscas sem resultados ou que falham não são cobradas.
A leitura de URL é faturada quando uma página é recuperada com sucesso. Se a verificação de segurança substituir o resultado por um erro depois da recuperação, ainda poderá haver cobrança.
Na busca profunda, reabrir uma página já disponível no contexto não gera uma nova recuperação faturável. Procurar texto dentro dela também é gratuito.
As APIs Search e Fetch independentes seguem outra regra: cada requisição bem-sucedida é cobrada uma vez. A quantidade de resultados de Search não multiplica o preço da requisição.
Exemplo de custo para 100 requisições
Considere 100 requisições ao DeepSeek Flash com thinking desativado e o seguinte consumo:
| Uso | Quantidade considerada |
|---|---|
| Consultas de texto faturáveis | 200 |
| Páginas recuperadas e faturáveis | 100 |
| Tokens de entrada sem cache | 200,000 |
| Tokens de entrada lidos do cache | 0 |
| Tokens de saída, incluindo revisão de segurança | 50,000 |
| Buscas de imagens | 0 |
Fora do horário de pico, o deepseek-flash custa $0.15 por milhão de tokens de entrada sem cache e $0.60 por milhão de tokens de saída.
O cálculo, com essas premissas, é:
Text searches = 200 / 1,000 × $0.75 = $0.150
Page fetches = 100 / 1,000 × $0.75 = $0.075
Input tokens = 200,000 / 1,000,000 × $0.15 = $0.030
Output tokens = 50,000 / 1,000,000 × $0.60 = $0.030
Estimated total = $0.285 for 100 requests
O custo estimado é de $0.285 para 100 requisições. Trata-se de uma simulação com premissas explícitas, não de uso medido nem de uma cobrança real.
Pelo calendário publicado pelo DeepSeek, os horários de pico são 01:00–04:00 e 06:00–10:00 UTC, de segunda a sexta-feira, exceto feriados oficiais chineses.
Nesses horários, as tarifas do Flash são $0.30 por milhão de tokens de entrada sem cache e $1.20 por milhão de tokens de saída.
Para o mesmo volume de uso, o custo estimado no horário de pico seria $0.345.
O valor real depende das etapas de inferência, tokens thinking, leituras de cache, buscas de imagens, recuperações de páginas, revisão de segurança e tarifas vigentes.
Os tokens thinking já fazem parte de output_tokens. Não some o custo deles novamente.
Requisições com erro também podem ser cobradas?
Sim, dependendo de quando ocorreu a falha.
Se a geração falhar depois de começar, o DeepSeek pode retornar HTTP 200 mesmo quando existe um erro no corpo da resposta.
As etapas de inferência, buscas e recuperações executadas antes da falha continuam sendo cobradas normalmente.
Em streaming, verifique o evento final e os dados definitivos de usage. Não considere apenas o status HTTP inicial.
No Chat Completions sem streaming, procure o campo error mesmo quando o HTTP retornar 200.
Na Responses API, confira status, incluindo os valores failed e incomplete.
Como corrigir os erros 400 das ferramentas web?
Muitos erros de validação aparecem ao tratar ferramentas de servidor como funções comuns ou ao misturar opções não suportadas.
A referência oficial de erros do Web Tools documenta estas mensagens:
| Erro reconhecível | Causa | Correção |
|---|---|---|
tool_choice: deepseek_web_search cannot be forced | tool_choice força uma ferramenta web | Remova a seleção forçada e deixe o modelo decidir |
tools: deepseek_web_search can only be declared once | Declaração duplicada | Mantenha apenas uma declaração |
tools: allowed_domains is not supported by deepseek_web_search | Opções de domínio ou localização não suportadas | Remova allowed_domains, blocked_domains e user_location |
tools: other tools cannot be used together with deepseek_web_search, deepseek_read_url, safety_check or title yet | Outra ferramenta de servidor incompatível foi declarada | Remova a ferramenta de servidor que causa o conflito |
safety_check: level must be low or high | Nível de segurança inválido | Use low ou high |
messages: the last assistant message used deepseek_web_search or deepseek_read_url and cannot be continued; resend the previous request | Tentativa de continuar uma resposta parcial que usou ferramentas web | Reenvie a requisição original |
As mensagens originais colocam os nomes dos campos entre crases. A tabela omite esses delimitadores para facilitar a leitura.
Você não precisa aplicar todas as correções. Localize sua mensagem de erro, ajuste o campo correspondente e envie a requisição novamente.
É possível forçar uma busca com tool_choice?
Não. tool_choice não pode indicar deepseek_web_search ou deepseek_read_url como ferramenta obrigatória.
Quando tool_choice recebe none, todas as ferramentas ficam desativadas, incluindo a leitura de URL.
No Chat Completions e no Responses, tool_choice: "required" é tratado como auto quando essas ferramentas web são utilizadas. Isso também não garante uma busca.
Se o aplicativo precisa executar uma consulta específica em todas as situações, chame a API Search independente.
As ferramentas web funcionam com function calls comuns?
O erro documentado se refere a declarações incompatíveis de ferramentas de servidor.
Isso não demonstra que todas as funções definidas pelo desenvolvedor estejam proibidas. Por outro lado, a compatibilidade com qualquer framework de agentes também não foi verificada.
Na Responses API, essas ferramentas não podem ser combinadas com web_search. Alguns tipos, incluindo custom, namespace e tool_search, também não são suportados.
Antes de usá-las no Claude Code, OpenCode ou em um agente com funções próprias, teste a requisição completa e a troca de chamadas e resultados.
Uma requisição OpenAI-compatible funcionar sem ferramentas web não comprova que essa combinação é compatível.
Por que continuar uma resposta que usou ferramentas web gera 400?
Adicionar um novo turno à conversa e continuar uma geração interrompida são operações diferentes.
Em um novo turno, você envia a resposta concluída do assistente e a próxima mensagem do usuário.
Na continuação, você tenta completar a mesma resposta parcial do assistente.
O DeepSeek não permite continuar uma resposta que tenha usado deepseek_web_search ou deepseek_read_url.
Se uma resposta com busca for interrompida, reenvie a solicitação anterior com um limite de saída adequado. Lembre-se de que novas buscas e recuperações poderão ser executadas e cobradas.
Em outras continuações permitidas no Chat Completions, a documentação utiliza prefix: true na última mensagem assistant e o endpoint beta. Esse mecanismo não elimina a restrição para respostas com ferramentas web.
O que significam url_not_accessible, url_not_allowed e unavailable?
Quando a recuperação de uma página falha, o DeepSeek devolve um resultado web_fetch_tool_result_error sem signature.
O campo error_code identifica o tipo de problema.
| Código | Significado | Próxima ação |
|---|---|---|
url_not_accessible | Não foi possível ler o link | Verifique URL, disponibilidade, autenticação e restrições do site |
url_not_allowed | A leitura não é permitida ou a revisão de segurança rejeitou a página | Não tente contornar a restrição; solicite outra fonte permitida |
unavailable | O serviço está indisponível, a página não abriu na busca profunda ou a chamada não terminou | Confira o status e considere uma quantidade limitada de tentativas |
Esses códigos não são equivalentes.
url_not_allowed não significa necessariamente um erro de rede. O código também pode indicar rejeição pela revisão de conteúdo.
unavailable também não significa que a operação foi gratuita. A página pode ter sido recuperada antes da falha.
Em streaming, relacione chamadas e resultados pelos identificadores correspondentes. Quando várias páginas são lidas, os resultados nem sempre chegam imediatamente após suas chamadas.
Verifique também o motivo do encerramento:
end_turnno Messages indica que a resposta terminou.max_tokenssignifica que o limite de saída ou o contexto disponível acabou.refusalindica rejeição pela revisão de conteúdo.
No Chat Completions, os valores correspondentes incluem stop, length e content_filter.
Para um aplicativo disponível ao público, ative a verificação de segurança:
{
"safety_check": {"level": "high"}
}
O DeepSeek exige essa verificação em serviços voltados ao público. O parâmetro realiza uma revisão básica de entradas e saídas, mas não substitui a moderação do aplicativo nem as obrigações aplicáveis de registro e identificação de conteúdo gerado por IA.
Uma resposta rejeitada ainda pode gerar cobrança pelos tokens consumidos antes da rejeição.
Consulte o guia de Model Content Safety para entender como cada protocolo informa as recusas.
Vale usar as ferramentas integradas ou uma API de busca própria?
Use as ferramentas integradas quando quiser que o modelo conduza a pesquisa durante a conversa. Prefira as APIs independentes quando precisar controlar cada etapa e receber diretamente o conteúdo recuperado.
| Necessidade do aplicativo | Comece com | Motivo |
|---|---|---|
| Chatbot que responde com fontes | deepseek_web_search, thinking desativado | Menos lógica própria de busca |
| Pesquisa com várias fontes | deepseek_web_search, thinking ativado | O modelo pode pesquisar e analisar páginas em várias etapas |
| Resumo de links fornecidos pelo usuário | deepseek_read_url | Lê URLs elegíveis e preserva o contexto por assinatura |
| Busca em um site específico | Search independente | O código controla operadores e resultados |
| Obter Markdown de um URL conhecido | Fetch independente | O conteúdo chega diretamente ao aplicativo |
| Extrair texto de muitos documentos | OCR independente | Retorna o texto por página |
| Perguntar sobre documentos enviados | File Parsing e deepseek-flash | O conteúdo entra no contexto do modelo |
| Entrada de voz e leitura em áudio | ASR e TTS | Interfaces específicas de processamento de áudio |
Para um agente de programação já existente, manter uma integração externa de busca pode ser a melhor opção. Isso evita alterar o conjunto atual de ferramentas e o controle de recuperação do agente.
O guia para adicionar Parallel Search MCP a um agente apresenta uma alternativa. Compare custos reais, compatibilidade e qualidade do conteúdo recuperado em tarefas equivalentes antes de decidir.
Essas ferramentas funcionam pelo BetterToken e por outros gateways?
Em 14 de novembro de 2026, deepseek-flash aparecia no catálogo de modelos do BetterToken. Consulte os preços atuais dos modelos antes de escolher a rota de acesso.
No entanto, a presença de um modelo no catálogo não comprova o suporte às novas ferramentas de servidor do DeepSeek.
Ainda não foi verificado se o BetterToken encaminha as declarações das ferramentas, preserva signature, retorna usage.server_tool_use ou registra as cobranças adicionais dos recursos.
Por isso, todos os exemplos deste guia utilizam o endpoint oficial do DeepSeek.
Antes de usar um gateway compatível, teste uma requisição de busca, outra de leitura de URL e um segundo turno que preserve signature. Depois, compare os contadores usage com os valores efetivamente cobrados.
Para um novo aplicativo, comece com busca normal e thinking desativado. Verifique as citações e o consumo faturável. Ative a busca profunda quando forem necessárias várias etapas de pesquisa. Use Search e Fetch independentes para as operações que precisam ficar sob controle do seu código.