DeepSeek API : recherche web, lecture d’URL, tarifs et erreurs 400

Configurez la recherche web et la lecture d’URL côté serveur avec deepseek-flash, dans les API Chat Completions, Messages et Responses. Choisissez le mode thinking, conservez signature entre les tours, calculez les frais de recherche et de récupération de pages en plus des tokens, puis corrigez les erreurs 400. Comparez aussi les outils intégrés aux API autonomes Search, Fetch, OCR, ASR et TTS.

Sommaire
DeepSeek API : recherche web, lecture d’URL, tarifs et erreurs 400

Pour créer un chatbot qui recherche des informations sur le Web et cite ses sources, utilisez deepseek-flash avec deepseek_web_search et désactivez thinking. Activez thinking pour les recherches en plusieurs étapes, ou déclarez deepseek_read_url pour lire les liens fournis par l’utilisateur. Commencez par l’API officielle de DeepSeek : une passerelle compatible ne conserve pas nécessairement les champs et les résultats particuliers de ces outils serveur.

DeepSeek a lancé ces fonctions le 13 novembre 2026. La recherche, la lecture d’URL, le traitement des fichiers et les services vocaux sont facturés séparément des tokens du modèle.

Ce guide présente les requêtes des trois API compatibles, les contrôles à effectuer, les compteurs de facturation, les erreurs 400 et les cas où il vaut mieux employer des API autonomes.

Qu’a apporté la mise à jour DeepSeek du 13 novembre ?

DeepSeek a ouvert aux développeurs plusieurs fonctions jusque-là principalement associées à son application de chat.

Selon les notes de version officielles du 13 novembre, DeepSeek V4.1 Flash, accessible avec l’identifiant deepseek-flash, prend désormais en charge :

  • La recherche sur le Web et la recherche d’images avec citation des sources.
  • La recherche approfondie, avec plusieurs étapes de raisonnement, ouverture de pages et recherche dans leur texte.
  • La lecture des URL contenues dans le message de l’utilisateur.
  • L’importation de PDF, de fichiers Office et d’images, avec extraction de texte ou analyse de la mise en page.
  • Les contrôles de sécurité sur les entrées et les sorties du modèle.

Ces fonctions sont disponibles dans Messages, Responses et Chat Completions. DeepSeek exécute les outils côté serveur et ajoute leurs résultats au contexte du modèle.

Votre application n’a donc pas à lancer elle-même les recherches ou les téléchargements de pages lorsqu’elle utilise les outils intégrés.

DeepSeek propose également les API autonomes Search, Fetch, OCR, ASR et TTS. Celles-ci transmettent directement à votre code des résultats de recherche, du texte extrait, des transcriptions ou des fichiers audio.

Choisir le bon mode de recherche

Le paramètre thinking détermine le fonctionnement de deepseek_web_search.

ModeOutil déclaréThinkingComportement
Recherche web normaledeepseek_web_searchDésactivéLe modèle recherche si nécessaire et répond avec des citations
Recherche approfondiedeepseek_web_searchActivéLe modèle recherche, ouvre des pages et analyse leur texte en plusieurs étapes
Lecture d’URLdeepseek_read_urlDésactivé, ou activé sans recherche webLe modèle examine les URL du dernier message utilisateur
Recherche et lecture d’URLLes deux outilsDésactivéLe modèle choisit entre effectuer une recherche et lire les URL fournies

La recherche approfondie peut effectuer jusqu’à environ 20 appels d’outils avant de répondre. Ce plafond est approximatif et documenté ; le nombre d’appels n’est pas garanti pour chaque requête.

Attention à l’interaction entre les deux outils.

Si thinking est activé et que deepseek_web_search est déclaré, la requête utilise la recherche approfondie. Le comportement distinct de lecture d’URL de deepseek_read_url ne s’exécute pas.

Si votre application doit examiner des URL précises fournies par l’utilisateur, déclarez uniquement deepseek_read_url.

Déclarer un outil serveur ne force pas son exécution. Le modèle décide de rechercher ou de récupérer une page.

Pour mieux comprendre le modèle, consultez le guide des performances de programmation et des tarifs de DeepSeek V4.1 Flash.

Comment activer deepseek_web_search dans Chat Completions ?

Envoyez une requête POST https://api.deepseek.com/chat/completions, sélectionnez deepseek-flash et déclarez l’outil dans tools.

Il vous faut une clé API DeepSeek active, le shell Bash, cURL et jq.

La commande Bash suivante active la recherche web normale et le contrôle de sécurité du contenu. La première ligne lit la clé sans afficher les caractères saisis. Lorsque la commande attend une entrée, collez la clé créée dans votre compte 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
  }'

Une réponse correcte avec recherche peut contenir les champs suivants :

  • choices[0].message.content : le texte de la réponse.
  • choices[0].message.annotations : les URL des sources et les positions des citations.
  • choices[0].message.server_tool_calls : les étapes de recherche exécutées sur le serveur.
  • usage.server_tool_use : les compteurs d’utilisation pour les recherches et les récupérations de pages.

Une réponse terminée présente choices[0].finish_reason = "stop". La valeur length indique une réponse interrompue par la limite de sortie. content_filter signale un refus lié au contrôle du contenu.

L’absence de server_tool_calls n’indique pas nécessairement un échec. Le modèle a peut-être jugé la recherche inutile. Posez une question nécessitant des informations récentes et vérifiez à nouveau le résultat.

Activer la recherche approfondie

Conservez la déclaration de recherche et modifiez le paramètre thinking :

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

Choisissez ce mode lorsque la question demande plusieurs recherches ou une comparaison entre diverses sources.

La recherche approfondie peut ouvrir des pages et y retrouver des passages précis. Elle peut donc consommer davantage de tokens d’inférence et de récupérations de pages facturables qu’une recherche normale.

Le modèle détermine lui-même les étapes à effectuer.

Lire des URL sans lancer de recherche

Ne déclarez que deepseek_read_url et incluez l’adresse dans le dernier message utilisateur :

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

Utilisez le même endpoint Chat Completions, le même modèle, la même authentification et le même paramètre de sécurité que dans le premier exemple.

La lecture d’URL obéit à plusieurs règles :

  • Seul le dernier message de l’utilisateur est analysé pour détecter les URL.
  • Une URL répétée n’est comptée qu’une fois.
  • Seules les 10 premières URL distinctes sont prises en compte.
  • Le modèle choisit lesquelles de ces URL il va lire.
  • Le contenu de plusieurs longues pages peut être tronqué.

Ces règles figurent dans le guide officiel Web Tools.

Une URL présente uniquement dans un ancien message ne déclenche pas automatiquement une nouvelle lecture à la requête suivante.

Comment déclarer ces outils dans Messages et Responses ?

Les trois API prennent en charge ces outils serveur, mais leurs requêtes et leurs réponses n’ont pas la même structure.

APIEndpointDéclaration indiquée dans la documentationContrôle 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

Ces chemins utilisent tous l’hôte https://api.deepseek.com.

Dans les exemples officiels pour Messages, la déclaration de l’outil contient type et name. Ces exemples ne prouvent toutefois pas que name soit obligatoire dans toute requête valide.

Messages utilise l’en-tête x-api-key. Chat Completions et Responses utilisent Authorization: Bearer.

Si vous changez de protocole, consultez les différences de compatibilité entre Messages, Chat Completions et Responses. Un identifiant de modèle identique ne garantit pas un format identique pour les outils et l’historique.

Exemple pour l’API Messages

Cette commande Bash lit une URL avec le format Messages compatible avec 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
  }'

Le texte de la réponse se trouve dans les blocs content. Les appels aux outils apparaissent dans des blocs server_tool_use, suivis de blocs de résultats.

Les citations sont associées aux blocs de texte. Une réponse terminée indique stop_reason = "end_turn".

En streaming, récupérez la consommation totale à partir du dernier événement message_delta. Le champ usage de message_start ne couvre que la première étape d’inférence.

Exemple pour l’API Responses

Dans Responses, utilisez reasoning.effort à la place de thinking.type.

La valeur none désactive thinking. Les valeurs low, high et max l’activent avec le niveau d’effort demandé.

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
  }'

Responses présente l’activité des outils sous forme d’éléments web_search_call dans output. La réponse finale est un élément message, avec les sources dans les annotations de output_text.

Une réponse achevée possède status = "completed". Une interruption due à la limite de sortie ou au contrôle du contenu peut donner incomplete. Un échec de génération peut donner failed.

Avant de relancer une requête, consultez incomplete_details.reason ou error.code.

Ne traitez pas les objets de réponse des trois protocoles comme s’ils étaient identiques. La différence compte particulièrement pour la conservation des résultats des outils entre les tours.

Pourquoi conserver signature d’un tour à l’autre ?

Quand deepseek_read_url lit une page avec succès, DeepSeek renvoie une représentation chiffrée de son contenu dans signature.

Le texte de la page ne figure pas directement dans le bloc de résultat. Les champs url, title, data et published_at servent surtout à l’affichage.

Aux tours suivants, DeepSeek peut utiliser signature pour restaurer le contenu de la page dans le contexte de la conversation.

Renvoyez les réponses précédentes de l’assistant sans les modifier, y compris kind, signature et la structure complète des appels serveur.

Cet exemple Python utilise Chat Completions. Il conserve l’intégralité du premier message de l’assistant avant d’envoyer la question suivante.

Installez requests et exportez DEEPSEEK_API_KEY dans votre environnement avant l’exécution.

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"])

Cet exemple illustre le format de conversation documenté. Il ne s’agit pas du résultat d’un test exécuté sur l’API.

Examinez first_reply["server_tool_calls"] pour savoir si le modèle a réellement lu l’URL. Si aucun appel read_link n’apparaît, le premier message ne contient aucune signature de page lue à préserver.

Pour les autres protocoles, conservez les structures correspondantes :

APIÉléments à renvoyer
MessagesLes blocs content précédents de l’assistant, avec kind et signature
ResponsesLes éléments output précédents, avec web_search_call, kind et signature
Chat CompletionsLe message complet de l’assistant, avec server_tool_calls

Si une bibliothèque ou une passerelle supprime signature, la requête suivante peut quand même réussir. Cependant, le contenu de la page lue précédemment ne sera plus restauré.

Les résultats de recherche, les pages ouvertes lors d’une recherche approfondie et les raisonnements précédents ne sont pas automatiquement conservés dans leur intégralité. En général, seul le texte de la réponse est repris aux tours suivants. Les pages récupérées à partir d’une signature valide constituent l’exception documentée.

Ne réduisez donc pas l’historique de l’assistant aux seuls champs role et content lorsque vous avez besoin de conserver ces pages.

Quand utiliser les API autonomes Search, Fetch, OCR, ASR et TTS ?

Utilisez les API autonomes lorsque votre application doit maîtriser directement la récupération ou le traitement des données.

Contrairement aux outils intégrés, elles renvoient leurs résultats à votre propre code. Vous pouvez alors les vérifier, les filtrer, les stocker et choisir ce qui sera transmis au modèle.

Endpoints et entrées des API autonomes

APIEndpoint sous https://api.deepseek.comEntrée requiseRésultat
SearchPOST /v1/tools/searchJSON avec queryresults structurés
FetchPOST /v1/tools/fetchJSON avec urltitle et content de la page au format Markdown
OCRPOST /v1/tools/ocrChamps multipart file, purposepages[].text et page_count
ASRPOST /v1/tools/asrFichier audio multipart fileTranscription text et duration_ms
TTSPOST /v1/tools/ttsJSON avec textAudio WAV ou PCM

Les cinq API utilisent l’authentification Bearer.

Les commandes Bash suivantes montrent les requêtes directes. Elles utilisent la variable DEEPSEEK_API_KEY exportée précédemment.

# 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

Les exemples OCR et ASR nécessitent des fichiers locaux. La commande TTS crée speech.wav dans le répertoire de travail.

Principales limites documentées au 14 novembre 2026 :

  • Search : query accepte 1–128 caractères Unicode. count permet de demander 1–50 résultats. La limite par compte est de 100 QPS.
  • Fetch : une seule URL HTTP ou HTTPS par requête, sous réserve des règles d’accès du site. La limite par compte est de 25 QPS, avec une limite QPS supplémentaire par domaine.
  • OCR : taille maximale de 100 MiB et 1,000 pages par fichier. Jusqu’à 15 reconnaissances simultanées par compte.
  • ASR : maximum 120 secondes et 8 MiB par requête. Les formats 16-bit PCM WAV et Ogg Opus sont pris en charge.
  • TTS : maximum 10,000 caractères facturables par requête. La synthèse complète et le streaming WebSocket sont disponibles.

Search accepte des opérateurs tels que site:, lang: et after:. Au 14 novembre 2026, l’API Search autonome ne prend pas en charge la recherche d’images. Cette capacité est disponible avec l’outil Web intégré.

Pour les conditions détaillées, consultez les guides Search et Fetch, OCR, ASR et TTS.

Quelle différence entre l’importation de fichiers et OCR ?

L’importation de fichiers sert à poser des questions au modèle sur un document. L’API OCR autonome permet de récupérer directement le texte extrait dans votre application.

Pour utiliser un document avec le modèle :

  1. Envoyez-le à POST https://api.deepseek.com/files au format multipart/form-data.
  2. Placez le champ purpose avant le champ file. L’ordre inverse peut provoquer une erreur 400.
  3. Utilisez text_recognition ou rich_layout_recognition dans purpose.
  4. Récupérez le file_id après le traitement, puis référencez-le dans une requête à deepseek-flash.

Cet exemple Bash importe 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}'

Les options -F créent une requête de formulaire multipart. Respectez l’ordre purpose, puis file. Ne définissez pas manuellement la frontière multipart dans Content-Type : cURL la génère automatiquement.

La réponse contient un champ id à utiliser comme file_id dans la conversation. L’analyse est effectuée pendant l’importation, sans étape supplémentaire de consultation d’état.

text_recognition extrait uniquement le texte, sans transmettre les figures au modèle. rich_layout_recognition transmet également les images détectées aux emplacements correspondants du document.

Dans Chat Completions, un message utilisateur peut référencer le fichier comme ceci :

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

Remplacez l’identifiant d’exemple par le véritable file_id renvoyé lors de l’importation.

Une requête peut référencer au maximum 20 documents. Leur texte extrait ne doit pas dépasser 8 MiB au total.

L’analyse du fichier est facturée une seule fois lorsque l’importation réussit. Les conversations ultérieures qui utilisent ce document sont facturées selon les tokens d’entrée correspondant à son contenu.

Consultez le guide d’analyse des documents avant de développer ce parcours.

Combien coûtent les outils Web et les autres API de DeepSeek ?

Au 14 novembre 2026, DeepSeek facture séparément les tokens du modèle et l’utilisation des outils.

La grille tarifaire officielle indique les prix suivants en dollars américains :

FonctionUnité de facturationTarif
Recherche web textuelle1,000 recherches facturables$0.75
Recherche d’images1,000 recherches facturables$0.75
Web Fetch ou lecture d’URL1,000 récupérations facturables$0.75
Analyse de fichiers ou OCR1,000 pages traitées avec succès$0.225
ASR1 heure d’audio$0.058 promotionnel ; $0.116 normal
TTS10,000 caractères facturables$0.225 promotionnel ; $0.45 normal

Les réductions ASR et TTS sont annoncées comme temporaires. Les pages de tarifs et les guides consultés n’indiquent pas de date de fin.

Pour TTS, un caractère chinois compte pour deux caractères facturables. Les autres caractères, espaces compris, comptent chacun pour un.

Pour ASR, la durée est comptabilisée à la seconde, avec arrondi à la seconde supérieure en cas de fraction.

Quels champs usage représentent la consommation facturable ?

Pour les outils Web intégrés, utilisez :

  • usage.server_tool_use.tool_search : nombre de recherches textuelles facturables.
  • usage.server_tool_use.tool_image_search : nombre de recherches d’images facturables.
  • usage.server_tool_use.tool_fetch : nombre de récupérations de pages facturables.

Ne calculez pas les frais avec web_search_requests ou web_fetch_requests.

Ces champs comptent les blocs de résultats, y compris ceux qui contiennent des erreurs. Ce sont des compteurs d’affichage et non des quantités facturables.

Un appel de recherche peut soumettre plusieurs requêtes. S’il lance trois requêtes qui réussissent, tool_search peut augmenter de trois unités.

Une recherche qui échoue ou ne renvoie aucun résultat n’est pas facturée.

Pour la recherche d’images, chaque image compte pour une recherche. Chaque région sélectionnée par le modèle dans une image compte pour une recherche supplémentaire. Les recherches qui échouent ou ne trouvent rien ne sont pas facturées.

Une URL est facturée lorsqu’une page a été récupérée avec succès. Si le contrôle de sécurité remplace ensuite le résultat par une erreur, la récupération initiale peut tout de même être facturée.

Dans la recherche approfondie, rouvrir une page déjà disponible dans le contexte n’entraîne pas de nouveau frais de récupération. Chercher du texte dans une page est également gratuit.

Les API Search et Fetch autonomes suivent une autre règle : chaque requête réussie est facturée une fois. Le nombre de résultats de Search ne multiplie pas le coût de la requête.

Exemple de calcul pour 100 requêtes

Supposons que 100 requêtes à DeepSeek Flash, avec thinking désactivé, produisent les volumes suivants :

UtilisationHypothèse
Recherches textuelles facturables200
Pages récupérées facturables100
Tokens d’entrée non servis depuis le cache200,000
Tokens d’entrée servis depuis le cache0
Tokens de sortie, y compris contrôle de sécurité50,000
Recherches d’images0

Pour deepseek-flash, le tarif hors pointe officiel est de $0.15 par million de tokens d’entrée hors cache et de $0.60 par million de tokens de sortie.

Le calcul est le suivant :

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

Le total estimé est de $0.285 pour 100 requêtes. C’est une simulation fondée sur des hypothèses, pas une mesure ou une facture réelle.

D’après les horaires publiés par DeepSeek, les périodes de pointe vont de 01:00–04:00 et 06:00–10:00 UTC, du lundi au vendredi, hors jours fériés chinois.

Pendant ces périodes, les tarifs Flash sont de $0.30 par million de tokens d’entrée hors cache et de $1.20 par million de tokens de sortie.

Pour les mêmes volumes, le coût estimé en période de pointe est de $0.345.

Le coût réel varie selon les étapes d’inférence, les tokens thinking, les lectures du cache, les recherches d’images, les pages récupérées, les contrôles de sécurité et les tarifs en vigueur.

Les tokens thinking sont déjà inclus dans output_tokens. Ne les comptez pas une seconde fois.

Une requête en échec peut-elle être facturée ?

Oui, si des opérations ont déjà été effectuées avant l’échec.

Si la génération échoue après avoir commencé, DeepSeek peut renvoyer un statut HTTP 200 alors que le corps contient une erreur.

Les étapes d’inférence, recherches et récupérations déjà effectuées restent facturables.

En streaming, inspectez l’événement final et la consommation totale. Le premier statut HTTP ne suffit pas à confirmer le succès.

Dans Chat Completions sans streaming, recherchez un objet error même si le statut HTTP est 200.

Dans Responses, vérifiez status, notamment les valeurs failed et incomplete.

Comment corriger les erreurs 400 des outils Web ?

La plupart des erreurs de validation proviennent d’une sélection forcée de l’outil, d’une déclaration dupliquée ou de paramètres non pris en charge.

La référence officielle des erreurs Web Tools présente les messages suivants.

Message d’erreurCauseCorrection
tool_choice: deepseek_web_search cannot be forcedtool_choice force un outil Web serveurSupprimez le choix forcé et laissez le modèle décider
tools: deepseek_web_search can only be declared onceL’outil est déclaré deux foisGardez une seule déclaration
tools: allowed_domains is not supported by deepseek_web_searchOptions de domaine ou de localisation non admisesSupprimez allowed_domains, blocked_domains et user_location
tools: other tools cannot be used together with deepseek_web_search, deepseek_read_url, safety_check or title yetUn autre outil serveur incompatible est déclaréRetirez l’outil serveur en conflit
safety_check: level must be low or highNiveau de sécurité invalideUtilisez low ou high
messages: the last assistant message used deepseek_web_search or deepseek_read_url and cannot be continued; resend the previous requestTentative de reprendre une réponse partielle utilisant un outil WebRenvoyez la requête initiale

Les messages d’origine entourent les noms de champs de guillemets de code. Ce tableau omet ces délimiteurs pour faciliter la lecture.

Il est inutile d’appliquer toutes les corrections. Repérez votre erreur, modifiez le paramètre concerné, puis renvoyez la requête.

Peut-on forcer un outil Web avec tool_choice ?

Non. tool_choice ne peut pas désigner deepseek_web_search ou deepseek_read_url comme outil obligatoire.

Avec tool_choice défini sur none, tous les outils sont désactivés, y compris la lecture d’URL.

Dans Chat Completions et Responses, tool_choice: "required" est traité comme auto lorsque ces outils Web sont utilisés. Cela ne garantit donc pas l’exécution d’une recherche.

Si votre application doit absolument effectuer une requête précise, appelez directement l’API Search autonome.

Peut-on combiner ces outils avec des function calls ordinaires ?

L’erreur documentée concerne les déclarations incompatibles d’outils serveur.

Elle ne démontre pas que toutes les fonctions ordinaires définies par le développeur sont interdites. Cependant, leur compatibilité avec chaque framework d’agents n’a pas été vérifiée.

Dans Responses, ces outils ne peuvent pas être déclarés avec web_search. Les types custom, namespace et tool_search ne sont pas non plus pris en charge.

Avant de les ajouter à Claude Code, OpenCode ou à votre agent avec fonctions, testez la requête complète et l’aller-retour des appels et résultats.

Une requête OpenAI-compatible réussie sans outils Web ne prouve pas que leur combinaison fonctionne.

Pourquoi la reprise d’une réponse avec outils Web donne-t-elle 400 ?

Un nouveau tour de conversation et la poursuite d’une génération interrompue sont deux opérations différentes.

Lors d’un nouveau tour, vous envoyez la réponse complète de l’assistant suivie d’un nouveau message utilisateur.

La continuation tente de compléter le même message partiel de l’assistant.

DeepSeek interdit de continuer une réponse qui a utilisé deepseek_web_search ou deepseek_read_url.

Si une réponse avec recherche est coupée, renvoyez la requête précédente avec une limite de sortie adaptée. Les recherches et les récupérations peuvent être exécutées et facturées à nouveau.

Pour les autres continuations autorisées dans Chat Completions, DeepSeek documente prefix: true sur le dernier message assistant, avec l’endpoint beta. Cette méthode ne contourne pas la restriction des outils Web.

Que signifient url_not_accessible, url_not_allowed et unavailable ?

Lorsqu’une récupération échoue, DeepSeek retourne web_fetch_tool_result_error sans champ signature.

La valeur de error_code indique le problème.

CodeSignificationAction recommandée
url_not_accessibleImpossible de lire le lienVérifiez l’URL, la disponibilité, l’authentification et les restrictions du site
url_not_allowedLecture interdite ou page rejetée par le contrôle de sécuritéNe contournez pas la restriction ; demandez une source autorisée
unavailableService indisponible, ouverture impossible pendant la recherche approfondie ou appel non terminéVérifiez l’état de la réponse et envisagez un nombre limité de nouvelles tentatives

Ces codes ne sont pas interchangeables.

url_not_allowed ne signifie pas forcément un problème de réseau. La page peut avoir été rejetée par le contrôle de contenu.

unavailable ne signifie pas automatiquement que l’opération était gratuite. La page peut avoir déjà été récupérée avant l’erreur.

En streaming, associez les appels et les résultats à l’aide de leurs identifiants. Lorsque plusieurs pages sont lues, leurs résultats ne suivent pas forcément immédiatement les appels correspondants.

Vérifiez également la raison d’arrêt :

  • end_turn dans Messages signifie que la réponse est terminée.
  • max_tokens signale une limite de sortie ou de contexte atteinte.
  • refusal indique un refus de l’examen du contenu.

Dans Chat Completions, les valeurs correspondantes comprennent stop, length et content_filter.

Pour une application accessible au public, activez le contrôle de sécurité :

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

DeepSeek demande aux fournisseurs de services accessibles au public d’activer ce contrôle. Il assure une vérification de base des entrées et sorties, sans remplacer votre modération ni les éventuelles obligations d’enregistrement et de signalement du contenu généré par l’IA.

Une réponse refusée peut encore occasionner des frais pour les tokens consommés avant le refus.

Le guide Model Content Safety détaille la manière dont chaque protocole signale les refus.

Faut-il choisir les outils intégrés ou une API de recherche externe ?

Privilégiez les outils intégrés lorsque le modèle doit gérer les recherches pendant la conversation. Choisissez des API autonomes lorsque votre application doit contrôler chaque requête et recevoir directement les données récupérées.

Besoin de l’applicationPremière optionPourquoi
Chatbot avec réponses sourcéesdeepseek_web_search, thinking désactivéMoins de code pour orchestrer les recherches
Analyse de plusieurs sourcesdeepseek_web_search, thinking activéLe modèle peut rechercher et inspecter des pages en plusieurs étapes
Résumer les liens fournis par l’utilisateurdeepseek_read_urlLit les URL admissibles et conserve le contexte avec des signatures
Rechercher sur un site précisSearch autonomeVotre code contrôle la requête et les résultats
Obtenir du Markdown depuis une URL connueFetch autonomeL’application reçoit directement le contenu
Extraire du texte de nombreux documentsOCR autonomeFournit les résultats page par page
Poser des questions sur un document importéFile Parsing et deepseek-flashLe document rejoint le contexte du modèle
Entrée vocale ou lecture à voix hauteASR et TTSAPI dédiées au traitement audio

Pour un agent de programmation existant, conserver une intégration de recherche externe peut être préférable. Vous évitez ainsi de modifier son orchestration d’outils et sa logique de récupération.

Le guide d’intégration de Parallel Search MCP dans un agent présente une autre approche. Comparez les coûts réels, la compatibilité et la qualité des contenus récupérés sur des tâches équivalentes.

Et avec BetterToken ou une autre passerelle compatible ?

Au 14 novembre 2026, le catalogue de modèles BetterToken répertoriait deepseek-flash. Consultez les tarifs actuels des modèles avant de choisir votre mode d’accès.

Mais la présence du modèle dans un catalogue ne prouve pas que la passerelle prend en charge les nouveaux outils serveur de DeepSeek.

La transmission des déclarations d’outils, la conservation de signature, le retour de usage.server_tool_use et la facturation des outils n’ont pas été vérifiés via BetterToken.

Tous les exemples de ce guide utilisent donc l’endpoint officiel DeepSeek.

Avant de passer par une passerelle compatible, vérifiez une requête avec recherche, une requête avec lecture d’URL et un deuxième tour qui conserve signature. Comparez ensuite les compteurs usage aux frais réellement prélevés.

Pour une nouvelle application, commencez par la recherche normale avec thinking désactivé. Vérifiez les sources et l’utilisation facturable. Activez la recherche approfondie lorsque plusieurs étapes sont nécessaires. Réservez Search et Fetch autonomes aux opérations que votre code doit contrôler.

Prêt à optimiser votre workflow LLM ?

Connectez vos modèles via une API unique, gérez les clés et maîtrisez vos dépenses d’IA.

Commencer gratuitement