Comment utiliser l'API DeepSeek V4?

DeepSeek V4 a été lancé avec l'API disponible dès le premier jour. Les identifiants de modèle sont deepseek-v4-pro et deepseek-v4-flash, le point de terminaison est compatible OpenAI, et l'URL de base est https://api.deepseek.com. Cela signifie que tout client que vous utilisez déjà avec GPT-5.5 ou d'autres API de type OpenAI fonctionne avec V4 avec un simple échange d'URL de base.

Ce guide couvre l'authentification, tous les paramètres importants, des exemples en Python et Node, les calculs en mode réflexion, l'appel d'outils, le streaming, et un flux de travail basé sur Apidog qui maintient les coûts visibles pendant que vous itérez.

Pour un aperçu du produit, consultez qu'est-ce que DeepSeek V4. Pour la méthode sans coût, consultez comment utiliser DeepSeek V4 gratuitement.

En bref

• DeepSeek V4 est disponible sur le point de terminaison compatible OpenAI à https://api.deepseek.com/v1/chat/completions et le point de terminaison compatible Anthropic à https://api.deepseek.com/anthropic.
• IDs des modèles : deepseek-v4-pro (1.6T total, 49B actif) et deepseek-v4-flash (284B total, 13B actif).
• Les deux variantes supportent un contexte de 1M de tokens et trois modes de raisonnement : non-thinking, thinking, thinking_max.
• Utilisez temperature=1.0, top_p=1.0 comme recommandé par DeepSeek ; n'importez pas les valeurs par défaut de GPT-5.5 ou Claude.
• Les IDs hérités deepseek-chat et deepseek-reasoner seront dépréciés le 24 juillet 2026 ; migrez avant cette date.
• Téléchargez Apidog pour rejouer les requêtes, comparer les modes de réflexion, et éviter de laisser la clé dans l'historique de votre shell.

Prérequis

Avant la première requête, préparez quatre choses.

• Un compte développeur DeepSeek sur platform.deepseek.com avec un rechargement d'au moins 2 $. Sans solde, les appels renvoient 402 Insufficient Balance.
• Une clé API limitée au projet que vous facturerez. Les clés limitées à un projet sont plus sûres que les clés de compte pour toute utilisation en production.
• Un SDK capable d'interroger une URL de base compatible OpenAI. Python openai>=1.30.0 et Node openai@4.x fonctionnent tous deux sans modification.
• Un client API capable de rejouer les requêtes sans encombrer le terminal. curl fonctionne pour un seul appel ; après cela, utilisez Apidog.

Exportez la clé une fois :

export DEEPSEEK_API_KEY="sk-..."

Point de terminaison et authentification

Deux URL de base couvrent deux formats de requête.

POST https://api.deepseek.com/v1/chat/completions    # Format OpenAI
POST https://api.deepseek.com/anthropic/v1/messages  # Format Anthropic

Choisissez le format compatible OpenAI, sauf si vous disposez d'une base de code existante de type Anthropic. Le reste de ce guide utilise le format OpenAI.

L'authentification se fait par un jeton bearer dans l'en-tête standard Authorization. La requête minimale viable :

curl https://api.deepseek.com/v1/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "user", "content": "Expliquez le routage MoE en deux phrases."}
    ]
  }'

Les réponses réussies renvoient un corps JSON avec un tableau choices, un bloc usage détaillé en tokens d'entrée et de sortie (et reasoning_tokens si le mode de réflexion était activé), et un id que vous pouvez utiliser pour le traçage. Les échecs renvoient l'enveloppe OpenAI standard avec error.code et error.message.

Paramètres de requête

Chaque champ correspond à un coût ou à un comportement. Voici la correspondance pour deepseek-v4-pro et deepseek-v4-flash.

thinking_mode est le principal levier de coût. non-thinking ignore entièrement la trace de raisonnement et renvoie des tokens à une vitesse comparable à V3.2. thinking active un bloc de raisonnement qui coûte des tokens supplémentaires mais améliore la précision sur le code et les mathématiques. thinking_max produit les scores du tableau principal de DeepSeek ; il consomme également le plus de tokens et est le seul mode qui nécessite un budget de contexte de plus de 384K.

Client Python

Le SDK officiel openai fonctionne avec une surcharge d'URL de base. Chaque wrapper compatible OpenAI existant, y compris LangChain, LlamaIndex et DSPy, fonctionne également.

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "system", "content": "Répondez en code seulement."},
        {"role": "user", "content": "Écrivez une fonction Rust qui dédoublonne les événements."},
    ],
    extra_body={"thinking_mode": "thinking"},
    temperature=1.0,
    top_p=1.0,
    max_tokens=2048,
)

choice = response.choices[0]
print("Contenu:", choice.message.content)
print("Tokens de raisonnement:", response.usage.reasoning_tokens)
print("Tokens totaux:", response.usage.total_tokens)

L'astuce extra_body est la manière de passer les paramètres spécifiques à DeepSeek via le SDK OpenAI sans modifier la bibliothèque.

Client Node

Même structure en Node :

import OpenAI from "openai";

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

const response = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [
    { role: "user", content: "Expliquez l'optimiseur Muon en langage simple." },
  ],
  thinking_mode: "thinking",
  temperature: 1.0,
  top_p: 1.0,
});

console.log(response.choices[0].message.content);
console.log("Utilisation:", response.usage);

Le SDK Node accepte les champs inconnus silencieusement, donc thinking_mode est transmis directement sans extra_body.

Réponses en streaming

Définissez stream: true et itérez sur les fragments SSE. La structure correspond exactement à celle d'OpenAI.

stream = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Diffusez un essai de 300 mots sur le MoE."}],
    stream=True,
    extra_body={"thinking_mode": "non-thinking"},
)

for chunk in stream:
    delta = chunk.choices[0].delta.content or ""
    print(delta, end="", flush=True)

Les traces de raisonnement sont diffusées séparément lorsque le mode de réflexion est activé ; le champ delta.reasoning_content les contient et vous pouvez les afficher dans l'interface utilisateur ou les ignorer.

Appel d'outils

V4 prend en charge le schéma standard d'appel d'outils d'OpenAI. Les fonctions définies dans le tableau tools deviennent appelables, et le modèle décide quand les invoquer.

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Retourne la météo actuelle pour une ville.",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"},
                "unit": {"type": "string", "enum": ["c", "f"]},
            },
            "required": ["city"],
        },
    },
}]

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Météo à Lagos en Celsius ?" }],
    tools=tools,
    tool_choice="auto",
    extra_body={"thinking_mode": "thinking"},
)

tool_call = response.choices[0].message.tool_calls[0]
print(tool_call.function.name, tool_call.function.arguments)

À partir de là, appelez la fonction, ajoutez le résultat comme un message role: "tool", et appelez l'API à nouveau pour continuer la boucle. Le modèle est identique aux boucles d'utilisation d'outils d'OpenAI et Anthropic.

Mode JSON

Pour une sortie structurée, demandez explicitement du JSON et définissez le format de réponse.

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "Répondez avec un seul objet JSON."},
        {"role": "user", "content": "Résumez cette note de version sous forme de {titre, date, puces} : ..."},
    ],
    response_format={"type": "json_object"},
    extra_body={"thinking_mode": "non-thinking"},
)

Le mode JSON force un JSON valide mais n'impose pas de schéma spécifique. Pour la validation de schéma, associez-le à Pydantic ou Zod côté client.

Construire la collection dans Apidog

Rejouer des requêtes depuis le terminal consomme des crédits et masque les différences entre les exécutions. Le flux de travail qui résiste à une utilisation réelle :

1. Téléchargez Apidog et créez un projet.
2. Ajoutez un environnement avec {{DEEPSEEK_API_KEY}} stocké comme variable secrète.
3. Enregistrez une requête POST vers {{BASE_URL}}/chat/completions avec l'en-tête Authorization: Bearer {{DEEPSEEK_API_KEY}}.
4. Paramétrez model et thinking_mode afin de pouvoir effectuer des tests A/B entre les variantes sans dupliquer les requêtes.
5. Utilisez l'afficheur de réponse pour inspecter usage.reasoning_tokens à chaque exécution. C'est le signal le plus clair pour savoir si vous payez pour un mode de réflexion dont vous n'avez pas besoin.

Les équipes utilisant déjà la collection d'API GPT-5.5 correspondante dans Apidog peuvent la dupliquer, changer l'URL de base pour https://api.deepseek.com/v1, changer l'ID du modèle, et exécuter des requêtes de comparaison entre les deux fournisseurs en quelques minutes.

Gestion des erreurs

L'enveloppe suit exactement celle d'OpenAI. Ceux que vous rencontrerez en premier :

Enveloppez les appels dans une fonction de réessai qui gère les erreurs 429 et 5xx avec un backoff exponentiel. Ne réessayez pas automatiquement les erreurs 4xx ; ce sont des bogues logiques, pas des échecs transitoires.

Modèles de contrôle des coûts

Quatre modèles permettent de maintenir les dépenses prévisibles.

1. Utilisez V4-Flash par défaut. Passez à V4-Pro uniquement pour les invites où vous avez mesuré une amélioration de la qualité.
2. Restreignez l'accès à thinking_max via un flag. C'est de loin le mode le plus cher ; ne l'utilisez que lorsque la correction prime sur la latence.
3. Limitez max_tokens. La plupart des réponses tiennent en 2 000 tokens de sortie. Le contexte de 1M est pour l'entrée, pas la sortie.
4. Enregistrez l'usage à chaque appel. Envoyez les comptes d'entrée, de sortie et de raisonnement à votre pile d'observabilité ; une alerte sur un pic soudain de tokens de raisonnement détecte les invites qui ont dérivé.

Migration depuis les anciens modèles DeepSeek

Les anciens IDs deepseek-chat et deepseek-reasoner seront dépréciés le 24 juillet 2026. La migration ne nécessite qu'une ligne de différence par site d'appel ; les formats de requête et de réponse restent inchangés.

-  model="deepseek-chat"
+  model="deepseek-v4-pro"

Avant de passer en production, effectuez des comparaisons A/B côte à côte dans Apidog. Le saut de qualité de réponse récompense généralement le changement ; la date limite de dépréciation l'impose de toute façon.

FAQ

L'API DeepSeek V4 est-elle prête pour la production ?Oui. L'API a été lancée le 23 avril 2026 en même temps que les poids. DeepSeek V3 et V3.2 ont fonctionné sur la même infrastructure à grande échelle pendant plus d'un an, donc la surface API est mature.

V4 prend-il en charge le format de message Anthropic ?Oui. Pointez vers https://api.deepseek.com/anthropic/v1/messages et envoyez la charge utile au format Anthropic. Les deux formats atteignent le même modèle sous-jacent.

Quelle est la fenêtre de contexte ?1 million de tokens sur V4-Pro et V4-Flash. Notez que le mode Think Max recommande une fenêtre de travail minimale de 384K.

Comment compter les tokens d'entrée avant l'envoi ?Utilisez le tokenizer OpenAI standard pour les approximations ; DeepSeek publie les comptes exacts dans le bloc usage de chaque réponse. Pour la budgétisation en production, fiez-vous au compte côté réponse.

Puis-je effectuer du fine-tuning via l'API ?Pas au lancement. Le fine-tuning s'effectue actuellement via les checkpoints de base auto-hébergés sur Hugging Face.

L'API est-elle gratuite à essayer ?Il n'y a pas de niveau gratuit au niveau du compte, mais les nouvelles inscriptions reçoivent occasionnellement un crédit d'essai.