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

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.
| Mode | Outil déclaré | Thinking | Comportement |
|---|---|---|---|
| Recherche web normale | deepseek_web_search | Désactivé | Le modèle recherche si nécessaire et répond avec des citations |
| Recherche approfondie | deepseek_web_search | Activé | Le modèle recherche, ouvre des pages et analyse leur texte en plusieurs étapes |
| Lecture d’URL | deepseek_read_url | Désactivé, ou activé sans recherche web | Le modèle examine les URL du dernier message utilisateur |
| Recherche et lecture d’URL | Les deux outils | Dé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.
| API | Endpoint | Déclaration indiquée dans la documentation | Contrô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 |
|---|---|
| Messages | Les blocs content précédents de l’assistant, avec kind et signature |
| Responses | Les éléments output précédents, avec web_search_call, kind et signature |
| Chat Completions | Le 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
| API | Endpoint sous https://api.deepseek.com | Entrée requise | Résultat |
|---|---|---|---|
| Search | POST /v1/tools/search | JSON avec query | results structurés |
| Fetch | POST /v1/tools/fetch | JSON avec url | title et content de la page au format Markdown |
| OCR | POST /v1/tools/ocr | Champs multipart file, purpose | pages[].text et page_count |
| ASR | POST /v1/tools/asr | Fichier audio multipart file | Transcription text et duration_ms |
| TTS | POST /v1/tools/tts | JSON avec text | Audio 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 :
queryaccepte 1–128 caractères Unicode.countpermet 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 :
- Envoyez-le à
POST https://api.deepseek.com/filesau formatmultipart/form-data. - Placez le champ
purposeavant le champfile. L’ordre inverse peut provoquer une erreur400. - Utilisez
text_recognitionourich_layout_recognitiondanspurpose. - Récupérez le
file_idaprè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 :
| Fonction | Unité de facturation | Tarif |
|---|---|---|
| Recherche web textuelle | 1,000 recherches facturables | $0.75 |
| Recherche d’images | 1,000 recherches facturables | $0.75 |
| Web Fetch ou lecture d’URL | 1,000 récupérations facturables | $0.75 |
| Analyse de fichiers ou OCR | 1,000 pages traitées avec succès | $0.225 |
| ASR | 1 heure d’audio | $0.058 promotionnel ; $0.116 normal |
| TTS | 10,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 :
| Utilisation | Hypothèse |
|---|---|
| Recherches textuelles facturables | 200 |
| Pages récupérées facturables | 100 |
| Tokens d’entrée non servis depuis le cache | 200,000 |
| Tokens d’entrée servis depuis le cache | 0 |
| Tokens de sortie, y compris contrôle de sécurité | 50,000 |
| Recherches d’images | 0 |
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’erreur | Cause | Correction |
|---|---|---|
tool_choice: deepseek_web_search cannot be forced | tool_choice force un outil Web serveur | Supprimez le choix forcé et laissez le modèle décider |
tools: deepseek_web_search can only be declared once | L’outil est déclaré deux fois | Gardez une seule déclaration |
tools: allowed_domains is not supported by deepseek_web_search | Options de domaine ou de localisation non admises | Supprimez 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 yet | Un autre outil serveur incompatible est déclaré | Retirez l’outil serveur en conflit |
safety_check: level must be low or high | Niveau de sécurité invalide | Utilisez low ou high |
messages: the last assistant message used deepseek_web_search or deepseek_read_url and cannot be continued; resend the previous request | Tentative de reprendre une réponse partielle utilisant un outil Web | Renvoyez 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.
| Code | Signification | Action recommandée |
|---|---|---|
url_not_accessible | Impossible de lire le lien | Vérifiez l’URL, la disponibilité, l’authentification et les restrictions du site |
url_not_allowed | Lecture interdite ou page rejetée par le contrôle de sécurité | Ne contournez pas la restriction ; demandez une source autorisée |
unavailable | Service 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_turndans Messages signifie que la réponse est terminée.max_tokenssignale une limite de sortie ou de contexte atteinte.refusalindique 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’application | Première option | Pourquoi |
|---|---|---|
| Chatbot avec réponses sourcées | deepseek_web_search, thinking désactivé | Moins de code pour orchestrer les recherches |
| Analyse de plusieurs sources | deepseek_web_search, thinking activé | Le modèle peut rechercher et inspecter des pages en plusieurs étapes |
| Résumer les liens fournis par l’utilisateur | deepseek_read_url | Lit les URL admissibles et conserve le contexte avec des signatures |
| Rechercher sur un site précis | Search autonome | Votre code contrôle la requête et les résultats |
| Obtenir du Markdown depuis une URL connue | Fetch autonome | L’application reçoit directement le contenu |
| Extraire du texte de nombreux documents | OCR autonome | Fournit les résultats page par page |
| Poser des questions sur un document importé | File Parsing et deepseek-flash | Le document rejoint le contexte du modèle |
| Entrée vocale ou lecture à voix haute | ASR et TTS | API 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.