API DeepSeek en français : guide complet avec Python, Node.js et cURL

L’API DeepSeek permet d’appeler deepseek-v4-flash et deepseek-v4-pro depuis un serveur, un script ou une application. Elle accepte le format OpenAI Chat Completions à l’adresse https://api.deepseek.com et le format Anthropic à l’adresse https://api.deepseek.com/anthropic. Ce guide utilise exclusivement les identifiants V4 actuellement documentés.

Sommaire

• Modèles et endpoints actuels
• Premier appel avec cURL, Python et Node.js
• Thinking et Non-Thinking
• Paramètres importants
• Conversation multi-tour et sens de « stateless »
• JSON Output
• Tool Calls
• Streaming
• Cache de contexte et mesure des tokens
• FIM et fonctions Beta
• Limites de concurrence et erreurs
• Sécurité et données personnelles
• FAQ

Modèles et endpoints actuels

Élément	Valeur actuelle vérifiée
Modèles Chat Completions	deepseek-v4-flash et deepseek-v4-pro
Base URL, format OpenAI	https://api.deepseek.com
Base URL, format Anthropic	https://api.deepseek.com/anthropic
Chat Completions	POST /chat/completions
Liste des modèles	GET /models
Authentification	Authorization: Bearer VOTRE_CLE
Fenêtre de contexte	1M tokens pour Flash et Pro
Sortie Chat Completions	jusqu’à 384K tokens, sous réserve de la longueur totale du contexte

DeepSeek décrit son interface comme compatible avec les formats OpenAI et Anthropic. Cela permet de réutiliser leurs SDK en changeant la clé, la base URL et le modèle. Cette compatibilité ne signifie pas que chaque endpoint ou chaque paramètre de ces fournisseurs existe chez DeepSeek. Le périmètre vérifié ici est Chat Completions, ainsi que les fonctions explicitement documentées par DeepSeek.

L’annonce de V4 précisait que deepseek-chat et deepseek-reasoner seraient entièrement retirés et inaccessibles après le 24 juillet 2026 à 15 h 59 UTC. Certaines pages Quick Start conservent encore une note rédigée au futur, mais l’exemple actuel de GET /models ne présente que les deux identifiants V4. Pour un code maintenable, utilisez directement Flash ou Pro.

Premier appel à l’API DeepSeek

1. Créer et protéger la clé API

Créez la clé depuis la plateforme DeepSeek. Conservez-la dans une variable d’environnement ou un gestionnaire de secrets. Ne l’insérez jamais dans du JavaScript exécuté par le navigateur, une application mobile distribuée, un dépôt Git ou une capture d’écran.

export DEEPSEEK_API_KEY="votre_cle_api"

2. Exemple cURL

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {
        "role": "system",
        "content": "Réponds clairement en français."
      },
      {
        "role": "user",
        "content": "Résume les avantages et les limites du cache de contexte."
      }
    ],
    "thinking": {"type": "disabled"},
    "stream": false
  }'

3. Exemple Python

python -m pip install --upgrade openai

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-v4-pro",
    messages=[
        {"role": "system", "content": "Réponds en français et signale toute incertitude."},
        {"role": "user", "content": "Propose un plan de test pour une API de paiement."},
    ],
    reasoning_effort="high",
    extra_body={"thinking": {"type": "enabled"}},
)

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

4. Exemple Node.js

npm install openai

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseURL: "https://api.deepseek.com",
});

const response = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [
    { role: "system", content: "Réponds clairement en français." },
    { role: "user", content: "Transforme cette note en liste d’actions." },
  ],
  thinking: { type: "disabled" },
  stream: false,
});

console.log(response.choices[0].message.content);
console.log(response.usage);

Les exemples lisent la clé côté serveur. Si votre produit possède un frontend, faites transiter la demande par votre propre backend et appliquez authentification, quotas, contrôle des entrées et journalisation appropriée.

Thinking et Non-Thinking

Flash et Pro prennent en charge les deux modes. Le mode Thinking est activé par défaut. Désactivez-le explicitement pour une réponse directe, ou conservez-le pour les problèmes qui justifient un raisonnement plus important.

Besoin	Paramètres
Thinking standard	{"thinking":{"type":"enabled"}} et reasoning_effort="high"
Thinking maximal	{"thinking":{"type":"enabled"}} et reasoning_effort="max"
Réponse directe	{"thinking":{"type":"disabled"}}

DeepSeek documente high et max. Pour compatibilité, low et medium sont mappés vers high, tandis que xhigh est mappé vers max. Il est plus clair d’envoyer directement une valeur réellement prise en charge.

La réponse Thinking peut contenir reasoning_content en plus de content. Dans une conversation sans Tool Call, l’ancien reasoning_content n’a pas besoin d’être renvoyé. Lorsqu’un tour Thinking déclenche des outils, DeepSeek exige en revanche de renvoyer le reasoning_content de ce tour dans les requêtes suivantes de la boucle d’outils ; sinon l’API peut retourner une erreur 400.

Paramètres importants de Chat Completions

Paramètre	Rôle	Précaution
model	Choisit Flash ou Pro	Utiliser uniquement un identifiant retourné par GET /models.
messages	Historique composé des rôles system, user, assistant et tool	L’application doit renvoyer l’historique utile à chaque tour.
thinking	Active ou désactive Thinking	Thinking est activé par défaut.
reasoning_effort	Effort high ou max	Disponible en mode Thinking.
max_tokens	Plafond de génération	Entrée et sortie doivent tenir ensemble dans le contexte.
stream	Active les événements SSE	Traiter les fragments et le marqueur [DONE].
response_format	Active notamment json_object	Demander aussi explicitement du JSON dans le prompt.
tools	Décrit les fonctions disponibles	Le modèle propose un appel ; votre code valide et exécute.
tool_choice	none, auto, required ou fonction imposée	Ne pas confondre choix d’outil et autorisation métier.
user_id	Isolation sécurité, KV cache et planification	Chaîne de 512 caractères maximum, sans donnée personnelle.

Conversation multi-tour : ce que signifie « stateless »

L’endpoint ne réinjecte pas automatiquement les tours précédents : votre application doit concaténer l’historique nécessaire et le transmettre dans messages à chaque requête. Cela ne décrit ni la journalisation, ni le cache disque, ni la durée de conservation des données par DeepSeek.

messages = [{"role": "user", "content": "Quelle est la capitale du Japon ?"}]

first = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=messages,
    extra_body={"thinking": {"type": "disabled"}},
)

messages.append(first.choices[0].message)
messages.append({"role": "user", "content": "Et combien d’habitants environ ?"})

second = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=messages,
    extra_body={"thinking": {"type": "disabled"}},
)

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

Pour éviter une croissance illimitée, conservez une fenêtre de messages pertinente, résumez l’ancien contexte si nécessaire et mesurez prompt_tokens. Ne supprimez pas un message indispensable au sens de la tâche ou à la continuité d’un Tool Call.

Obtenir un JSON valide

DeepSeek fournit JSON Output avec response_format={"type":"json_object"}. La documentation demande aussi d’inclure le mot « json » dans le message system ou user, de donner un exemple de structure et de réserver assez de tokens pour ne pas tronquer l’objet.

import json

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {
            "role": "system",
            "content": (
                "Retourne uniquement un objet json valide avec les clés "
                "\"titre\" et \"actions\". actions doit être un tableau de chaînes."
            ),
        },
        {"role": "user", "content": "Prépare trois actions pour auditer une API."},
    ],
    response_format={"type": "json_object"},
    max_tokens=500,
    extra_body={"thinking": {"type": "disabled"}},
)

data = json.loads(response.choices[0].message.content)
print(data["actions"])

Un JSON syntaxiquement valide n’est pas automatiquement conforme à vos règles métier. Validez-le avec un schéma côté serveur et refusez les champs inattendus avant tout traitement.

Tool Calls et fonctions

Les Tool Calls permettent au modèle de produire le nom d’une fonction et des arguments. Le modèle ne se connecte pas seul à votre CRM, votre base de données ou un service de paiement. Votre application doit contrôler le nom demandé, parser les arguments, les valider, vérifier les droits, demander une confirmation pour les actions sensibles, exécuter la fonction puis renvoyer le résultat avec le rôle tool.

• N’exposez que les fonctions réellement nécessaires.
• Utilisez un schéma JSON strict et des listes d’autorisation.
• Ne faites pas confiance aux chemins, URL, identifiants ou montants générés.
• Ajoutez des limites de boucles, des délais et une journalisation des actions exécutées.
• Exigez une confirmation humaine pour envoyer, acheter, supprimer ou modifier des données importantes.

Le paramètre strict: true des fonctions est documenté comme Beta. Même avec ce mode, validez les données côté application : le contrôle du schéma ne remplace ni les permissions ni les règles métier.

Streaming des réponses

Avec stream: true, l’API renvoie des événements Server-Sent Events. Chaque fragment peut contenir du texte final ou, en Thinking, du reasoning_content. La séquence se termine par data: [DONE]. Si vous demandez stream_options.include_usage, un fragment supplémentaire avant [DONE] contient l’usage total.

stream = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Explique le cache en cinq points."}],
    stream=True,
    stream_options={"include_usage": True},
    extra_body={"thinking": {"type": "disabled"}},
)

for chunk in stream:
    if chunk.choices:
        text = chunk.choices[0].delta.content
        if text:
            print(text, end="", flush=True)
    if chunk.usage:
        print("\nUsage :", chunk.usage)

Cache de contexte et mesure des tokens

Le cache disque de contexte est activé par défaut. Lorsqu’une nouvelle requête réutilise intégralement un préfixe déjà persisté, les tokens correspondants peuvent devenir des cache hits. Le mécanisme fonctionne en « best effort » et ne garantit pas un taux de hit de 100 %.

Champ usage	Signification
prompt_cache_hit_tokens	Tokens d’entrée servis via un préfixe en cache.
prompt_cache_miss_tokens	Tokens d’entrée sans cache hit.
prompt_tokens	Somme des hits et des misses du prompt.
completion_tokens	Tokens générés dans la complétion.
completion_tokens_details.reasoning_tokens	Sous-ensemble de tokens de raisonnement produit en Thinking.
total_tokens	Total prompt + complétion.

Les tokens de raisonnement sont détaillés à l’intérieur des tokens de complétion. Pour contrôler la facture, utilisez les valeurs réellement renvoyées par usage et appliquez les tarifs d’entrée avec ou sans cache et le tarif de sortie. Consultez notre guide du cache de contexte DeepSeek pour les règles de préfixe et les exemples.

FIM, préfixe de chat et fonctions Beta

Les fonctions Beta utilisent la base https://api.deepseek.com/beta. Chat Prefix Completion complète un début de réponse assistant. FIM, ou Fill In the Middle, complète le contenu situé entre un préfixe et un suffixe optionnel.

La limite de 384K concerne la sortie maximale annoncée pour Chat Completions. Elle ne remplace pas la limite FIM Beta de 4K.

Concurrence, erreurs et reprises

Les limites publiées sont de 2 500 requêtes concurrentes pour Flash et 500 pour Pro. Elles sont calculées au niveau du compte, quel que soit le nombre de clés API. Une requête compte comme concurrente depuis son envoi jusqu’à la fin de la réponse.

Code	Cause documentée	Action
400	Format invalide	Corriger le corps selon le message retourné.
401	Authentification échouée	Vérifier la clé et son chargement côté serveur.
402	Solde insuffisant	Contrôler le solde et le compte de facturation.
422	Paramètres invalides	Vérifier modèle, types et valeurs autorisées.
429	Limite atteinte	Réduire la concurrence et réessayer progressivement.
500	Erreur serveur	Réessayer avec temporisation et consulter le statut.
503	Serveur surchargé	Réduire le rythme et réessayer plus tard.

Pour 429, 500 et 503, utilisez un backoff exponentiel avec jitter et un nombre maximal de tentatives. Respectez Retry-After lorsqu’il est présent, mais ne supposez pas que cet en-tête sera toujours fourni. Ajoutez une clé d’idempotence dans votre propre logique pour toute opération métier qui ne doit pas être répétée.

La documentation décrit également des lignes vides pour les requêtes non streamées et des commentaires SSE : keep-alive pour le streaming pendant l’attente. Un parseur HTTP personnalisé doit les accepter. Si l’inférence n’a pas commencé après dix minutes, le serveur ferme la connexion.

Sécurité, confidentialité et mise en production

• Gardez la clé uniquement côté serveur et faites-la tourner après toute exposition.
• Ne transmettez pas de secret, mot de passe, donnée de santé ou autre donnée sensible sans base juridique, nécessité et protections adaptées.
• Ne placez aucune donnée personnelle dans user_id.
• Filtrez les logs pour ne pas enregistrer la clé ni des prompts complets par défaut.
• Validez les sorties avant de les afficher ou de les utiliser dans une décision importante.
• Appliquez des contrôles humains aux actions à impact financier, juridique, médical ou administratif.

La politique de confidentialité DeepSeek indique notamment que des entrées, fichiers, historiques et données techniques peuvent être collectés, que certaines données peuvent servir à améliorer ou entraîner les modèles, et que les données sont directement collectées, traitées et stockées en Chine. Elle permet de s’opposer à l’utilisation pour l’entraînement via les réglages prévus. Si vous construisez une application utilisant l’Open Platform, votre propre politique de confidentialité doit expliquer le traitement des données de vos utilisateurs : la politique DeepSeek ne couvre pas à elle seule votre produit en aval.

Checklist avant la production

1. Vérifier les modèles avec GET /models.
2. Fixer explicitement Flash ou Pro dans la configuration.
3. Choisir Thinking ou Non-Thinking au lieu de dépendre du défaut.
4. Définir max_tokens et mesurer usage.
5. Mettre en place timeout, backoff, jitter et plafond de tentatives.
6. Valider JSON et arguments de Tool Calls côté serveur.
7. Protéger la clé et séparer environnements de test et de production.
8. Tester en français sur un corpus représentatif de votre usage.
9. Documenter les données envoyées, les rôles des prestataires et les durées de conservation.
10. Surveiller coût, latence, taux d’erreur et qualité par version de modèle.

FAQ sur l’API DeepSeek

Quels identifiants utiliser en juillet 2026 ?

Utilisez deepseek-v4-flash ou deepseek-v4-pro. Ce sont les deux identifiants présentés dans l’exemple actuel de l’endpoint GET /models.

Puis-je encore utiliser deepseek-chat ou deepseek-reasoner ?

Ne les utilisez plus pour un nouveau projet. L’annonce V4 indiquait qu’ils seraient entièrement retirés et inaccessibles après le 24 juillet 2026 à 15 h 59 UTC. Migrez vers les identifiants V4 explicites et vérifiez GET /models dans votre compte.

L’API DeepSeek est-elle identique à l’API OpenAI ?

Non. Elle accepte un format compatible pour Chat Completions et peut être appelée avec le SDK OpenAI, mais DeepSeek possède ses propres modèles, paramètres, fonctions, limites et endpoints. Vérifiez chaque fonctionnalité dans sa documentation DeepSeek.

Thinking est-il activé automatiquement ?

Oui, la documentation V4 indique qu’il est activé par défaut. Utilisez {"thinking":{"type":"disabled"}} si vous voulez explicitement le mode Non-Thinking.

DeepSeek conserve-t-il la conversation entre deux appels ?

L’endpoint ne réinjecte pas l’historique automatiquement. Votre application doit renvoyer les messages précédents nécessaires. Cette caractéristique ne permet pas de conclure que DeepSeek ne journalise, ne traite ou ne conserve jamais les données.

Existe-t-il un endpoint Embeddings DeepSeek officiel ?

La documentation API actuelle consultée ne présente pas d’endpoint Embeddings first-party. Ne configurez pas une URL supposée. Pour un système RAG, choisissez séparément une solution d’embeddings documentée et évaluez sa région, sa confidentialité et son coût.

Le cache garantit-il toujours une réduction de prix ?

Non. Le cache fonctionne en best effort et exige la réutilisation complète d’un préfixe persisté. Mesurez les champs prompt_cache_hit_tokens et prompt_cache_miss_tokens au lieu d’estimer le taux de hit.

Sources officielles

• Your First API Call — DeepSeek API Docs
• Create Chat Completion — référence officielle
• GET /models — liste des modèles
• Annonce DeepSeek V4 Preview et retrait des anciens alias
• Thinking Mode
• Multi-round Conversation
• JSON Output
• Tool Calls
• Context Caching
• Rate Limit & Isolation
• Error Codes
• Politique de confidentialité DeepSeek

---

À lire ensuite : DeepSeek V4 Flash et Pro, prix de l’API DeepSeek, obtenir une clé API, limites de l’API et codes d’erreur DeepSeek.