DeepSeek API Guide

DeepSeek propose une plateforme d’API permettant d’accéder à ses modèles de langage avancés, avec un format compatible avec l’API OpenAI. Elle permet aux développeurs d’intégrer ces modèles dans leurs applications (chatbots, SaaS, assistants virtuels, etc.) via des appels HTTP standard.

Ce guide avancé, mis à jour au 27 mars 2026, s’adresse aux développeurs back-end et aux ingénieurs IA souhaitant exploiter les fonctionnalités avancées de l’API DeepSeek. Nous supposons que vous disposez déjà d’une clé API et que vous avez effectué quelques appels de base (le cas échéant, commencez par notre guide débutant pour créer un chatbot avec l’API DeepSeek). Dans ce guide, nous approfondissons les points suivants :

• Modèles de l’API : différence entre deepseek-chat (mode normal) et deepseek-reasoner (mode raisonneur « thinking »).
• Paramètres de génération : réglages avancés (temperature, top_p, max_tokens, etc.) et spécificités en mode raisonneur.
• Mode “thinking” (raisonneur) : comment l’activer (modèle ou paramètre), fonctionnement du chain-of-thought avec reasoning_content.
• Sortie JSON structurée (JSON Output) : forcer une réponse au format JSON, avec exemples et erreurs courantes (ex : réponse vide).
• Appels d’outils externes (Tool Calls) : utilisation des fonctions, format des requêtes/réponses, mode strict et pièges à éviter.
• Cache de contexte (Context Caching) : principe, cas d’usage, impact sur les coûts et bonnes pratiques pour en tirer parti.
• Streaming des réponses : intégration front-end (SSE), parsing du flux en continu et implications UX.
• Compatibilité Anthropic: utilisation de DeepSeek via l’API Anthropic (Claude) avec configuration minimale.
• Gestion des erreurs : significations des codes 400, 401, 422, 429, 500, 503, et stratégies de retry/fallback pour renforcer la robustesse.

Table des matières :

• Présentation des modèles DeepSeek : deepseek-chat vs deepseek-reasoner
• Paramètres de génération principaux (temperature, top_p, etc.)
• Mode raisonneur (Thinking mode) et reasoning_content
• Sortie JSON structurée (fonctionnalité JSON Output)
• Appels d’outils externes (Tool Calls) et mode strict
• Cache de contexte : principe et bénéfices
• Streaming des réponses en temps réel
• Compatibilité avec l’API d’Anthropic
• Gestion des erreurs, retries et fallback
• FAQ technique (DeepSeek API)
• Sources officielles

Modèles DeepSeek : deepseek-chat vs deepseek-reasoner

L’API DeepSeek propose deux modèles principaux pour les complétions conversationnelles : deepseek-chat et deepseek-reasoner. Ces deux noms correspondent en pratique à la version DeepSeek-V3.2 (modèle de fin 2025) déployée côté API, avec une fenêtre de contexte étendue à 128k tokens:

• deepseek-chat – Mode classique (« non-thinking ») : ce modèle est optimisé pour les réponses rapides et factuelles en conversation. Il fonctionne comme un chatbot standard, similaire à ChatGPT, fournissant directement la réponse finale à l’utilisateur. C’est le modèle par défaut à utiliser pour la plupart des usages courants nécessitant des réponses concises et efficaces. Il prend en charge les fonctionnalités habituelles de l’API (tool use, output JSON, etc.) et supporte les paramètres aléatoires comme la température (voir plus bas). Fenêtre contextuelle : jusqu’à 128k tokens, avec une réponse par défaut limitée à ~4096 tokens (max 8192 tokens configurables).
• deepseek-reasoner – Mode raisonneur (« thinking ») : ce modèle active le mode “pensée” (chain-of-thought) de DeepSeek V3.2. Avant de donner sa réponse finale, le modèle génère en interne un raisonnement pas à pas détaillé qu’il peut exposer via un champ spécial reasoning_content. Ce mode vise les tâches complexes (problèmes de math, questions de programmation, analyses logiques) où décomposer la réflexion améliore la justesse de la réponse. L’inconvénient est une latence plus élevée et une consommation de tokens accrue : en mode raisonneur, le modèle « pense » longuement (plusieurs milliers de tokens internes possibles) avant de formuler sa conclusion. Fenêtre contextuelle : identique (128k tokens), mais la réponse peut être beaucoup plus longue : ~32k tokens par défaut, extensible jusqu’à 64k tokens max pour inclure le raisonnement + la réponse. À noter : deepseek-reasoner n’accepte pas certains paramètres de variabilité comme temperature ou top_p (ils sont ignorés ou interdits en mode raisonneur, voir section paramètres) – ceci afin de garantir un raisonnement déterministe et cohérent.

En résumé, deepseek-chat est recommandé par défaut pour la plupart des échanges et générations de texte, tandis que deepseek-reasoner est à employer pour les requêtes particulièrement complexes ou critiques nécessitant une vérification interne par le modèle (calculs, déduction, code difficile, etc.). Les deux modèles ont le même tarif par token côté API, mais utiliser le mode raisonneur revient plus cher par requête car la réponse inclura le coût de la chaîne de raisonnement en plus du résultat final.

Exemple d’appel API simple – Ci-dessous, un exemple minimal en Python utilisant la bibliothèque OpenAI (compatible avec l’API DeepSeek) pour interroger le modèle par défaut deepseek-chat. On spécifie le point d’entrée API DeepSeek (api_base) et on envoie un message utilisateur ; la réponse du modèle est imprimée :

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "user", "content": "Bonjour, que sais-tu sur DeepSeek ?"}
    ],
)

print(response.choices[0].message.content)

Ce code appelle l’endpoint Chat Completions de DeepSeek via la base URL https://api.deepseek.com. Pour compatibilité OpenAI, https://api.deepseek.com/v1 peut aussi être utilisé, mais le “v1” n’a aucun lien avec la version du modèle.

Paramètres de génération principaux

L’API DeepSeek reprend les mêmes paramètres de génération que l’API OpenAI pour configurer la créativité, la longueur et le style des réponses. Les principaux paramètres utilisables (pour le modèle deepseek-chat) incluent :

• temperature – Valeur entre 0.0 et 2.0 (défaut 1.0) qui contrôle la part de randomness dans la génération. Une température basse (~0) rend les réponses plus déterministes (répétables, utiles pour du code ou des calculs) tandis qu’une température élevée (>1.2) produit des sorties plus variées ou créatives (rédaction libre, brainstorming). Recommandations DeepSeek : 0.0 pour le code/math, ~1.0 pour de l’analyse de données, ~1.3 pour la conversation générale ou la traduction, et jusqu’à 1.5 pour des tâches créatives (récit, poésie). (Note : en mode raisonneur, ce paramètre est ignoré, voir plus bas.)
• top_p – Fraction 0.0–1.0 (défaut 1.0) appliquant le nucléus sampling. Ce filtre considère uniquement les tokens les plus probables cumulant une probabilité p donnée. Par exemple, top_p=0.5 limite chaque génération aux tokens couvrant 50% de probabilité cumulée, excluant les continuations plus obscures. À 1.0, aucun filtre n’est appliqué (toutes les probabilités sont prises en compte). Réduire top_p peut rendre les réponses plus conservatrices et éviter certains dérapages, souvent utilisé comme alternative ou en complément à temperature. (Ignoré également en mode raisonneur.)
• max_tokens – Nombre maximal de tokens de sortie que le modèle peut générer. Par défaut, DeepSeek fixe des valeurs adaptées au modèle : ~4096 tokens pour deepseek-chat et ~32k pour deepseek-reasoner, mais vous pouvez augmenter ces limites jusqu’au maximum supporté (8192 et 65536 respectivement) selon vos besoins. Attention toutefois : un max_tokens très élevé peut entraîner des réponses très longues (coûts en tokens proportionnels) ou troncation de la réponse si le serveur coupe à la limite. Veillez à ajuster ce paramètre en fonction du format de sortie attendu (par ex. allouer suffisamment de tokens pour un objet JSON complet, voir section JSON Output). En mode raisonneur, notez que max_tokens couvre l’ensemble de la génération (raisonnement + réponse finale).
• presence_penalty et frequency_penalty – Coefficients (-2.0 à 2.0) influant sur la tendance du modèle à répéter ou non certains éléments dans sa réponse. Un frequency_penalty positif décourage la redondance (chaque occurrence répétée d’un token est pénalisée), tandis qu’un presence_penalty positif décourage la simple répétition d’idées déjà mentionnées. Utile pour obtenir des réponses plus diversifiées, ou au contraire en négatif pour forcer le modèle à revenir sur des éléments. (En mode raisonneur, ces paramètres sont sans effet).
• stop – Liste de séquences de texte où la génération s’arrêtera si rencontrées. Par exemple, fournir stop=["\nUser:"] pourrait stopper le modèle s’il commence à produire la prochaine question utilisateur. DeepSeek supporte ce paramètre pour contrôler finement la fin de réponse, tout comme l’API OpenAI (on peut fournir plusieurs délimiteurs de fin).

En pratique, deepseek-chat supporte pleinement tous ces réglages comme un GPT classique. En revanche, le mode raisonneur a des contraintes : pour deepseek-reasoner, la plupart des paramètres stochastiques sont désactivés ou interdits. DeepSeek a figé les valeurs aléatoires en thinking mode afin d’assurer une cohérence maximale du raisonnement d’une requête à l’autre. Concrètement :

• Sur deepseek-reasoner, définir temperature, top_p, presence_penalty ou frequency_penalty n’a aucun effet (les valeurs sont ignorées sans erreur).
• Tenter de définir des options de logprobs (logprobs, top_logprobs) produit une erreur 400/422 (paramètre invalide) et la requête échoue.
• Seuls les paramètres de longueur (max_tokens) et arrêts (stop) restent pertinents en mode raisonneur, ainsi que l’activation éventuelle de JSON Output ou Tool Calls (qui sont compatibles).

En somme, prévoyez deux configurations : une flexible avec ajustement de température/top_p pour deepseek-chat (afin d’affiner la créativité des réponses), et une plus déterministe pour deepseek-reasoner (pas de température) de façon à garantir des raisonnements reproductibles.

Mode raisonneur (“Thinking mode”) et reasoning_content

Le mode “thinking” de DeepSeek permet au modèle de générer une réflexion intermédiaire (souvent appelée Chain-of-Thought) avant de formuler sa réponse finale. Ce mode, activé par le modèle deepseek-reasoner, est précieux pour les problèmes complexes car il oblige l’IA à décomposer sa démarche en étapes logiques, améliorant généralement la fiabilité de la réponse. Deux approches permettent d’activer le mode raisonneur :

1. Choisir le modèle deepseek-reasoner dans la requête (model: "deepseek-reasoner"). C’est le moyen le plus simple : toute requête faite avec ce modèle retournera par défaut un champ de raisonnement.
2. Utiliser le paramètre thinking sur deepseek-chat : il est officiellement possible d’activer le thinking mode avec thinking={"type":"enabled"}. Avec le SDK OpenAI, ce paramètre se passe via extra_body. En pratique, deepseek-reasoner reste l’option la plus simple quand vous voulez un mode raisonneur dédié.

Lorsque le mode raisonneur est actif, la structure de la réponse de l’API change légèrement : en plus du contenu final normal, la réponse inclut un champ supplémentaire appelé reasoning_content qui contient tout le texte du raisonnement (non filtré) généré par le modèle. Ce champ se situe au même niveau que le champ content habituel dans l’objet message retourné. Concrètement, si vous examinez response.choices[0].message :

• message.content contient la réponse finale (destinée à l’utilisateur).
• message.reasoning_content contient la raisonnement complet du modèle (généralement un enchaînement d’étapes de pensée, calculs, recherches d’indices, etc.).

Le champ tool_calls peut également apparaître si le modèle a déclenché des outils pendant son raisonnement (voir section Tool Calls). Voici un exemple d’appel en mode raisonneur et la façon de lire les deux contenus :

# Exemple: question mathématique simple en mode raisonneur
messages = [{"role": "user", "content": "9.11 et 9.8, lequel est plus grand ?"}]
response = client.chat.completions.create(
    model="deepseek-reasoner",
    messages=messages
)
reasoning = response.choices[0].message.reasoning_content
answer = response.choices[0].message.content
print("Raisonnement interne :\n", reasoning)
print("Réponse finale :\n", answer)

Dans cet exemple, le modèle doit d’abord raisonner (par ex. comparer 9.11 et 9.8 numériquement), puis fournir la réponse correcte (« 9.8 est plus grand que 9.11 »). Le texte complet du raisonnement interne sera disponible dans reasoning_content, tandis que la conclusion finale apparaîtra dans content.

Important : en conversation multi-tour classique, n’incluez pas le reasoning_content du tour précédent dans les messages du tour suivant. Il faut uniquement transmettre le contenu final avec le rôle assistant. Le raisonnement intermédiaire est conçu comme une étape transitoire : DeepSeek ne s’attend pas à recevoir ses propres chaînes de pensée en entrée, et cela peut alourdir inutilement le contexte sans améliorer la qualité des réponses.

En revanche, dans un flux utilisant le thinking mode avec des Tool Calls au sein d’une même requête, il peut être nécessaire de conserver temporairement le reasoning_content pendant les sous-tours internes (tool → réponse → tool…). Ce contenu doit ensuite être supprimé lorsqu’un nouveau message utilisateur démarre un nouveau tour de conversation.

L’illustration suivante résume la bonne pratique :

• Tour 1: Utilisateur -> (modèle réfléchit) -> Assistant (réponse + reasoning_content)
• Tour 2: On ajoute dans l’historique uniquement le message Assistant final (sans le reasoning), puis le nouvel utilisateur, etc..

Le mode raisonneur est donc particulièrement utile pour auditer ou expliquer la réponse du modèle. Par exemple, en cas de doute sur l’exactitude d’une réponse, vous pouvez regarder reasoning_content pour voir d’où pourrait venir l’erreur logique ou la mauvaise supposition. Certaines intégrations exploitent même ce champ pour afficher un « pas-à-pas » à l’utilisateur ou pour vérifier factuellement chaque étape. Notez toutefois que le raisonnement n’est pas garanti 100% fiable non plus – il peut contenir des digressions ou des calculs faux – mais il donne de la visibilité sur le processus. Enfin, comme mentionné précédemment, ce mode impose une certaine rigidité (pas de température aléatoire) pour privilégier la répétabilité du chain-of-thought.

Streaming en mode raisonneur : l’API DeepSeek supporte le streaming des tokens en temps réel même pour le reasoning. Dans ce cas, chaque chunk de données reçu peut contenir soit un segment du reasoning_content soit du content final. Le JSON partiel indique ces distinctions via un objet delta. Il faut donc agréger séparément les deux flux. Par exemple, en Python :

response = client.chat.completions.create(model="deepseek-reasoner", messages=messages, stream=True)
reasoning_content = ""
final_answer = ""
for chunk in response:
    delta = chunk.choices[0].delta
    if hasattr(delta, "reasoning_content"):
        reasoning_content += delta.reasoning_content
    elif hasattr(delta, "content"):
        final_answer += delta.content

Ce pseudocode lit chaque fragment renvoyé : si le fragment contient un bout de raisonnement (delta.reasoning_content), on l’accumule dans la variable de raisonnement, sinon on ajoute les tokens dans la variable de réponse finale. À la fin du streaming, on reconstitue ainsi les deux chaînes complètes. (Voir aussi [le guide officiel DeepSeek sur le Thinking mode pour l’exemple complet].)

Sortie JSON structurée (fonctionnalité JSON Output)

Il est courant de vouloir que le modèle renvoie un objet JSON valide au lieu d’une réponse textuelle libre, afin de faciliter le parsing automatique et l’exploitation par un programme. Bien qu’il soit toujours possible d’“instruire” le modèle dans le prompt à répondre en JSON, DeepSeek propose une fonctionnalité dédiée appelée JSON Output pour fiabiliser ce procédé. Lorsqu’elle est activée, le modèle garantit (autant que possible) que sa réponse sera un JSON bien formé.

Pour utiliser la sortie JSON structurée :

• Incluez le paramètre spécial response_format dans votre requête, avec la valeur {'type': 'json_object'}. Ceci indique au serveur DeepSeek que vous souhaitez un résultat JSON.
• Guidez le modèle via le prompt : il est recommandé de mentionner le mot « JSON » dans l’instruction système ou utilisateur, et de fournir un exemple de format attendu dans le prompt pour mettre le modèle sur la bonne voie. Par exemple, vous pouvez donner un exemple d’entrée et la structure JSON de sortie correspondante (voir ci-dessous).
• Ajustez max_tokens en conséquence : la réponse JSON pouvant être volumineuse, assurez-vous que la limite de tokens est suffisante pour contenir l’objet entier, sans quoi vous risquez une troncation du JSON.

Exemple : Supposons qu’on veuille extraire en JSON la question et la réponse d’une phrase d’examen. On peut construire le prompt suivant :

system_prompt = """Tu es un assistant qui renvoie du JSON.
L’utilisateur fournira un texte d’examen. Extrait la "question" et la "réponse" en format JSON.EXEMPLE ENTRÉE :
Quel est le plus haut sommet du monde ? Mont Everest.EXEMPLE SORTIE JSON :
{
    "question": "Quel est le plus haut sommet du monde ?",
    "answer": "Mont Everest"
}"""
user_input = "Quel est le fleuve le plus long du monde ? Le Nil."
messages = [
    {"role": "system", "content": system_prompt},
    {"role": "user", "content": user_input}
]
response = client.chat.completions.create(
    model="deepseek-chat",
    messages=messages,
    response_format={"type": "json_object"}
)
json_str = response.choices[0].message.content
data = json.loads(json_str)
print(data["question"], "->", data["answer"])

Dans cet exemple, on informe clairement le modèle (rôle système) qu’il doit répondre en JSON et on lui fournit un exemple de la forme voulue. Le paramètre response_format enclenche le mode JSON Output côté API. La réponse retournée par DeepSeek pourrait ressembler à :

{
    "question": "Quel est le fleuve le plus long du monde ?",
    "answer": "Le Nil"
}

que l’on peut charger avec json.loads en Python pour obtention du dict Python.

Limitations connues : bien que cette fonctionnalité améliore la fiabilité, l’API peut parfois retourner un contenu vide (chaîne vide) au lieu du JSON attendu. DeepSeek recommande également de guider explicitement le modèle en mentionnant le mot « JSON » dans le prompt et en fournissant un exemple clair du format souhaité.

Sans instruction explicite, le modèle peut produire une sortie composée de whitespace (espaces ou lignes vides) jusqu’à la limite de tokens, donnant l’impression qu’aucune réponse n’est générée. Ce comportement est connu et peut être évité avec un prompt bien structuré.

En pratique, il est recommandé de : (1) inclure une instruction explicite pour produire du JSON, (2) fournir un exemple du schéma attendu, (3) définir un max_tokens suffisant pour éviter toute troncation, et (4) implémenter côté client une vérification robuste du JSON (try/except) avec éventuellement une stratégie de retry en cas d’échec ou de réponse vide.

Enfin, veillez à toujours demander un objet JSON unique (type dictionnaire) comme racine. Le paramètre response_format={"type":"json_object"} attend un objet, et non un tableau. Si votre cas d’usage nécessite une liste de résultats, encapsulez-la dans un champ d’un objet JSON.

Appels d’outils externes (Tool Calls) et mode strict

Une des fonctionnalités puissantes de DeepSeek est sa capacité à appeler des outils externes durant la génération. Cela équivaut aux “fonctions” de l’API OpenAI (fonctions qu’un modèle peut invoquer pour obtenir des informations supplémentaires). Dans le contexte DeepSeek, on parle de Tool Calls : le modèle peut décider de sortir de la conversation pour appeler un outil (fonction prédéfinie par le développeur) puis reprendre le fil avec le résultat de cet outil. Cela permet par exemple de consulter une base de connaissances, d’effectuer un calcul, une requête API tierce, etc., en étendant les capacités du modèle.

Définition des outils : Pour utiliser cette fonction, on doit fournir à l’appel API un paramètre tools qui est une liste de descriptions de fonctions utilisables. Chaque entrée est un objet JSON décrivant un outil avec notamment :

• name : nom de la fonction (utilisé par le modèle pour le référencer).
• description : courte explication de ce que fait la fonction (pour orienter le modèle).
• parameters : schéma JSON de paramètres attendus (type, champs requis, etc. conforme au JSON Schema).

Exemple simplifié : imaginons une fonction get_weather(location) qui fournit la météo pour une ville donnée. On la décrit ainsi :

tools = [
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Donne la météo actuelle pour une ville donnée.",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "Ville et pays, ex: Paris, France"
          }
        },
        "required": ["location"]
      }
    }
  }
]

On passe ensuite tools=tools dans la requête ChatCompletion.create(...) avec par exemple la question utilisateur « Quel temps fait-il à Paris ? ». Le modèle, grâce à la description fournie, peut choisir de retourner un appel d’outil plutôt qu’une réponse directe. Concrètement, la réponse de l’API aura alors un champ tool_calls contenant un objet du type : « veut appeler la fonction get_weather avec tel paramètre ».

Flux d’exécution : Reprenons l’exemple météo. Le modèle reçoit la question « How’s the weather in Hangzhou, Zhejiang? ». Au lieu de répondre « Il fait 24°C », il peut décider qu’il a besoin de l’outil. La réponse initiale du modèle n’aura donc pas de content final, mais dans message.tool_calls[0] on trouvera par ex. :

"tool_calls": [
  {
    "id": "call_xxx",
    "type": "function",
    "function": {
      "name": "get_weather",
      "arguments": "{\"location\":\"Hangzhou, Zhejiang\"}"
    }
  }
]

Ici, le modèle demande à exécuter get_weather("Hangzhou, Zhejiang"). C’est ensuite à l’application cliente d’effectuer réellement cet appel (par ex. via une API météo) et de récupérer un résultat (ex: « 24°C, ciel clair »). Une fois le résultat obtenu, on l’envoie au modèle via un nouveau message de rôle spécial "tool" (équivalent du rôle function côté OpenAI) : ce message doit contenir "tool_call_id": <id> identique à celui du tool_calls originel, et le content contenant la sortie de la fonction. Dans notre cas :

import json

tool = response.choices[0].message.tool_calls[0]

messages.append(response.choices[0].message)

args = json.loads(tool.function.arguments)

weather_result = call_weather_api(args["location"])

messages.append({
    "role": "tool",
    "tool_call_id": tool.id,
    "content": weather_result  # ex: "24℃, ciel clair"
})

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=messages,
    tools=tools,
)

print("Assistant:", response.choices[0].message.content)

Au second appel, le modèle reçoit donc en contexte sa propre demande d’outil suivie de la réponse de l’outil, et peut dès lors produire la réponse finale à l’utilisateur en intégrant l’information (« Il fait 24°C et le ciel est clair à Hangzhou. »). Ce schéma correspond à un aller-retour typique Question -> Tool -> Answer. On peut enchaîner plusieurs appels d’outils dans la même conversation si nécessaire (le modèle pourrait par ex. appeler un autre outil après, tant qu’on lui fournit les réponses intermédiaires avec le bon rôle).

Note : le modèle n’exécute pas lui-même l’outil – il ne fait que formuler l’intention d’appel. C’est au développeur d’implémenter chaque fonction et d’insérer son résultat. Si aucun outil n’est pertinent, le modèle fournira directement une réponse normale dans content.

À partir de DeepSeek-V3.2, l’API prend en charge les Tool Calls en mode non-thinking et en thinking mode, les deux modes peuvent utiliser des outils. En thinking mode, le raisonnement reasoning_content peut lui-même décrire la décision d’appeler un outil, ce qui transparaîtra dans la sortie.

Mode strict (beta) : Un problème possible lors d’appels d’outils est que le modèle ne respecte pas exactement le schéma de paramètres (ex : il oublie un champ requis, ou produit un JSON mal formé pour l’appel). Pour pallier cela, DeepSeek offre un mode strict où le serveur valide la conformité du JSON de l’outil avant de le retourner. Si le modèle commet une erreur de format, l’appel est rejeté (générant probablement une erreur 422). Pour activer ce mode :

1. Utilisez l’endpoint beta de l’API comme base URL : https://api.deepseek.com/beta . (Le mode strict est pour l’instant en bêta sur un endpoint distinct.)
2. Dans chaque définition de fonction de votre liste tools, ajoutez "strict": true au même niveau que name/description.
3. Assurez-vous que vos schémas JSON respectent les contraintes du mode strict : par ex, tous les champs object doivent spécifier additionalProperties: false et avoir des required exhaustifs, En strict mode, DeepSeek prend notamment en charge object, string, number, integer, boolean, array, enum et anyOf. Pour les chaînes, pattern et format sont pris en charge, tandis que minLength et maxLength ne le sont pas.

Le mode strict permet de s’assurer que les appels d’outils du modèle seront toujours bien formés et conformes à vos attentes. Par exemple, si un champ requis manque, le modèle sera forcé de le fournir ou échouera. Les types de schéma supportés en strict incluent les objets, string, number, boolean, array, enum de valeurs, et combinaisons anyOf simples. Cette fonctionnalité ajoute une robustesse appréciable lorsque l’API est utilisée en production avec des outils critiques.

Erreurs courantes avec Tool Calls : Quelques points d’attention pour éviter des erreurs :

• Oublier d’envoyer le résultat d’un outil : si le modèle appelle un outil et que vous ne renvoyez pas de message de rôle tool avec le résultat, la conversation restera incomplète. Toujours détecter les tool_calls et y répondre pour permettre au modèle de conclure.
• Mismatch d’identifiant : assurez-vous de renvoyer exactement le même tool_call_id que fourni. L’API utilise cet id pour associer la réponse outil à la demande correspondante.
• Correspondance des rôles : après un Tool Call, renvoyez le résultat via un message avec role: « tool » et le champ tool_call_id correspondant à l’identifiant de l’appel d’outil renvoyé par le modèle. En pratique, conservez le message assistant contenant tool_calls dans l’historique, puis ajoutez un message tool avec le résultat de votre fonction. Respecter exactement ce format est important pour éviter une erreur 400 (Invalid Format).
• Sortie de l’outil trop verbeuse : idéalement, retournez juste les données brutes dont le modèle a besoin, sans phrases inutiles, pour éviter de polluer la réponse finale.
• Utilisation du mode strict : n’oubliez pas de passer par l’URL beta et de bien mettre strict=true sur chaque outil sinon le strict mode ne s’enclenchera pas. En mode strict, une erreur « schema not supported » indique souvent un champ manquant additionalProperties: false ou un type non supporté.

Cache de contexte : principe et bénéfices

DeepSeek a introduit mi-2024 une optimisation nommée Context Caching (mise en cache de contexte) pour réduire les coûts et accélérer les requêtes répétitives. Le principe : si plusieurs appels successifs contiennent une même portion de contexte au début (par exemple toujours la même consigne système ou le même document), cette portion n’a pas besoin d’être recalculée à chaque fois par le modèle. L’API DeepSeek va alors détecter le préfixe commun et le traiter via un cache disque plutôt que de tout recalculer. Concrètement :

• Cache automatique : ce mécanisme est activé par défaut pour tous les utilisateurs, sans configuration spécifique. Le Context Caching de DeepSeek repose sur la réutilisation des préfixes communs entre plusieurs requêtes. Lorsqu’une requête partage un début identique (préfixe) avec une requête précédente, cette portion peut être traitée comme un cache-hit et réutilisée via un hard disk cache, sans être recalculée entièrement.
• En pratique, seuls les préfixes suffisamment longs (environ 64 tokens ou plus) sont concernés. Si une requête ultérieure reprend exactement ce même début, le serveur réutilise ce préfixe déjà traité, ce qui réduit le coût des tokens d’entrée et améliore l’efficacité globale des requêtes.
• Détection du préfixe : Seul le préfixe commun compte. Par exemple, si vous posez deux questions différentes sur un même long texte, tout le passage de texte répété sera mis en cache lors de la première requête, puis réutilisé lors de la seconde. De même, en conversation multi-tours, les premiers messages (système + 1ère question) peuvent servir de base de cache pour les tours suivants. En revanche, si vous changez complètement de sujet ou modifiez le prompt initial, le cache ne s’appliquera pas (cache miss).
• Exemples :
  • Cas 1 : Long texte identique, question différente – Vous envoyez un rapport financier de 50 pages dans le message utilisateur suivi d’une demande de résumé (requête 1). Puis vous renvoyez le même rapport suivi d’une question sur la profitabilité (requête 2). Le rapport étant identique dans les deux cas (préfixe commun), la deuxième requête sera en grande partie servie par le cache, évitant de repayer l’analyse complète du texte.
  • Cas 2 : Conversation multi-tours – Tour 1 : vous posez une question, le modèle répond. Tour 2 : vous reprenez l’historique complet (système + Q1 + R1) plus votre nouvelle question. Le préfixe (système + Q1 + R1) est commun à la requête précédente, donc cette partie sera un cache hit et seul la nouvelle question est traitée “à neuf”.
  • Cas 3 : Few-shot prompts – Vous avez un prompt très long avec plusieurs exemples (few-shot) que vous conservez constant, et seul la dernière question change. Là encore, tout le bloc d’exemples sera mis en cache lors du premier appel, et les suivants bénéficieront d’un coût fortement réduit sur cette partie redondante.
• Impact sur la facturation : L’API facture les tokens d’entrée bien moins cher en cas de cache hit. En cas de cache-hit, les tokens d’entrée sont fortement moins chers que les cache-miss, selon la page officielle Models & Pricing. Les tokens de sortie, eux, sont toujours facturés au tarif normal (0,42 $ par million environ). DeepSeek ajoute dans la réponse deux champs d’usage : prompt_cache_hit_tokens et prompt_cache_miss_tokens pour indiquer le nombre de tokens entrée ayant bénéficié du cache vs calculés normalement. Vous pouvez consulter ces valeurs si besoin pour monitorer l’efficacité du cache.
• Bonnes pratiques : Le cache de contexte profite surtout aux scénarios où on réutilise beaucoup de texte identique. Pour en tirer parti :
  • Structurez vos appels de manière à répéter les instructions invariantes (ex : toujours renvoyer le même système prompt contenant les règles du jeu de rôle de l’IA, plutôt que de le reformuler à chaque fois).
  • En exploitation, essayez de regrouper les requêtes sur un même gros document au lieu d’alterner constamment avec d’autres contextes (ainsi le document reste chaud dans le cache).
  • Pour le few-shot learning, n’hésitez pas à inclure plusieurs exemples si nécessaires : le coût initial sera plus élevé, mais grâce au cache, les appels suivants amortiront ce coût.
  • Sachez qu’un cache hit n’accélère pas forcément la réponse de façon visible (la latence dépend aussi du calcul de sortie), mais il réduit le travail côté serveur et donc améliore la scalabilité globale.
  • Ne comptez pas à 100% sur le cache pour chaque token : DeepSeek précise que c’est un système best-effort, sans garantie de hit systématique (le cache peut être évincé au bout de quelques heures/jours). Mais en pratique sur des requêtes rapprochées le taux de hit est élevé.

En résumé, le context caching est une optimisation transparente qui diminue le coût des requêtes redondantes. C’est particulièrement utile pour les applications traitant des documents longs en plusieurs fois, ou les agents conversationnels qui rappellent souvent le même contexte. Cette optimisation réduit fortement le coût des entrées répétées grâce au cache-hit. Le context caching réduit surtout le coût des segments d’entrée réutilisés. Toute comparaison chiffrée avec un autre fournisseur doit être présentée dans une section distincte, sourcée et datée.

(Note : le cache ne stocke rien en deçà de ~64 tokens, donc les prompts minuscules ne sont pas concernés. De plus, la cache ne rend pas le modèle déterministe : la sortie reste recalculée à chaque fois et peut varier si de la stochasticité est en jeu.)

Streaming des réponses en temps réel

Comme l’API OpenAI, l’API DeepSeek permet de recevoir la réponse en streaming plutôt qu’en une fois à la fin. En passant stream=true dans la requête, le serveur envoie des morceaux de réponse au fur et à mesure de leur génération, ce qui est idéal pour afficher un texte qui se déroule en direct dans une interface utilisateur. Le streaming fonctionne aussi bien en mode chat normal qu’en mode raisonneur (avec la nuance vue plus haut qu’il faut reconstituer potentiellement deux flux de texte).

Techniquement, DeepSeek utilise le même format de Server-Sent Events (SSE) que l’API OpenAI. Chaque chunk de réponse est envoyé sous forme de ligne JSON préfixée par data:, et la fin du stream est marquée par un message [DONE]. Cela signifie que vous pouvez utiliser les mêmes outils ou bibliothèques que pour GPT : par exemple, en Python, itérer directement sur l’objet retourné (comme dans l’exemple plus haut), ou en JavaScript utiliser un EventSource pour lire le flux SSE.

Exemple d’intégration front (JS) : Voici un exemple simplifié en JavaScript côté navigateur pour appeler l’API DeepSeek en streaming via fetch et lire les données progressivement :

const response = await fetch("/api/deepseek-stream", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    message: "Donne-moi un conseil en Go (le jeu)."
  })
});

if (!response.ok || !response.body) {
  throw new Error("Streaming response unavailable");
}

const reader = response.body.getReader();
const decoder = new TextDecoder("utf-8");

let buffer = "";
let partialText = "";

while (true) {
  const { value, done } = await reader.read();
  if (done) break;

  buffer += decoder.decode(value, { stream: true });

  const lines = buffer.split("\n");
  buffer = lines.pop() || "";

  for (const line of lines) {
    const trimmed = line.trim();

    if (!trimmed) continue;
    if (trimmed.startsWith(":")) continue; // ignore SSE keep-alive comments
    if (!trimmed.startsWith("data:")) continue;

    const data = trimmed.slice(5).trim();

    if (data === "[DONE]") {
      break;
    }

    try {
      const json = JSON.parse(data);
      const delta = json.choices?.[0]?.delta?.content || "";
      if (delta) {
        partialText += delta;
        updateUI(partialText);
      }
    } catch (err) {
      // Ignore malformed partial lines and continue
      console.error("Failed to parse SSE chunk:", err);
    }
  }
}

(Note : pour extraire correctement le texte, il faut parser chaque data: reçu en excluant les éventuels commentaires SSE comme : keep-alive.)

Back-End :

import express from "express";

const app = express();
app.use(express.json());

app.post("/api/deepseek-stream", async (req, res) => {
  const message = req.body?.message || "Bonjour !";

  const upstream = await fetch("https://api.deepseek.com/chat/completions", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.DEEPSEEK_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "deepseek-chat",
      stream: true,
      messages: [
        { role: "user", content: message }
      ]
    })
  });

  if (!upstream.ok || !upstream.body) {
    const errorText = await upstream.text();
    res.status(upstream.status).send(errorText);
    return;
  }

  res.setHeader("Content-Type", "text/event-stream; charset=utf-8");
  res.setHeader("Cache-Control", "no-cache, no-transform");
  res.setHeader("Connection", "keep-alive");

  const reader = upstream.body.getReader();

  try {
    while (true) {
      const { value, done } = await reader.read();
      if (done) break;
      res.write(value);
    }
  } finally {
    res.end();
  }
});

app.listen(3000);

DeepSeek envoie régulièrement des lignes de keep-alive pendant le stream pour garder la connexion ouverte en cas de latence. Si vous utilisez le SDK OpenAI, il gère ces lignes automatiquement (elles sont ignorées). En implémentation manuelle, il faudra filtrer les lignes commençant par : qui sont des commentaires SSE (et éventuellement les lignes vides). Ces lignes n’affectent pas le JSON de données et peuvent être simplement ignorées lors du parsing.

En termes d’UX, le streaming apporte un réel confort : l’utilisateur voit la réponse se construire et perçoit moins l’attente, surtout pour des réponses longues. Assurez-vous néanmoins de gérer correctement la fin du stream ([DONE]) pour éviter de laisser un indicateur de chargement activé indéfiniment. De plus, si vous combinez streaming et reasoning mode, vous pouvez choisir d’afficher ou non le raisonnement en direct (peut-être dans une fenêtre cachée réservée aux admins ou debug). La plupart du temps, pour un utilisateur final, on ne montrera que la réponse finale en train d’apparaître progressivement.

Enfin, sachez que le streaming n’accélère pas la génération elle-même (le temps total pour générer X tokens reste similaire), mais il améliore la perception de rapidité. En cas de forte charge serveur, DeepSeek peut retarder légèrement l’envoi tout en maintenant la connexion avec des keep-alive SSE. Et au-delà de 10 minutes sans début de génération, la connexion sera coupée d’office. Ces détails sont identiques à OpenAI, d’où une intégration très similaire.

Compatibilité avec l’API d’Anthropic

Pour les développeurs qui utilisent déjà l’API d’Anthropic (Claude) ou ses SDK, DeepSeek a mis en place une compatibilité spécifique qui permet de brancher DeepSeek à la place de Claude avec un minimum de modifications. En pratique, DeepSeek expose un endpoint dédié qui parle le même format JSON que l’API Anthropic, de sorte qu’un client conçu pour Claude peut interroger DeepSeek sans tout recoder.

Mise en place (exemple SDK Anthropic) : Supposons que vous utilisiez le SDK officiel Anthropic en Python ou Claude-Next en Node. Il suffit de configurer les variables suivantes :

• ANTHROPIC_BASE_URL = "https://api.deepseek.com/anthropic"
• ANTHROPIC_API_KEY = <Votre_clé_API_DeepSeek> (le token DeepSeek servira de clé Anthropic).

Ensuite, lorsqu’au lieu d’appeler un modèle "claude-v1" ou autre, vous spécifiez "model": "deepseek-chat" (ou "deepseek-reasoner"), l’appel sera redirigé vers DeepSeek. Tout le reste (structure des messages, etc.) peut rester identique. Par exemple avec le SDK Anthropic JS :

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="deepseek-chat",
    max_tokens=1000,
    system="You are a helpful assistant.",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Hi, how are you?"}
            ]
        }
    ],
)

print(message.content)

Ici on utilise un prompt formaté façon Anthropic, mais avec le model deepseek-chat. DeepSeek va intercepter cet appel sur son endpoint /anthropic et répondre comme le ferait Claude. Si on fournit un nom de modèle non supporté, DeepSeek le remappe automatiquement sur deepseek-chat par défaut.

La compatibilité annoncée couvre :

• Les entêtes Anthropic standards (x-api-key supporté).
• Les champs principaux de la requête : model, max_tokens, stop_sequences, stream, temperature (0–2), etc. sont pris en charge. Dans la compatibilité Anthropic, le champ thinking est pris en charge, mais budget_tokens est ignoré.
• La structure des messages : les rôles human/assistant version Anthropic (ou via la clé messages du SDK) sont mappés correctement vers DeepSeek. Dans le format Anthropic compatible, DeepSeek prend en charge content string et array/type= »text ». En revanche, array/type= »image », « document » et « search_result » ne sont pas pris en charge.
• Les outils : Anthropic a sa façon de définir des « plugins » (outil web search, etc.). DeepSeek prend en charge les champs équivalents pour tools et renvoie des tool_use et tool_result semblables dans le format de message. La compatibilité n’est pas totale (certains types de messages comme search_result ne s’appliquent pas) mais suffira pour beaucoup de cas.

En bref, si vous avez déjà du code qui appelle Claude (Anthropic) et que vous souhaitez tester DeepSeek à la place, il vous suffit de changer l’URL et la clé. Cette interopérabilité facilite l’adoption de DeepSeek en le rendant plug-and-play dans l’écosystème Anthropic, de même que la compatibilité OpenAI le rend plug-and-play dans l’écosystème GPT. Cela témoigne de la volonté de DeepSeek de s’insérer facilement dans les projets existants.

(Remarque : la compatibilité anthropic reste un ajout pratique. Pour exploiter au maximum les spécificités DeepSeek, l’API OpenAI-like reste plus complète, car elle expose directement le mode raisonneur via deepseek-reasoner, etc. Mais pour un remplacement rapide de backend IA, le mode anthropic est parfait.)

Gestion des erreurs, retries et fallback

Aucun développeur n’aime voir ses appels échouer, mais cela arrive ! La DeepSeek API renvoie des codes d’erreur HTTP avec des messages explicatifs en cas de problème. Voici les principaux codes à connaître et comment les gérer :

• 400 – Bad Request (Invalid Format) : la requête est mal formée ou un champ requis manque. Par ex, un JSON mal structuré, un messages mal construit, un paramètre de travers. La réponse comprend souvent un message JSON indiquant l’erreur précise. Solution : vérifiez le format selon la doc et corrigez le JSON d’envoi. En dev, loggez la réponse d’erreur pour trouver la cause exacte.
• 401 – Authentication Fails : la clé API est absente ou invalide (mauvaise clé, compte supprimé, etc.). Solution : double-check de la clé (Authorization: Bearer). Si vous n’avez pas de clé, [créez-en une sur le portail DeepSeek]. En production, surveillez l’expiration de clé ou la désactivation éventuelle du compte.
• 402 – Insufficient Balance : vous n’avez plus de crédits. DeepSeek fonctionne sur un système prépayé : il faut créditer votre compte (pas de quota gratuit illimité). Solution : allez sur la page de top-up pour ajouter des fonds. Vous pouvez suivre votre consommation de tokens pour anticiper cette erreur. En attendant le rechargement, vos appels échoueront tous sur 402.
• 422 – Invalid Parameters : proche du 400, signifie qu’un paramètre fourni est invalide ou non supporté. Ex : vous avez peut-être mis logprobs sur deepseek-reasoner (param non supporté, entraîne une erreur), ou un champ d’outil strict non conforme. Solution : se référer au message d’erreur et à la doc pour ajuster les paramètres. Cette erreur apparaît aussi si vous dépassez certaines limites (ex: max_tokens trop grand).
• 429 – Rate Limit Reached : vous envoyez trop de requêtes rapidement. Officiellement, DeepSeek n’impose pas de limite fixe de requêtes par minute, mais en pratique si vous bombardez de requêtes, vous pouvez recevoir un 429. Cela indique que le service vous throttle temporairement. Solutions : implémentez une attente exponentielle avant retry (ex: attendre 1s, puis 2s, etc.), ou réduisez la cadence d’appel. Dans son message d’erreur, DeepSeek suggère même de basculer sur une API LLM alternative (OpenAI) en attendant si votre application le permet – c’est une sorte de “fallback” possible si DeepSeek est saturé. En tous les cas, ne spammez pas en boucle en cas de 429, cela risquerait d’aggraver la situation côté serveur et côté blocage.
• 500 – Server Error : une erreur inattendue côté serveur DeepSeek. Cela peut arriver si le modèle plante ou autre. Solution : attendez quelques secondes et retentez. Ces erreurs sont généralement transitoires. Surveillez la récurrence : si un 500 persistant survient sur une requête spécifique, il se peut que le prompt en cause révèle un bug (ex: une séquence de tokens que le modèle ne gère pas). Vous pouvez essayer de modifier légèrement le prompt pour contourner, et remonter le cas à DeepSeek si besoin.
• 503 – Service Unavailable (Server Overloaded) : le service est surchargé ou en maintenance. Solution : là aussi, patienter et retenter plus tard. Vous pouvez consulter la page statut officielle pour voir si une panne ou un pic de charge est connu. Implémentez une stratégie de repli : par exemple, si vos appels critiques tombent régulièrement en 503 aux heures de pointe, envisagez de prévoir un backup (ex: basculer sur un autre modèle open-source local temporairement, ou sur OpenAI) pour assurer la continuité de service. DeepSeek étant encore jeune, il peut y avoir des moments de saturation – leur infrastructure s’améliore constamment, mais mieux vaut prévenir en ayant un plan B pour les usages en production critique.

Stratégies de retry/fallback : Pour une application robuste, encapsulez vos appels dans une logique de retry sur les codes récupérables (429, 500, 503). Par exemple :

import time

MAX_RETRIES = 3

for attempt in range(MAX_RETRIES):
    try:
        response = client.chat.completions.create(
            model="deepseek-chat",
            messages=[{"role": "user", "content": "Bonjour"}],
            timeout=15,
        )
        break
    except Exception as e:
        error_text = str(e)

        if "429" in error_text or "503" in error_text:
            wait = (2 ** attempt) * 1.5
            time.sleep(wait)
            continue

        raise

(Pseudo-code illustratif – adapter selon le SDK utilisé et la manière dont il expose les erreurs.)

Au-delà d’un certain nombre d’échecs consécutifs, loggez l’erreur, alertez, et éventuellement tentez un fallback : par exemple, basculer sur un autre modèle si disponible (OpenAI GPT-3.5/GPT-4 via leur API, ou un modèle local plus simple). DeepSeek le suggère pour le 429, et c’est en effet une bonne pratique si vos utilisateurs ne doivent pas subir d’interruption.

Enfin, si vous rencontrez beaucoup d’erreurs 500/503 sur DeepSeek, n’hésitez pas à en informer l’équipe via Discord ou support, et en attendant réduisez la charge de votre côté (par ex., limitez la taille des prompts ou la fréquence). Heureusement, DeepSeek a montré une assez bonne stabilité et un coût bien inférieur aux alternatives, ce qui compense ces quelques aléas en 2025-2026. Avec des stratégies adéquates de gestion d’erreurs, vous pourrez offrir une expérience utilisateur fluide tout en profitant des avantages de cette API émergente.

FAQ technique (DeepSeek API)

Sources officielles

• DeepSeek API Docs – Thinking Mode (Documentation officielle du mode raisonneur)
• DeepSeek API Docs – JSON Output (Sortie JSON structurée)
• DeepSeek API Docs – Tool Calls (Appels d’outils externes)
• DeepSeek API Docs – Context Caching (Mise en cache de contexte)
• DeepSeek API Docs – Anthropic API (Compatibilité avec API Claude)
• DeepSeek API Docs – Error Codes (Liste des codes d’erreur & solutions)
• DeepSeek API – Models & Pricing (Détails modèles V3.2 et tarifs tokens)