L'intégration de l'API DeepSeek n'est pas compliquée en soi. Trois choses bloquent le plus souvent : à quelle plateforme appartient la clé, si l'URL de base est complète, et si le nom du modèle correspond à la version actuelle. Beaucoup d'échecs « d'appel » ne viennent pas des capacités du modèle, mais d'un décalage entre les identifiants et l'adresse.

Cet article part de l'inscription, de la recharge et de la création de clé, puis réalise dans l'ordre le premier appel curl et Python, avant de détailler le streaming, le mode thinking, max_tokens et les erreurs fréquentes. En suivant les étapes, vous devriez pouvoir faire fonctionner toute la chaîne d'intégration.

Remarque : DeepSeek est une marque de son détenteur ; cet article n'a aucun lien d'affiliation avec DeepSeek. Les noms de modèles, paramètres et limites peuvent évoluer selon les versions. Cet article décrit les formes courantes de la documentation d'octobre 2026 ; la documentation du fournisseur et la page Tarifs des modèles font foi.

1. Quatre éléments à distinguer avant l'intégration

Un échec d'intégration API vient le plus souvent d'un décalage entre quatre objets, et non des capacités du modèle :

Objet Rôle Erreur la plus fréquente
Compte Détermine le solde, la facturation et l'appartenance des clés Utiliser une clé de la plateforme A avec l'adresse de la plateforme B
Clé API Justificatif d'identité Coller avec des espaces, sauts de ligne ou guillemets
URL de base Point d'entrée des requêtes Oublier /v1, ou mélanger adresse du fournisseur et adresse de passerelle
Nom du modèle Champ model de la requête Reprendre un nom obsolète trouvé dans un ancien article

La règle de mémoire est simple : la clé et l'URL de base vont toujours par paire. Une clé du fournisseur ne va qu'avec l'entrée du fournisseur, une clé de passerelle qu'avec l'entrée de la passerelle ; un mélange renvoie généralement une erreur 401.

2. Inscription, recharge et création de clé

Prenons l'exemple de la plateforme ouverte du fournisseur :

  1. Ouvrez la plateforme DeepSeek, inscrivez-vous et connectez-vous.
  2. Suivez les vérifications demandées, puis ouvrez la page de recharge.
  3. Commencez par un petit montant et vérifiez que le crédit est bien arrivé avant de lancer des tâches en lot.
  4. Ouvrez la page API Keys, créez une clé et donnez-lui un nom explicite, par exemple deepseek-test ou deepseek-prod.
  5. Copiez la clé et enregistrez-la immédiatement dans un gestionnaire de mots de passe ou une variable d'environnement côté serveur ; la page ne l'affiche généralement plus en entier après fermeture.
  6. Créez des clés distinctes pour le test et la production, et configurez des alertes de budget ou de consommation.

Avec ZSQH AI Gateway, le processus est similaire : créez un compte sur la page d'inscription, puis créez une clé, rechargez et appelez selon le mode compatible OpenAI décrit plus bas. Ne partagez pas la même clé entre les deux plateformes, sinon il sera difficile de savoir si le problème vient du solde, de la limitation de débit ou de la configuration.

3. URL de base et nom de modèle : vérifier avant de coder

La documentation du fournisseur indique actuellement comme entrée compatible OpenAI https://api.deepseek.com, avec le chemin de complétion de chat /chat/completions. Certains anciens tutoriels mentionnent https://api.deepseek.com/v1 ; la disponibilité dépend de la documentation actuelle. En cas de doute, utilisez d'abord l'adresse de l'exemple du fournisseur.

Élément Accès direct ZSQH AI Gateway
URL de base https://api.deepseek.com https://ai.zhongshangqihang.com/v1
Chemin de chat /chat/completions /v1/chat/completions
Source de la clé Plateforme ouverte du fournisseur Console de la passerelle
Nom du modèle Selon la documentation du fournisseur Selon la page Tarifs des modèles
Convient à Usage exclusif de DeepSeek, accès et paiement fluides Point d'entrée unifié, multi-modèles ou facturation en yuans

En octobre 2026, la documentation du fournisseur liste les modèles deepseek-flash et deepseek-v4-pro ; les noms deepseek-chat et deepseek-reasoner cités dans d'anciens articles ne sont pas forcément encore disponibles. Ne remplissez pas le nom de modèle de mémoire : vérifiez-le dans la documentation ou sur la page Tarifs avant l'appel.

4. Premier appel curl : valider la requête minimale

Désactivez d'abord le mode thinking pour réduire les variables. Exemple avec l'entrée du fournisseur :

export DEEPSEEK_API_KEY="sk-votre-clé"

curl "https://api.deepseek.com/chat/completions" \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-flash",
    "messages": [{"role": "user", "content": "Réponds seulement OK"}],
    "thinking": {"type": "disabled"},
    "max_tokens": 32
  }'

Si vous recevez un code 200 avec du contenu dans choices[0].message.content, les trois éléments clé, URL de base et nom de modèle sont corrects. Avec la passerelle, remplacez simplement l'URL par https://ai.zhongshangqihang.com/v1/chat/completions et utilisez une clé de passerelle.

Attention : thinking est un paramètre d'extension propre à DeepSeek et n'est pas pris en charge par tous les services compatibles OpenAI. Si la passerelle ne le prend pas en charge, retirez ce champ ou utilisez le paramètre équivalent indiqué dans sa documentation.

5. Premier appel Python : utiliser le SDK OpenAI

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",  # Avec la passerelle : https://ai.zhongshangqihang.com/v1
)

resp = client.chat.completions.create(
    model="deepseek-flash",
    messages=[
        {"role": "system", "content": "Tu es un assistant technique francophone. Réponds de manière concise."},
        {"role": "user", "content": "Explique en trois phrases ce qu'est une base de données vectorielle."},
    ],
    max_tokens=512,
    extra_body={"thinking": {"type": "disabled"}},
)

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

Le SDK OpenAI ne reconnaît pas le champ thinking, il faut donc le passer via extra_body. Une fois l'appel réussi, examinez usage : nombre de tokens en entrée et en sortie, indication éventuelle du cache, et comptage séparé du contenu de raisonnement. Ces données guident mieux le coût et les timeouts que l'impression de rapidité.

6. Streaming et reasoning_content

Le mode thinking est activé par défaut, avec une intensité par défaut high. Lorsqu'il est actif, la réponse contient reasoning_content, au même niveau que le contenu final content ; en streaming, il est renvoyé bloc par bloc dans delta.reasoning_content.

stream = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "Écris un exemple Python de lecture de fichier CSV"}],
    stream=True,
    max_tokens=4096,
    reasoning_effort="high",
    extra_body={"thinking": {"type": "enabled"}},
)

reasoning, answer = [], []
for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta
    if getattr(delta, "reasoning_content", None):
        reasoning.append(delta.reasoning_content)
    if delta.content:
        answer.append(delta.content)

print("Raisonnement :", "".join(reasoning))
print("Réponse finale :", "".join(answer))

En conversation multi-tours, si la requête contient tools, le reasoning_content du tour précédent doit être renvoyé intégralement, sinon une erreur 400 peut survenir ; sans tools, il peut être omis et le serveur l'ignore. Pour les utilisateurs finaux, mieux vaut replier le contenu de raisonnement plutôt que de l'afficher entièrement par défaut.

7. Configurer max_tokens, temperature et thinking

Tâche Thinking Point de départ conseillé Remarque
Test de connectivité Désactivé max_tokens 32–128 Une réponse courte suffit
Classification, extraction Désactivé 256–1024 Sortie structurée, moins de raisonnement
Support, rédaction Activé 1024–4096 Ajuster effort selon le résultat
Code, raisonnement complexe Activé 4096 et plus Laisser assez de budget au raisonnement

La documentation indique actuellement une fenêtre de contexte de 1M tokens et une plage max_tokens de 1 à 384K. Sans valeur explicite, la valeur par défaut est 8K hors thinking et 64K avec thinking ; avec reasoning_effort à max, elle passe à 128K. Ces chiffres peuvent évoluer ; référez-vous à la documentation du fournisseur.

En mode thinking, temperature, presence_penalty et frequency_penalty ne prennent pas effet : les modifier ne provoque pas d'erreur, mais ne change pas le résultat. max_tokens ne doit pas non plus être trop bas : le raisonnement consomme le budget de sortie, et un budget trop faible peut tronquer la réponse avant même le début du texte final.

8. Diagnostiquer 401, 402, 429 et les timeouts

Symptôme Cause fréquente Traitement
401 Clé erronée, Bearer absent, clé et URL de base de plateformes différentes Recopier la clé, vérifier l'en-tête, confirmer la correspondance de l'entrée
402 Solde insuffisant Recharger puis réessayer ; vérifier le solde avant de modifier le code
429 Requêtes trop rapides, concurrence ou QPS dépassé Réduire la concurrence, backoff exponentiel, séparer les clés par projet
400/422 Paramètre, nom de modèle ou contexte invalide Lire le message, vérifier le nom du modèle et max_tokens
Timeout Réseau, sortie longue, durée du raisonnement Régler séparément les timeouts de connexion et de lecture, limiter la sortie
500/503 Erreur ou surcharge du service amont Attendre brièvement puis réessayer avec backoff

La limite de concurrence d'une 429 est calculée par compte, et non répartie entre les clés. Plusieurs clés d'un même compte partagent le quota ; « créer plus de clés » ne contourne donc pas la limite. La documentation précise aussi que la connexion est coupée si le raisonnement n'a pas commencé dans les 10 minutes ; le client doit savoir identifier ce cas et réessayer.

9. Sécurité des clés : au moins cinq actions avant la production

  1. Stocker les clés uniquement dans des variables d'environnement côté serveur ou un gestionnaire de secrets, jamais dans un front-end, un dépôt ou un journal.
  2. Utiliser une clé distincte pour le test, la préproduction et la production, afin de localiser et de suspendre rapidement un problème.
  3. Configurer une alerte de solde ou un plafond de consommation pour limiter les pertes en cas d'appel anormal.
  4. Ne journaliser que le préfixe ou l'empreinte de la clé, jamais sa valeur complète.
  5. En cas de changement de personnel ou de suspicion de fuite, effectuer une rotation immédiate et vérifier les consommations récentes.

10. Passer du fournisseur à la passerelle : deux modifications

Lors de la migration, changez d'abord base_url et api_key, puis reconfirmez les noms de modèles sur la page Tarifs de la passerelle en conservant autant que possible le reste du corps de requête. Comparez les sorties, les durées et usage sur un même lot d'invites réelles, observez 3 à 7 jours avant de basculer la production. Conservez l'accès direct comme canal de secours pour pouvoir revenir en arrière rapidement.

Si vous avez besoin d'un point d'entrée unifié ou d'une facturation multi-modèles, vous pouvez créer une clé de test sur ZSQH AI Gateway ; les prix et les modèles disponibles figurent sur la page Tarifs des modèles.

Questions fréquentes

Faut-il ajouter /v1 à l'URL de base ?

Référez-vous à l'exemple actuel de la documentation. L'entrée compatible OpenAI du fournisseur est écrite https://api.deepseek.com, avec le chemin de chat /chat/completions ; une passerelle utilise généralement le préfixe /v1. Ne devinez pas à partir d'anciens tutoriels : testez d'abord l'adresse complète avec curl.

Une 401 vient-elle d'une clé erronée ou d'un solde insuffisant ?

Une 401 est un échec d'authentification : vérifiez d'abord si la clé est correcte, si le Bearer est présent et si la clé et l'URL de base appartiennent à la même plateforme. Un solde insuffisant renvoie généralement une 402 ; ne confondez pas les deux.

Faut-il activer thinking au premier appel ?

Je conseille de le désactiver d'abord et de confirmer la chaîne avec la requête la plus courte. Une fois la clé, l'adresse et le nom du modèle validés, activez-le selon la tâche et commencez par un reasoning_effort peu élevé.

Quelle valeur choisir pour max_tokens ?

Donnez d'abord une valeur suffisante pour la tâche, puis resserrez après validation. La classification et l'extraction peuvent commencer à quelques centaines, les textes longs et le code à quelques milliers ; en mode thinking, laissez un budget au raisonnement, sinon le texte final risque d'être tronqué.

Une clé du fournisseur peut-elle être utilisée avec l'adresse d'une passerelle ?

Non. Une clé du fournisseur ne correspond qu'à l'entrée du fournisseur, une clé de passerelle qu'à l'entrée de la passerelle ; un mélange renvoie généralement une 401. Lors d'un changement d'entrée, la clé et l'URL de base doivent être remplacées ensemble.

À lire également :