L’API DeepSeek : le guide du développeur

L’API DeepSeek repose sur une idée simple : remplacer les API d’OpenAI et d’Anthropic sans réécrire votre code. Vous gardez le même format de requête, la même structure de réponse et les mêmes SDK. Seules l’adresse du serveur et la clé changent.

L’article 3 de la série a présenté les benchmarks de code et l’auto-hébergement. Celui-ci s’adresse au développeur qui intègre l’API dans une application : les paramètres qui comptent, les fonctions avancées, la facturation et les réflexes de production.

Les formats et les identifiants de modèles

L’API accepte trois formats, servis par deux adresses. Tous donnent accès aux mêmes modèles.

Côté modèles, deux identifiants servent aujourd’hui. Les anciens noms restent acceptés pour certains, mais ils pointent vers le nouveau modèle.

Si votre code appelle encore deepseek-v4-flash, il tourne déjà sur V4.1-Flash sans que vous l’ayez choisi. Le comportement a changé (réponses plus directes, vision, meilleurs scores d’agent), et le tarif aussi. Passez à deepseek-flash pour que votre code dise ce qu’il utilise vraiment.

Le premier appel et les paramètres qui comptent

Le SDK officiel d’OpenAI fonctionne tel quel. L’objet usage de la réponse détaille les tokens d’entrée servis par le cache (prompt_cache_hit_tokens), ceux traités normalement (prompt_cache_miss_tokens) et les tokens de sortie. Enregistrez ces valeurs dès le premier jour, car elles pilotent votre facture.

# Premier appel à V4.1-Flash
from openai import OpenAI

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

response = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "Bonjour !"}]
)
print(response.choices[0].message.content)
print(response.usage)  # cache, hors cache, sortie

Régler la réflexion

La réflexion est activée par défaut, avec un effort high. Le paramètre reasoning_effort accepte trois niveaux réels : low, high et max. L’API traduit aussi les valeurs utilisées par d’autres fournisseurs : minimal devient low, medium et xhigh deviennent high, et ultra devient max. Un code écrit pour OpenAI fonctionne donc sans erreur, mais il n’obtient pas forcément le niveau qu’il croit demander.

# V4-Pro en effort maximal
response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Démontre que racine de 2 est irrationnelle."}],
    reasoning_effort="max",
    extra_body={"thinking": {"type": "enabled"}}
)
print(response.choices[0].message.reasoning_content)  # le raisonnement
print(response.choices[0].message.content)            # la réponse

# Sans réflexion, pour les tâches simples et répétitives
response = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "Traduis en anglais : 'Livraison offerte dès 50 €'"}],
    extra_body={"thinking": {"type": "disabled"}}
)

En mode réflexion, temperature, presence_penalty et frequency_penalty ne sont pas pris en compte, et toute valeur de top_p inférieure à 0,95 est ramenée à 0,95. Pour des sorties plus stables d’un appel à l’autre, désactivez la réflexion. Hors réflexion, DeepSeek recommande une température de 1,0, et un top_p de 0,95 pour les usages d’agent.

La facturation : cache, heures creuses et raisonnement

Trois mécanismes font varier la facture du simple au décuple : le cache, l’heure d’envoi et la quantité de raisonnement. Voici la grille en vigueur, en dollars par million de tokens.

Le cache automatique

Le cache fonctionne sans réglage. Quand une requête commence par le même contenu qu’une requête récente, la partie commune est servie depuis le cache et facturée cinquante fois moins cher sur V4.1-Flash. Le système découpe le contexte en unités (fin du message utilisateur, fin de la réponse, puis blocs réguliers sur les longs textes), et une unité doit correspondre exactement pour être réutilisée. Le cache s’efface après quelques heures ou quelques jours d’inactivité, et DeepSeek précise qu’il fonctionne « au mieux », sans garantie de taux.

Pour en profiter, placez le contenu stable en tête (prompt système, définitions d’outils, schéma de sortie) et le contenu variable à la fin. Un pipeline de classification qui réutilise le même prompt système sur des milliers de textes voit ainsi l’essentiel de son entrée passer au tarif du cache.

Les heures pleines et les heures creuses

Depuis le 16 août 2026, l’API facture le double de 1 h à 4 h et de 6 h à 10 h UTC, du lundi au vendredi, hors jours fériés chinois. En heure d’été française, les heures pleines vont donc de 3 h à 6 h et de 8 h à 12 h. Le reste du temps, le tarif est divisé par deux, sans paramètre à activer : seule compte l’heure d’arrivée de la requête. Vous pouvez donc planifier vos traitements par lots l’après-midi ou le soir, et réserver les heures pleines aux requêtes interactives qui ne peuvent pas attendre.

Le raisonnement, facturé comme de la sortie

Les tokens de réflexion sont facturés au tarif de sortie, le plus cher. Sur une tâche simple, un effort max inutile peut multiplier le coût par dix sans améliorer le résultat. Mesurez, puis choisissez le niveau minimal qui atteint votre seuil de qualité.

L’appel d’outils et les agents

L’appel d’outils fonctionne comme chez OpenAI. Vous décrivez vos fonctions dans un tableau tools, le modèle décide quand les appeler, votre code exécute la fonction et renvoie le résultat.

# Appel d'outil, format identique à OpenAI
tools = [{
    "type": "function",
    "function": {
        "name": "chercher_produit",
        "description": "Cherche un produit dans le catalogue.",
        "parameters": {
            "type": "object",
            "properties": {
                "requete": {"type": "string"},
                "categorie": {"type": "string"}
            },
            "required": ["requete"]
        }
    }
}]

response = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "Trouve-moi un clavier ergonomique."}],
    tools=tools,
    tool_choice="auto"
)
appel = response.choices[0].message.tool_calls[0]
print(appel.function.name)       # chercher_produit
print(appel.function.arguments)  # {"requete": "clavier ergonomique"}

Le mode strict

En passant par l’adresse https://api.deepseek.com/beta, vous pouvez activer un mode strict qui force le modèle à respecter exactement le schéma JSON de vos outils. Ce mode accepte les types courants (objet, texte, nombre, entier, booléen, tableau, énumération, anyOf) ainsi que les références $ref et $def. Il reste en bêta.

Réflexion et outils : le piège de production

En mode réflexion, le modèle raisonne, appelle un outil, lit le résultat, raisonne à nouveau et peut enchaîner plusieurs appels avant de répondre. Pour que cette boucle fonctionne, vous devez renvoyer au modèle tout le reasoning_content des tours précédents quand la conversation contient des outils. Sans lui, l’API renvoie une erreur 400. Hors outils, en revanche, le raisonnement des tours précédents peut être omis, car l’API l’ignore.

Les formats Anthropic et Responses permettent aussi d’insérer des appels d’outils en cours de conversation, ce que le format Chat Completions ne permet pas. C’est l’une des raisons pour lesquelles Claude Code et Codex tirent bien parti de DeepSeek.

Images, sortie JSON et fonctions en bêta

Les images

V4.1-Flash accepte les images dans les trois formats, envoyées par adresse web, en base64 ou via l’API de fichiers de DeepSeek, dont le stockage est gratuit. Chaque image est convertie en tokens et facturée au tarif du modèle. V4-Pro, en revanche, ne lit pas les images.

La sortie JSON

La sortie JSON garantit un objet JSON valide. Elle s’active avec response_format={"type": "json_object"}, mais trois conditions s’appliquent. Le mot « json » doit figurer dans le prompt système ou dans le message, de préférence avec un exemple du format attendu. La valeur de max_tokens doit laisser assez de place pour que le JSON ne soit pas tronqué. Enfin, l’API renvoie parfois une réponse vide, et DeepSeek conseille alors d’ajuster le prompt.

# Extraction structurée en JSON
import json

response = client.chat.completions.create(
    model="deepseek-flash",
    messages=[
        {"role": "system", "content": (
            "Extrais les informations en json valide, avec ces clés : "
            "nom_entreprise (texte), ca_meur (nombre), nb_employes (nombre), secteur (texte). "
            'Exemple : {"nom_entreprise": "Atelier Lumen", "ca_meur": 18, '
            '"nb_employes": 120, "secteur": "luminaires"}'
        )},
        {"role": "user", "content": "La brasserie Vent d'Ouest emploie 45 personnes et réalise 6 M€ de chiffre d'affaires."}
    ],
    response_format={"type": "json_object"},
    max_tokens=500
)
donnees = json.loads(response.choices[0].message.content)

La complétion au milieu du code (FIM)

La complétion FIM, en bêta, reçoit le code situé avant le curseur et celui situé après, puis écrit ce qui manque au milieu. Elle passe par l’adresse https://api.deepseek.com/beta, fonctionne sans réflexion et produit au maximum 4 000 tokens. Elle sert à l’autocomplétion dans un éditeur, et l’extension Continue sait l’utiliser.

La complétion à partir d’un début de réponse

Cette autre fonction en bêta permet de rédiger le début de la réponse de l’assistant et de demander au modèle de continuer. Elle force un format sans avoir à le décrire : vous commencez par {"resultat": , et le modèle complète le JSON.

Les réflexes de production

Les limites de requêtes simultanées

DeepSeek limite le nombre de requêtes en cours à 2 500 pour deepseek-flash et 500 pour deepseek-v4-pro. Une requête compte depuis son envoi jusqu’à la fin de la réponse, et une requête de trop reçoit une erreur 429. Vous pouvez demander une hausse de ces limites sans frais. Le paramètre user_id permet en outre d’isoler vos propres utilisateurs, chacun gardant ses limites.

Pendant une attente, le serveur envoie des lignes vides, ou des commentaires de maintien de connexion en streaming. Si l’inférence n’a pas commencé au bout de dix minutes, il ferme la connexion. Réglez vos délais d’attente en conséquence, surtout pour les requêtes à effort max.

Réessayer avec un délai croissant

# Réessais avec délai croissant
import time
from openai import RateLimitError, APIStatusError

def appel_robuste(client, **kwargs):
    for tentative in range(5):
        try:
            return client.chat.completions.create(**kwargs)
        except RateLimitError:
            time.sleep(2 ** tentative)  # 429 : trop de requêtes simultanées
        except APIStatusError as e:
            if e.status_code in (500, 503) and tentative < 4:
                time.sleep(2 ** tentative)  # serveur saturé ou en erreur
            else:
                raise  # 400, 401, 402, 422 : inutile de réessayer
    raise RuntimeError("Échec après 5 tentatives")

Les erreurs 400, 401 et 422 signalent un problème dans la requête ou la clé, et un nouvel essai n’y changera rien. L’erreur 402 indique un solde épuisé : il faut recharger le compte. Les erreurs 429, 500 et 503 justifient en revanche un nouvel essai après un délai.

Suivre le coût en temps réel

Enregistrez pour chaque appel les tokens servis par le cache, les tokens hors cache, les tokens de sortie, l’heure d’envoi et le niveau de réflexion. Avec ce suivi, vous voyez en quelques jours quel prompt système mérite d’être réorganisé pour mieux profiter du cache, quelle route peut passer de V4-Pro à V4.1-Flash, et quel traitement gagnerait à être décalé l’après-midi.

Ce qui est compatible et ce qui diffère

La compatibilité avec OpenAI et Anthropic est élevée, avec quelques écarts à connaître. Voici la carte précise.

Ce qui fonctionne tel quel

• Les messages system, user, assistant et tool gardent la même structure.
• Le streaming renvoie des morceaux au format attendu.
• L’appel d’outils et la sortie JSON suivent le format d’OpenAI.
• Les SDK OpenAI pour Python et Node, LangChain et LlamaIndex fonctionnent en changeant l’adresse.
• Le format Anthropic prend en charge le prompt système, les séquences d’arrêt, le streaming, les outils, les images et la réflexion.

Ce qui diffère ou manque

• Le raisonnement arrive dans le champ reasoning_content, propre à DeepSeek.
• DeepSeek ne propose aucune API d’embeddings, et il faut passer par un autre service pour vectoriser vos textes.
• L’API ne permet pas d’affiner un modèle. L’affinage se fait sur les poids ouverts, en auto-hébergement.
• Aucun point d’accès de modération n’existe, et le filtrage des contenus vous revient.
• DeepSeek n’a pas d’API de traitement par lots à prix réduit, mais les heures creuses jouent un rôle proche.
• Sur le format Anthropic, l’API ignore les directives cache_control, les serveurs MCP, top_k et les blocs de documents.
• DeepSeek ne publie aucun engagement de disponibilité, ce qui rend les réessais et un fournisseur de secours indispensables.

API officielle, hébergeur tiers ou auto-hébergement

Trois voies donnent accès aux modèles. Le bon choix dépend surtout de la sensibilité de vos données et de votre volume.

Pour le prototypage et les projets personnels sans données sensibles, l’API officielle reste imbattable. Pour des données personnelles en Europe, un hébergeur hors de Chine avec un contrat adapté forme le compromis pragmatique. Pour un contrôle total, l’auto-hébergement s’impose, à condition que le volume justifie l’infrastructure.

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

L’API DeepSeek ne convient pas à tout. Sur certains usages précis, elle offre pourtant une qualité suffisante pour un coût très bas.

La classification à grande échelle

Trier des tickets, catégoriser des avis clients ou étiqueter des données d’entraînement se fait très bien avec V4.1-Flash sans réflexion. Avec un prompt système stable et un traitement l’après-midi, le coût tombe à quelques centimes pour des milliers d’éléments.

L’extraction de données structurées

Transformer des factures, des contrats ou des e-mails en JSON devient fiable avec la sortie JSON ou l’appel d’outils en mode strict. La vision de V4.1-Flash permet en plus de traiter directement des documents scannés ou des captures.

Le prototypage d’agents et de RAG

Tester une idée d’agent, un pipeline de RAG ou un assistant interne coûte peu. La compatibilité avec OpenAI permet ensuite de changer de fournisseur sans refonte si les besoins évoluent.

La traduction et le résumé en volume

Traduire une documentation technique ou résumer des centaines de rapports coûte quelques dollars aux heures creuses, là où un modèle haut de gamme en demanderait des dizaines ou des centaines.

Ce qu’il faut retenir

L’API DeepSeek accepte trois formats, sert deux modèles actifs, deepseek-flash et deepseek-v4-pro, et propose l’appel d’outils, la sortie JSON, la vision, la complétion FIM et le début de réponse imposé. La plupart des applications existantes fonctionnent en changeant deux lignes de code.

Sa force reste le prix, à condition de maîtriser trois leviers : le cache, les heures creuses et le niveau de réflexion. Ses limites sont techniques (pas d’embeddings, pas d’affinage par l’API, limites de requêtes simultanées, aucun engagement de disponibilité) et géopolitiques (serveurs en Chine, censure dans les poids, conformité RGPD à assurer ailleurs).