L’API DeepSeek : le guide du développeur

L’API DeepSeek est construite sur une idée simple : être un drop-in replacement pour les API OpenAI et Anthropic. Ainsi, vous gardez le même format de requête, la même structure de réponse, les mêmes SDK. Vous changez la base_url et la clé API dans votre code existant, et tout fonctionne. La compatibilité n’est pas un accident, c’est une stratégie délibérée pour réduire à zéro le coût de migration.

Si vous avez lu l’article 3 de la série, vous connaissez les benchmarks et les options de self-hosting. Cet article-ci entre dans le quotidien d’un développeur : les endpoints, les paramètres qui comptent, le function calling, le JSON mode, le cache automatique, les patterns de retry, et les pièges à éviter en production sur l’API V4.

Les deux endpoints et les quatre model IDs

L’API DeepSeek expose deux endpoints distincts, qui servent les mêmes modèles dans deux formats différents. Ainsi, le format OpenAI est compatible avec le SDK openai. Ensuite, le format Anthropic est compatible avec le SDK anthropic et avec Claude Code.

Côté modèles, la gamme V4 expose quatre IDs au moment où vous lisez cet article. Ainsi, les deux nouveaux IDs V4 sont à utiliser pour toute nouvelle intégration. En revanche, les deux anciens IDs V3 routent vers V4-Flash et seront retirés le 24 juillet 2026 à 15h59 UTC.

Pour V4-Pro, le contexte d’1M de tokens nécessite explicitement le suffixe entre crochets : deepseek-v4-pro[1m]. Sans ce suffixe, vous restez plafonné à 200K. C’est la principale source de confusion à la migration et c’est documenté dans la doc officielle.

Premier appel et paramètres qui comptent

Le SDK officiel OpenAI fonctionne tel quel. Installez-le, pointez la base_url vers https://api.deepseek.com, et appelez le modèle. Pour info, DeepSeek recommande temperature=1.0 et top_p=1.0 sur V4 — n’importez pas les valeurs par défaut d’autres modèles, elles dégradent les performances sur les benchmarks de raisonnement.

# Premier appel V4-Flash en Non-think
from openai import OpenAI

client = OpenAI(
    api_key="sk-VOTRE-CLE",
    base_url="https://api.deepseek.com"
)

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Salut !"}],
    temperature=1.0,
    top_p=1.0
)
print(response.choices[0].message.content)
print(response.usage)  # tokens input/output (+ reasoning si thinking)

L’objet usage de la réponse renvoie les prompt_tokens, completion_tokens et, en mode thinking, un champ reasoning_tokens. En pratique, ces trois valeurs sont la base de votre suivi de coût en production. Pensez à les logguer dès le premier jour.

Activer le mode thinking

V4-Pro et V4-Flash partagent trois modes de raisonnement : Non-think (défaut, rapide), Think High (qualité maximale) et Think Max (raisonnement long jusqu’à 384K tokens). Le mode s’active via deux paramètres, reasoning_effort et un extra_body pour activer le bloc thinking.

# V4-Pro avec contexte 1M et Think Max
response = client.chat.completions.create(
    model="deepseek-v4-pro[1m]",
    messages=[{"role": "user", "content": "Démontre l'irrationalité de racine de 2."}],
    reasoning_effort="max",
    extra_body={"thinking": {"type": "enabled"}},
    temperature=1.0,
    top_p=1.0
)

# La chaîne de pensée arrive dans reasoning_content
print(response.choices[0].message.reasoning_content)
print(response.choices[0].message.content)
print(response.usage.reasoning_tokens)  # tokens de raisonnement facturés

À noter : en mode thinking, les paramètres temperature, top_p, presence_penalty et frequency_penalty sont ignorés silencieusement par le serveur. C’est documenté. Si vous testez deux configurations et que les sorties varient malgré temperature=0, c’est normal — passez en Non-think pour obtenir un comportement déterministe.

Le pricing en détail : cache automatique et off-peak

Le système de cache est l’arme secrète du pricing DeepSeek. Le cache fonctionne automatiquement : si votre requête partage un préfixe commun avec une requête récente (même system prompt, mêmes outils, seul le message utilisateur change), les tokens du préfixe sont alors servis depuis le cache. Coût : divisé par 10 sur l’input.

Pour maximiser le cache hit, structurez vos requêtes avec un préfixe stable : system prompt + définitions d’outils + schéma de sortie en premier, contenu variable en dernier. Ainsi, un pipeline de classification qui traite 10 000 textes avec le même system prompt obtient un taux de cache hit supérieur à 90 % à partir du deuxième appel. Sur un system prompt de 10 000 tokens, le coût d’entrée s’effondre alors à quasi rien après la première requête.

Off-peak pricing : -50 % pendant la nuit chinoise

DeepSeek applique automatiquement une remise de 50 % sur tous les modèles pendant la fenêtre 16h30 à 00h30 UTC (ce qui correspond à 18h30-02h30 en heure de Paris). Ainsi, si votre charge tolère le décalage, planifiez les batchs de classification, d’extraction ou d’enrichissement de données pendant cette fenêtre. Aucun paramètre à activer : la remise est automatique sur l’heure d’envoi de la requête. Combinée avec le cache hit, l’input V4-Flash tombe sous 0,01 $/M tokens. À ce niveau, le coût n’est plus une variable de décision.

Function calling et thinking with tool-use

V4 supporte le function calling dans les trois modes (Non-think, Think High, Think Max) et accepte jusqu’à 128 appels d’outils en parallèle sur une même réponse. Concrètement, le format est identique à OpenAI : vous définissez vos outils dans un tableau tools, le modèle décide quand les appeler, votre code exécute la fonction et renvoie le résultat.

# Function calling — format identique à OpenAI
from openai import OpenAI

client = OpenAI(api_key="sk-VOTRE-CLE", base_url="https://api.deepseek.com")

tools = [{
    "type": "function",
    "function": {
        "name": "chercher_produit",
        "description": "Cherche un produit dans le catalogue.",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {"type": "string"},
                "categorie": {"type": "string"}
            },
            "required": ["query"]
        }
    }
}]

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Trouve-moi un clavier ergonomique."}],
    tools=tools,
    tool_choice="auto"
)

tool_call = response.choices[0].message.tool_calls[0]
print(tool_call.function.name)       # "chercher_produit"
print(tool_call.function.arguments)  # {"query": "clavier ergonomique"}

Thinking with tool-use : le pattern agentic

En mode thinking activé sur V4, le modèle raisonne d’abord sur la requête, décide quel outil appeler, exécute l’appel, reçoit le résultat, raisonne à nouveau, et peut enchaîner plusieurs appels avant de produire la réponse finale. C’est un comportement agentique natif, sans framework externe.

Point d’attention de production : en mode thinking avec tool-use, vous devez renvoyer le reasoning_content au modèle entre chaque tour. Si vous l’omettez, l’API renvoie une erreur 400. Quand une nouvelle question commence dans une session, supprimez les reasoning_content des tours précédents pour éviter la pollution du contexte. Le pattern est documenté dans la doc officielle.

JSON mode, FIM et chat-prefix completion

Au-delà du function calling, l’API DeepSeek expose trois fonctionnalités utiles pour les pipelines structurés.

JSON mode pour la sortie structurée

Le JSON mode garantit que la sortie est un objet JSON valide. Vous l’activez via response_format={"type": "json_object"} dans la requête. Important : pour que le mode fonctionne, le mot « json » doit apparaître quelque part dans le system prompt ou le user message — sinon le serveur renvoie une erreur. Le combo qui marche le mieux : décrire le schéma attendu en JSON dans le system prompt, demander explicitement « Réponds en JSON », et activer response_format.

# JSON mode pour extraction structurée
response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": (
            "Extrais les infos en JSON valide avec ces clés : "
            "nom_entreprise (string), ca_meur (number), "
            "nb_employes (number), secteur (string)."
        )},
        {"role": "user", "content": "Doctolib emploie 2800 personnes et a fait 500 M€ en 2024."}
    ],
    response_format={"type": "json_object"}
)
import json
data = json.loads(response.choices[0].message.content)

FIM — Fill In the Middle pour le code

FIM est un mode bêta réservé à V4-Flash en Non-think. Le service prend un prompt (le code avant le curseur) et un suffix (le code après le curseur), puis génère le contenu manquant au milieu. Ainsi, c’est exactement ce dont a besoin un système d’autocomplétion en ligne dans un IDE. La latence est sous 500 ms et le coût reste celui de V4-Flash, ce qui rend l’option viable pour servir de l’autocomplete IDE à un coût quasi nul.

Chat-prefix completion — pour forcer un format de sortie

La fonctionnalité chat-prefix completion (bêta) permet de pré-remplir le début de la réponse de l’assistant et de demander au modèle de continuer. Le service est utile pour forcer un format spécifique sans même avoir à le décrire dans le prompt : vous démarrez la réponse par {"resultat": et le modèle complète le JSON attendu.

Patterns de production : retry, observabilité, robustesse

L’API DeepSeek n’impose pas de rate limit strict côté client. La doc officielle indique que le service traite chaque requête qu’il peut absorber, sans plafond par utilisateur. Cela dit, aux heures de pointe chinoises (9h-18h heure de Pékin), les erreurs 503 et les latences élevées sont fréquentes. Ainsi, sur un service en production, ces deux patterns sont indispensables.

Retry avec backoff exponentiel

# Pattern de retry recommandé
import time
from openai import RateLimitError, APIStatusError

def appel_deepseek_robuste(client, **kwargs):
    for tentative in range(5):
        try:
            return client.chat.completions.create(**kwargs)
        except (RateLimitError, APIStatusError) as e:
            if tentative == 4:
                raise
            # backoff : 1s, 2s, 4s, 8s
            time.sleep(2 ** tentative)
        except Exception as e:
            # 402 Insufficient Balance, 401 Auth, etc.
            raise

L’erreur 402 Insufficient Balance survient quand votre solde est à zéro : pas de retry possible, il faut recharger. Les nouveaux comptes obtiennent 5 millions de tokens gratuits à l’inscription, ensuite il faut créditer la plateforme avec un minimum de 2 $ pour activer la facturation.

Observabilité du coût en temps réel

Loggez systématiquement response.usage dans votre télémétrie, en distinguant les quatre catégories qui pilotent vraiment le coût : cache_hit_input_tokens, cache_miss_input_tokens, output_tokens, et reasoning_tokens en mode thinking. Sans cette télémétrie, vous découvrez votre facture à la fin du mois et vous ne savez pas quel paramètre tirer pour la réduire. En revanche, avec elle, vous savez en deux jours quel system prompt mérite d’être réécrit pour maximiser le cache hit, et quelle route mérite de basculer de Pro vers Flash.

Ce qui est compatible et ce qui diffère

La compatibilité avec OpenAI et Anthropic est élevée mais pas parfaite. Voici alors la cartographie précise.

Ce qui fonctionne tel quel

• Format de messages — system, user, assistant, tool. Structure identique sur l’endpoint OpenAI ; structure Anthropic Messages sur l’endpoint /anthropic.
• Streaming — stream: true renvoie des chunks SSE dans le format attendu.
• Function calling et tool use — même format, même flux d’exécution, jusqu’à 128 appels parallèles.
• JSON mode — response_format={"type": "json_object"} supporté.
• SDK officiels — le SDK OpenAI Python et Node, LangChain et LlamaIndex fonctionnent en changeant la base_url.
• Paramètres de génération — temperature, top_p, max_tokens, presence_penalty, frequency_penalty, stop.

Ce qui diffère ou qui manque

• Mode thinking — paramètres reasoning_effort et extra_body spécifiques. Le champ reasoning_content et la métrique reasoning_tokens n’existent pas chez OpenAI.
• Suffixe [1m] — particulier à V4-Pro pour activer le contexte 1M ; sans suffixe, V4-Pro est plafonné à 200K.
• Pas d’API d’embeddings — DeepSeek ne propose pas d’embeddings. Utilisez Jina, Voyage ou un service dédié pour vectoriser.
• Pas de fine-tuning via API — les poids sont open-weight sous MIT, le fine-tuning se fait en self-hosting (Axolotl, LLaMA-Factory, Unsloth), pas via l’API cloud.
• Pas d’API de modération — pas d’endpoint de modération comme OpenAI, pas de content filter configurable côté API. À implémenter en aval si nécessaire.
• Pas de Batch API à tarif réduit — pas d’équivalent au Batch API d’OpenAI. En revanche, l’off-peak -50 % (16h30-00h30 UTC) joue un rôle similaire pour les charges asynchrones.
• Pas de SLA formel — fiabilité variable aux heures de pointe chinoises. Implémentez un retry avec backoff exponentiel obligatoirement.

API officielle, providers tiers ou self-hosting : comment choisir

Trois façons d’accéder à V4. Le bon choix dépend principalement de votre contrainte sur la résidence des données et de votre volume.

Pour le prototypage et les projets personnels, l’API officielle est imbattable. Ensuite, pour les données sensibles en Europe, un provider tiers hébergé hors de Chine est le compromis pragmatique. Enfin, pour le contrôle total sans compromis, le self-hosting est la seule option mais réservez-le aux volumes qui justifient le coût d’infrastructure (cf. l’article 3 pour les détails du setup vLLM).

Les cas d’usage où l’API DeepSeek est le choix rationnel

L’API DeepSeek n’est pas le bon outil pour tout. Mais sur certains cas d’usage précis, c’est objectivement le choix économiquement rationnel : la qualité est suffisante et le coût est imbattable.

Classification et étiquetage à grande échelle

Trier des milliers de tickets support, catégoriser des commentaires utilisateurs, étiqueter des données d’entraînement. V4-Flash en Non-think est assez précis pour ces tâches, et le cache rend le coût négligeable quand le system prompt est stable. Ajoutez l’off-peak pricing : votre pipeline tombe sous le centime par millier d’items traités.

Extraction de données structurées

Transformer des factures, contrats, emails ou rapports en JSON structuré. Le JSON mode garantit la validité du format, et le function calling avec un schéma required garantit la complétude des champs. Coût : quelques dollars pour des milliers de documents.

Prototypage rapide d’agents et de RAG

Tester une idée d’agent, un pipeline RAG, un chatbot interne. Les 5 millions de tokens gratuits à l’inscription permettent de prototyper sérieusement avant la moindre dépense. Ensuite, la compatibilité OpenAI permet de migrer vers un autre provider sans refonte si les exigences de qualité changent.

Traduction et résumé de volume

Traduire une documentation technique de 500 pages, résumer des centaines de rapports, normaliser des transcriptions. Avec V4-Flash en off-peak, le coût total tombe à quelques dollars pour des charges qui demandent normalement plusieurs centaines.

Pipelines de données et enrichissement

Nettoyer, normaliser, enrichir des datasets. Tâches répétitives sur des millions de lignes où la qualité « assez bonne » suffit et où le coût est le facteur décisif. Le cache hit + off-peak rend ces charges quasi gratuites.

Ce qu’il faut retenir

L’API DeepSeek V4 est techniquement solide : deux endpoints (OpenAI et Anthropic), trois modes de raisonnement, function calling avec 128 appels parallèles, JSON mode, FIM, chat-prefix completion. Ainsi, la compatibilité est suffisamment élevée pour que la plupart des applications existantes fonctionnent en changeant deux lignes de code.

La vraie force est le pricing. Avec le cache automatique à 90 % de réduction et l’off-peak à -50 %, l’input V4-Flash tombe sous 0,01 $ par million de tokens. Sur les pipelines de volume, le coût n’est plus une variable de décision. Et avec la promo de lancement à -75 % sur V4-Pro jusqu’au 5 mai 2026, c’est aussi le bon moment pour tester le modèle phare au tarif Flash.

Les limites sont techniques (pas d’embeddings, pas de batch API à tarif réduit, pas de fine-tuning cloud, fiabilité variable aux heures de pointe) et géopolitiques (serveurs en Chine, censure inscrite dans les poids, pas de RGPD côté API officielle). Le prochain article entre dans ces sujets sous l’angle pratique : DeepSeek en production — conformité, censure et données. Les patterns qui marchent pour mettre V4 en prod sans buter sur ses zones d’ombre : contournement RGPD via providers tiers, prompts qui évitent les blocages, filtres applicatifs et choix d’hébergement selon la sensibilité de vos données.