DeepSeek API: búsqueda web, lectura de URL, precios y errores 400

Configura la búsqueda web y la lectura de URL del lado del servidor con deepseek-flash mediante Chat Completions, Messages o Responses. Aprende a elegir el modo thinking, conservar signature entre turnos, calcular los cargos por búsquedas y páginas junto con los tokens, resolver errores 400 y decidir cuándo utilizar las API independientes de Search, Fetch, OCR, ASR y TTS.

Índice
DeepSeek API: búsqueda web, lectura de URL, precios y errores 400

Si tu chatbot necesita consultar Internet y citar fuentes, utiliza deepseek-flash con deepseek_web_search y desactiva thinking. Activa thinking para investigar en varios pasos, o declara deepseek_read_url para leer los enlaces que proporcione el usuario. Empieza con la API oficial de DeepSeek porque las pasarelas compatibles pueden no conservar los campos y resultados especiales de sus herramientas de servidor.

DeepSeek lanzó estas funciones el 13 de noviembre de 2026. La búsqueda, la lectura de URL, el procesamiento de archivos y las funciones de voz tienen cargos propios, adicionales al consumo de tokens del modelo.

Esta guía explica las solicitudes para las tres API compatibles, cómo comprobar los resultados, calcular el consumo y resolver errores frecuentes. También muestra cuándo conviene llamar directamente a las API independientes.

¿Qué cambió en la API de DeepSeek el 13 de noviembre?

DeepSeek abrió a los desarrolladores varias funciones que antes estaban asociadas principalmente a su aplicación de chat.

Según las notas oficiales del 13 de noviembre, DeepSeek V4.1 Flash, identificado en la API como deepseek-flash, incorpora:

  • Búsqueda web y de imágenes con referencias a las fuentes.
  • Búsqueda profunda, que consulta distintas fuentes, abre páginas y busca texto mientras razona.
  • Lectura de URL incluidas en el mensaje del usuario.
  • Entrada de archivos PDF, documentos de Office e imágenes, con extracción de texto o análisis del diseño.
  • Controles de seguridad sobre las entradas y salidas del modelo.

Estas capacidades funcionan con Messages, Responses y Chat Completions. DeepSeek ejecuta las llamadas a las herramientas en sus servidores y añade los resultados al contexto del modelo.

Cuando utilizas las herramientas integradas, tu aplicación no tiene que ejecutar por separado las búsquedas ni descargar las páginas.

Además, DeepSeek ofrece las API independientes Search, Fetch, OCR, ASR y TTS. Estas devuelven directamente a tu aplicación resultados de búsqueda, texto extraído, transcripciones o audio.

Cómo elegir el modo de búsqueda

La configuración thinking determina el comportamiento de deepseek_web_search.

ModoHerramienta declaradaThinkingComportamiento
Búsqueda web normaldeepseek_web_searchDesactivadoEl modelo busca cuando lo necesita y responde con citas
Búsqueda profundadeepseek_web_searchActivadoBusca, abre páginas y localiza texto en distintos pasos de razonamiento
Lectura de URLdeepseek_read_urlDesactivado, o activado sin búsqueda webExamina los enlaces del último mensaje del usuario
Búsqueda y lectura de URLAmbas herramientasDesactivadoEl modelo decide entre buscar o leer los enlaces proporcionados

En la búsqueda profunda, el modelo puede realizar aproximadamente hasta 20 llamadas a herramientas antes de responder. Se trata de un límite aproximado documentado, no de un número garantizado de llamadas.

Existe una interacción importante entre ambas herramientas. Cuando thinking está activado y declaras deepseek_web_search, se ejecuta la búsqueda profunda. En esa misma ronda no se realiza por separado el comportamiento de lectura de deepseek_read_url.

Si tu aplicación debe examinar enlaces concretos enviados por el usuario, declara solamente deepseek_read_url.

Declarar una herramienta no obliga al modelo a utilizarla. El modelo decide cuándo buscar o recuperar una página.

Si necesitas conocer mejor las características del modelo, consulta la guía de DeepSeek V4.1 Flash para programación y precios.

¿Cómo activar deepseek_web_search en Chat Completions?

Envía una solicitud POST https://api.deepseek.com/chat/completions, selecciona deepseek-flash e incluye la declaración de la herramienta en tools.

Necesitas una clave API activa de DeepSeek, el intérprete Bash, cURL y jq.

El siguiente ejemplo en Bash activa la búsqueda normal y la revisión de seguridad del contenido. La primera orden recoge la clave sin mostrarla. Cuando solicite la entrada, pega la clave que hayas creado en la 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
  }'

Una respuesta correcta con búsqueda puede incluir:

  • choices[0].message.content: texto de la respuesta.
  • choices[0].message.annotations: URL de las fuentes y posiciones de las citas.
  • choices[0].message.server_tool_calls: pasos de búsqueda ejecutados en el servidor.
  • usage.server_tool_use: contadores de uso de búsqueda y recuperación de páginas.

La finalización correcta se identifica mediante choices[0].finish_reason = "stop". El valor length indica que la respuesta se cortó por el límite de salida. content_filter indica un rechazo de la revisión de contenido.

Si no aparece server_tool_calls, no significa necesariamente que la solicitud haya fallado. Quizá el modelo consideró innecesario buscar. Prueba una pregunta que requiera información reciente y vuelve a inspeccionar el resultado.

Activar la búsqueda profunda

Conserva la declaración de búsqueda y modifica la configuración de thinking:

{
  "thinking": {"type": "enabled"},
  "tools": [
    {"type": "deepseek_web_search"}
  ]
}

Elige este modo cuando necesites consultar varias fuentes o contrastar información en diferentes pasos.

La búsqueda profunda puede abrir páginas y buscar texto dentro de ellas. Por eso puede consumir más tokens de inferencia y generar más recuperaciones de páginas facturables que una búsqueda normal.

El modelo decide cuántos pasos necesita realmente.

Leer URL sin realizar búsquedas

Sustituye la declaración por deepseek_read_url e incluye el enlace en el último mensaje del usuario:

{
  "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."
    }
  ]
}

Usa el mismo endpoint de Chat Completions, modelo, autenticación y configuración de seguridad que en el primer ejemplo.

La lectura de URL tiene estas condiciones:

  • Solamente se buscan URL en el último mensaje del usuario.
  • Cada URL repetida cuenta una sola vez.
  • Se consideran como máximo las primeras 10 URL distintas.
  • El modelo decide cuáles de esas URL leer.
  • Si se leen varias páginas largas, su contenido puede truncarse.

Las reglas aparecen en la documentación oficial de Web Tools.

Si un enlace solo figura en un turno anterior, no esperes que una nueva solicitud vuelva a leerlo automáticamente.

¿Cómo se declaran las herramientas en Messages y Responses?

Las tres API admiten las nuevas herramientas, pero utilizan distintos formatos de solicitud y estructuras de respuesta.

APIEndpointDeclaración documentadaControl 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

Los tres utilizan https://api.deepseek.com como host.

Los ejemplos oficiales de Messages incluyen type y name en la declaración de la herramienta. Esos ejemplos no demuestran que name sea obligatorio en cualquier solicitud válida.

Messages utiliza el encabezado x-api-key. Chat Completions y Responses utilizan Authorization: Bearer.

Si estás migrando entre formatos, revisa las diferencias de compatibilidad entre Messages, Chat Completions y Responses. Un modelo con el mismo identificador puede requerir estructuras diferentes para las herramientas y el historial.

Ejemplo de Messages API

Esta solicitud Bash lee una URL mediante el formato Messages compatible con 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
  }'

La respuesta aparece en bloques content. Las llamadas a herramientas usan bloques server_tool_use seguidos de bloques de resultados.

Las citas se adjuntan a los bloques de texto. Una respuesta terminada indica stop_reason = "end_turn".

En las respuestas en streaming, lee el consumo completo del último evento message_delta. El usage de message_start solo corresponde al primer paso de inferencia.

Ejemplo de Responses API

En Responses debes usar reasoning.effort en lugar de thinking.type.

Establece none para desactivar thinking. Los valores low, high y max lo activan con el nivel de esfuerzo 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
  }'

La actividad de las herramientas se devuelve como elementos web_search_call dentro de output. La respuesta final aparece como un elemento message, con citas en las anotaciones de output_text.

Una respuesta completa tiene status = "completed". Si se alcanza el límite de salida o interviene la revisión de contenido, puede aparecer incomplete. Un fallo de generación puede producir failed.

Comprueba incomplete_details.reason o error.code antes de decidir si debes reintentar.

No analices las respuestas de los tres protocolos utilizando una única estructura. Las diferencias son especialmente importantes al conservar el historial.

¿Por qué hay que conservar signature entre turnos?

Cuando deepseek_read_url lee correctamente una página, DeepSeek devuelve una representación cifrada de su contenido en signature.

El texto completo de la página no se expone como texto normal en el resultado. Los campos url, title, data y published_at sirven principalmente para mostrar información.

En turnos posteriores, DeepSeek usa la firma para recuperar el contenido de la página e incorporarlo al contexto.

Devuelve las respuestas anteriores del asistente sin modificarlas. Conserva kind, signature y la estructura completa de llamadas al servidor.

El siguiente ejemplo de Python utiliza Chat Completions y mantiene el mensaje completo del asistente entre turnos.

Instala requests y exporta DEEPSEEK_API_KEY antes de ejecutar el 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"])

Este código ilustra el formato de conversación documentado. No representa una prueba ejecutada con una clave API real.

Inspecciona first_reply["server_tool_calls"] para confirmar que el modelo leyó el enlace. Si no aparece ninguna llamada read_link, no habrá una firma de página leída que conservar.

Los demás protocolos requieren mantener sus estructuras correspondientes:

APIQué debes enviar en el siguiente turno
MessagesBloques content anteriores del asistente, incluidos kind y signature
ResponsesElementos anteriores de output, incluidos web_search_call, kind y signature
Chat CompletionsMensaje completo del asistente con server_tool_calls

Si una biblioteca o pasarela elimina signature, la siguiente solicitud puede seguir funcionando. Sin embargo, la página leída anteriormente dejará de restaurarse en el contexto.

Los resultados de búsqueda, las páginas abiertas mediante búsqueda profunda y los pasos de razonamiento anteriores no se conservan automáticamente con todo su contenido. En los turnos posteriores normalmente se incorpora el texto de la respuesta previa. La firma de la lectura de URL constituye la excepción documentada.

Por eso no reduzcas el historial del asistente a role y content cuando necesites recuperar el contenido de los enlaces.

¿Cuándo conviene utilizar Search, Fetch, OCR, ASR y TTS por separado?

Las API independientes son más adecuadas cuando tu aplicación debe controlar directamente cómo obtiene o procesa la información.

A diferencia de las herramientas integradas, devuelven resultados a tu propio código. Puedes validarlos, filtrarlos, guardarlos y decidir qué contenido enviar al modelo.

Endpoints y entradas de las API independientes

APIEndpoint en https://api.deepseek.comEntrada requeridaResultado
SearchPOST /v1/tools/searchJSON con queryresults estructurados
FetchPOST /v1/tools/fetchJSON con urltitle y content de la página en Markdown
OCRPOST /v1/tools/ocrCampos multipart file, purposepages[].text y page_count
ASRPOST /v1/tools/asrArchivo de audio multipart fileTranscripción text y duration_ms
TTSPOST /v1/tools/ttsJSON con textAudio WAV o PCM

Las cinco API usan autenticación Bearer.

Los siguientes ejemplos Bash muestran cómo llamar a cada interfaz con la variable 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

Los ejemplos de OCR y ASR requieren archivos locales. La orden de TTS crea speech.wav en el directorio de trabajo.

Límites principales documentados al 14 de noviembre de 2026:

  • Search: query admite entre 1 y 128 caracteres Unicode. count permite solicitar entre 1 y 50 resultados. Límite por cuenta: 100 QPS.
  • Fetch: una URL HTTP o HTTPS por solicitud, sujeta a las políticas de acceso del sitio. Límite por cuenta: 25 QPS, además de un límite QPS por dominio.
  • OCR: archivos de hasta 100 MiB y 1,000 páginas. Cada cuenta puede mantener hasta 15 reconocimientos simultáneos.
  • ASR: máximo 120 segundos de audio y 8 MiB por solicitud. Admite 16-bit PCM WAV y Ogg Opus.
  • TTS: máximo 10,000 caracteres facturables por solicitud. Ofrece síntesis completa y transmisión mediante WebSocket.

La API Search admite operadores como site:, lang: y after:. Al 14 de noviembre de 2026, su interfaz documentada no admite búsqueda de imágenes. Esa función está disponible mediante las herramientas web integradas.

Consulta los requisitos completos en la documentación de Search y Fetch, OCR, ASR y TTS.

¿En qué se diferencia la entrada de archivos de OCR?

Utiliza la entrada de archivos cuando quieras hacer preguntas al modelo sobre un documento. Elige la API OCR independiente cuando necesites obtener el texto extraído en tu aplicación.

Para consultar un documento con el modelo:

  1. Sube el documento mediante POST https://api.deepseek.com/files con multipart/form-data.
  2. Envía el campo purpose antes de file. Invertir el orden puede devolver 400.
  3. Selecciona text_recognition o rich_layout_recognition en purpose.
  4. Recibe el file_id cuando termine el procesamiento y úsalo en una solicitud a deepseek-flash.

Este ejemplo Bash sube un 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}'

Las opciones -F generan un formulario multipart. Mantén el orden purpose, después file. No establezcas manualmente el delimitador de Content-Type: cURL lo genera.

La respuesta incluye id, que debes utilizar como file_id en la conversación. El documento se procesa durante la subida; no hay que consultar su estado por separado.

text_recognition extrae texto, pero no proporciona al modelo gráficos, fotografías ni diagramas. rich_layout_recognition también incorpora las figuras detectadas en sus posiciones dentro del documento.

En Chat Completions, la referencia al archivo dentro de un mensaje de usuario tiene este formato:

{
  "role": "user",
  "content": [
    {"type": "file", "file_id": "file-api-xxxxxxxxxxxxxxxx"},
    {"type": "text", "text": "Summarize the key points of this document."}
  ]
}

Sustituye el identificador ilustrativo por el file_id real devuelto por la subida.

Puedes referenciar como máximo 20 documentos por solicitud. El texto extraído de todos ellos no puede superar 8 MiB.

El procesamiento se cobra una vez cuando la subida se completa correctamente. Las solicitudes posteriores al modelo pagan los tokens de entrada correspondientes al contenido del documento.

Consulta la guía de procesamiento de archivos antes de implementar el flujo de subida.

¿Cuánto cuestan las herramientas web y las demás API de DeepSeek?

Al 14 de noviembre de 2026, DeepSeek cobra por separado la inferencia del modelo y el uso de herramientas.

La página oficial de precios publica las siguientes tarifas en dólares estadounidenses:

FunciónUnidad de facturaciónPrecio
Búsqueda web de texto1,000 búsquedas facturables$0.75
Búsqueda de imágenes1,000 búsquedas facturables$0.75
Fetch o lectura de URL1,000 recuperaciones facturables$0.75
Procesamiento de archivos u OCR1,000 páginas procesadas correctamente$0.225
ASR1 hora de audio$0.058 promocional; $0.116 de lista
TTS10,000 caracteres facturables$0.225 promocional; $0.45 de lista

Los descuentos de ASR y TTS se anuncian como promociones temporales. Las páginas de precios y documentación revisadas no indican cuándo terminan.

En TTS, un carácter chino cuenta como dos caracteres facturables. Los demás caracteres, incluidos los espacios, cuentan como uno.

ASR calcula la duración del audio por segundos y redondea cualquier fracción al segundo siguiente.

¿Qué campos de usage sirven para calcular los cargos?

Para las herramientas web integradas, utiliza estos contadores:

  • usage.server_tool_use.tool_search: búsquedas de texto facturables.
  • usage.server_tool_use.tool_image_search: búsquedas de imágenes facturables.
  • usage.server_tool_use.tool_fetch: recuperaciones de páginas facturables.

No calcules el importe usando web_search_requests ni web_fetch_requests.

Esos campos cuentan bloques de resultados, incluidos los que contienen errores. Son indicadores de visualización, no cantidades facturables.

Una llamada a la herramienta puede lanzar varias consultas. Si realiza tres consultas exitosas, tool_search puede aumentar en tres.

Las búsquedas fallidas o sin resultados no se cobran.

En la búsqueda de imágenes, cada imagen cuenta como una búsqueda. Cada región que selecciona el modelo dentro de una imagen cuenta como una búsqueda adicional. Las búsquedas que fallan o no encuentran resultados no se cobran.

La lectura de URL se factura cuando se recupera correctamente una página. Una página puede seguir siendo facturable si se recuperó antes de que el control de seguridad sustituyera el resultado por un error.

En la búsqueda profunda no se cobra una nueva recuperación por volver a abrir una página ya disponible en el contexto. Buscar texto dentro de una página también es gratuito.

Las API Search y Fetch independientes tienen otra regla: se cobra cada solicitud exitosa. El número de resultados de Search no multiplica el precio de la solicitud.

Ejemplo de cálculo para 100 solicitudes

Supongamos que 100 solicitudes a DeepSeek Flash, sin thinking, generan el siguiente consumo:

ConsumoCantidad supuesta
Consultas de texto facturables200
Páginas recuperadas y facturables100
Tokens de entrada sin caché200,000
Tokens de entrada desde caché0
Tokens de salida, incluida revisión de seguridad50,000
Búsquedas de imágenes0

En horario de menor demanda, deepseek-flash cuesta $0.15 por millón de tokens de entrada sin caché y $0.60 por millón de tokens de salida.

Con esos supuestos, el cálculo es:

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

La estimación es $0.285 para 100 solicitudes. Es un cálculo ilustrativo, no una medición de uso ni una factura real.

Según el calendario de DeepSeek, las horas punta son 01:00–04:00 y 06:00–10:00 UTC, de lunes a viernes, excepto los días festivos oficiales de China.

Durante esas horas, Flash cuesta $0.30 por millón de tokens de entrada sin caché y $1.20 por millón de tokens de salida.

Para el mismo consumo, la estimación en horario punta sería $0.345.

La factura real depende de los pasos de inferencia, los tokens thinking, los aciertos de caché, las búsquedas de imágenes, las páginas recuperadas, la revisión de seguridad y las tarifas vigentes.

Los tokens thinking ya están incluidos en output_tokens. No los cobres por segunda vez.

¿Se cobra una solicitud que termina con un error?

Puede cobrarse si una parte del trabajo ya se ejecutó.

Cuando la generación falla después de comenzar, DeepSeek puede devolver HTTP 200 aunque el cuerpo de la respuesta contenga un error.

Los pasos de inferencia, las búsquedas y las recuperaciones que se completaron antes del fallo se facturan normalmente.

En streaming, comprueba el evento final y los datos definitivos de usage. No consideres suficiente el estado HTTP inicial.

En Chat Completions sin streaming, comprueba si existe error aunque el estado HTTP sea 200.

En Responses, revisa status, incluidos failed e incomplete.

¿Cómo solucionar los errores 400 de las herramientas web?

Muchos errores de validación aparecen cuando se tratan las herramientas de servidor como funciones normales o se combinan opciones no admitidas.

La referencia oficial de errores de Web Tools documenta los siguientes mensajes.

Error reconocibleCausaSolución
tool_choice: deepseek_web_search cannot be forcedtool_choice fuerza una herramienta webElimina la selección forzada y deja decidir al modelo
tools: deepseek_web_search can only be declared onceHerramienta declarada dos vecesConserva una sola declaración
tools: allowed_domains is not supported by deepseek_web_searchOpciones de dominio o ubicación no admitidasElimina allowed_domains, blocked_domains y user_location
tools: other tools cannot be used together with deepseek_web_search, deepseek_read_url, safety_check or title yetDeclaración conflictiva de otra herramienta de servidorRetira la herramienta de servidor incompatible
safety_check: level must be low or highNivel de seguridad no válidoUsa low o high
messages: the last assistant message used deepseek_web_search or deepseek_read_url and cannot be continued; resend the previous requestIntento de continuar una respuesta parcial que usó herramientas webReenvía la solicitud original

En los mensajes originales, los nombres de campo aparecen entre acentos graves. La tabla omite esos delimitadores para facilitar la lectura.

No necesitas aplicar todas las soluciones. Identifica el mensaje de error, corrige la causa correspondiente y vuelve a enviar la solicitud.

¿Se puede forzar una búsqueda con tool_choice?

No. tool_choice no puede seleccionar deepseek_web_search ni deepseek_read_url como herramientas obligatorias.

Si estableces tool_choice en none, se desactivan todas las herramientas, incluida la lectura de URL.

En Chat Completions y Responses, tool_choice: "required" se interpreta como auto cuando se utilizan estas herramientas web. Tampoco garantiza que el modelo busque.

Si tu aplicación debe ejecutar una consulta específica en todos los casos, llama a la API Search independiente.

¿Pueden convivir las herramientas web con las function calls?

El error documentado se refiere a declaraciones incompatibles de herramientas de servidor.

No demuestra que todas las funciones definidas por el usuario estén prohibidas. Tampoco se ha verificado que cualquier framework de agentes admita ambas cosas.

En Responses no puedes combinar estas herramientas con web_search. Además, ciertos tipos como custom, namespace y tool_search no están admitidos.

Antes de introducirlas en Claude Code, OpenCode o un agente que ya declare funciones, comprueba la solicitud completa y el intercambio de llamadas y resultados.

Que una solicitud OpenAI-compatible funcione sin herramientas web no confirma que la combinación sea compatible.

¿Por qué continuar una respuesta con herramientas web devuelve 400?

Añadir un turno a la conversación y continuar una generación interrumpida son operaciones distintas.

Para un nuevo turno envías la respuesta completa del asistente seguida del siguiente mensaje del usuario.

La continuación intenta generar la parte restante del mismo mensaje parcial del asistente.

DeepSeek no permite continuar respuestas que hayan utilizado deepseek_web_search o deepseek_read_url.

Si se corta una respuesta con búsqueda, reenvía la solicitud anterior con un presupuesto de salida adecuado. Ten en cuenta que se podrían volver a ejecutar y cobrar búsquedas y recuperaciones.

Para otras continuaciones permitidas en Chat Completions, se documenta prefix: true en el último mensaje assistant y el endpoint beta. Ese mecanismo no elimina la restricción de las herramientas web.

¿Qué significan url_not_accessible, url_not_allowed y unavailable?

Cuando no se puede recuperar una página, DeepSeek devuelve un resultado web_fetch_tool_result_error sin signature.

El campo error_code identifica la clase de problema.

CódigoSignificadoAcción recomendada
url_not_accessibleNo se pudo leer el enlaceComprueba URL, disponibilidad, autenticación y restricciones del sitio
url_not_allowedLa lectura no está permitida o la revisión de seguridad rechazó la páginaNo evadas la restricción; solicita una fuente permitida
unavailableEl servicio no está disponible, falló la apertura durante la búsqueda profunda o la llamada no terminóRevisa el estado y considera un reintento limitado

Los tres códigos no son equivalentes.

url_not_allowed no indica necesariamente un fallo de conexión. También puede ser consecuencia de una revisión de contenido.

unavailable tampoco implica que la operación haya sido gratuita. Es posible que la página ya se hubiera recuperado antes del error.

En streaming, relaciona las llamadas con sus resultados mediante los identificadores correspondientes. Cuando se leen varias páginas, no todos los resultados llegan inmediatamente después de su llamada.

Comprueba también cómo terminó la generación:

  • end_turn en Messages indica que la respuesta terminó.
  • max_tokens significa que se agotó el límite de salida o el contexto disponible.
  • refusal indica un rechazo de la revisión de contenido.

En Chat Completions, los valores correspondientes incluyen stop, length y content_filter.

Para una aplicación de acceso público, activa la revisión de seguridad:

{
  "safety_check": {"level": "high"}
}

DeepSeek exige activar estos controles en las aplicaciones dirigidas al público. El parámetro proporciona una revisión básica de entradas y salidas, pero no sustituye la moderación propia de tu servicio ni las obligaciones aplicables de registro y etiquetado de contenido generado por IA.

Una respuesta rechazada puede seguir generando cargos por los tokens consumidos antes del rechazo.

Consulta la guía de Model Content Safety para conocer cómo informa cada protocolo de los rechazos.

¿Elegir herramientas integradas o una API de búsqueda propia?

Las herramientas integradas son adecuadas cuando quieres que el modelo gestione la investigación durante el diálogo. Las API independientes son preferibles cuando necesitas controlar cada consulta y acceder directamente al contenido recuperado.

Necesidad de la aplicaciónOpción inicialMotivo
Chatbot con respuestas y fuentesdeepseek_web_search, sin thinkingMenos lógica de búsqueda propia
Investigación de varias fuentesdeepseek_web_search, con thinkingEl modelo puede buscar y revisar páginas en varios pasos
Resumir enlaces del usuariodeepseek_read_urlLee URL válidas y conserva el contexto mediante firmas
Buscar en un sitio específicoSearch independienteEl código controla operadores y resultados
Obtener Markdown de una URL conocidaFetch independienteEl contenido llega directamente a la aplicación
Extraer texto de numerosos documentosOCR independienteDevuelve texto por páginas
Preguntar sobre un documento subidoFile Parsing y deepseek-flashEl documento entra en el contexto del modelo
Entrada por voz o lectura en voz altaASR y TTSInterfaces dedicadas al procesamiento de audio

Si ya tienes un agente de programación, puede convenirte conservar una integración externa de búsqueda. Así mantienes su actual sistema de herramientas y la lógica de recuperación.

La guía para añadir Parallel Search MCP a un agente presenta una alternativa. Compara el coste real, la compatibilidad y el contenido recuperado en las mismas tareas antes de elegir.

¿Funcionan estas herramientas con BetterToken y otras pasarelas?

Al 14 de noviembre de 2026, deepseek-flash figuraba en el catálogo de BetterToken. Consulta los precios actuales de los modelos antes de elegir la vía de acceso.

Sin embargo, que un modelo aparezca en el catálogo no demuestra que la pasarela admita las nuevas herramientas de servidor de DeepSeek.

No se ha verificado si BetterToken reenvía las declaraciones de herramientas, conserva signature, devuelve usage.server_tool_use o registra los cargos adicionales por herramienta.

Por eso todos los ejemplos de esta guía utilizan el endpoint oficial de DeepSeek.

Antes de usar una pasarela compatible, verifica una solicitud de búsqueda, otra de lectura de URL y un segundo turno que conserve signature. Después contrasta los contadores usage con los cargos reales.

Para una nueva aplicación, empieza con búsqueda normal y thinking desactivado. Comprueba las citas y el uso facturable. Activa la búsqueda profunda cuando hagan falta varios pasos de investigación. Reserva Search y Fetch independientes para operaciones cuyo control deba permanecer en tu código.

¿Quieres optimizar tu flujo de trabajo con LLM?

Conecta modelos mediante una API, gestiona claves y controla el gasto en IA.

Empezar gratis