Die Anbindung der DeepSeek API ist an sich nicht kompliziert. Wirklich hängen bleiben Teams an drei Dingen: zu welcher Plattform der Key gehört, ob die Base URL vollständig ist und ob der Modellname der aktuellen Version entspricht. Viele „Aufrufe funktionieren nicht“ sind kein Modellproblem, sondern eine nicht zusammenpassende Kombination aus Zugangsdaten und Adresse.
Dieser Artikel beginnt mit Registrierung, Aufladung und Key-Erstellung, führt dann den ersten curl- und Python-Aufruf durch und erklärt anschließend Streaming, den Thinking-Modus, max_tokens und häufige Fehler. Wer die Schritte einmal durchläuft, hat die Verbindung in der Regel laufen.
Hinweis: DeepSeek ist eine Marke ihres jeweiligen Inhabers; dieser Artikel steht in keiner Verbindung zu DeepSeek. Modellnamen, Parameter und Limits können sich mit Versionen ändern. Der Beitrag beschreibt die übliche Form der offiziellen Dokumentation im Oktober 2026; maßgeblich sind die offizielle Dokumentation und unsere Modellpreise.
1. Vor dem Start vier Dinge auseinanderhalten
Fehlgeschlagene API-Anbindungen liegen meist nicht an der Modellfähigkeit, sondern daran, dass diese vier Objekte nicht zusammenpassen:
| Objekt | Funktion | Häufigster Fehler |
|---|---|---|
| Konto | Bestimmt Guthaben, Abrechnung und Zuordnung des Keys | Key von Plattform A mit Adresse von Plattform B kombinieren |
| API Key | Identitätsnachweis | Beim Kopieren Leerzeichen, Zeilenumbrüche oder Anführungszeichen übernommen |
| Base URL | An welchen Einstiegspunkt die Anfrage geht | /v1 fehlt oder offizielle Adresse und Gateway-Adresse werden vermischt |
| Modellname | Feld model in der Anfrage |
Veralteter Name aus einem alten Artikel |
Die Merkregel ist einfach: Key und Base URL gehören immer als Paar zusammen. Ein offizieller Key passt nur zum offiziellen Zugang, ein Gateway-Key nur zum Gateway. Eine Mischung führt meist direkt zu 401.
2. Registrieren, aufladen, Key erstellen
Am Beispiel der offiziellen Plattform:
- Öffnen Sie die DeepSeek-Entwicklerplattform und registrieren oder melden Sie sich an.
- Schließen Sie die auf der Seite verlangten Prüfungen ab und wechseln Sie zur Aufladung.
- Laden Sie zunächst einen kleinen Betrag auf und starten Sie Batch-Aufgaben erst, wenn die Gutschrift bestätigt ist.
- Öffnen Sie die Seite API Keys, erstellen Sie einen neuen Key und benennen Sie ihn nach Zweck, etwa
deepseek-testoderdeepseek-prod. - Kopieren Sie den Key und speichern Sie ihn sofort in einem Passwortmanager oder als serverseitige Umgebungsvariable; nach dem Schließen der Seite wird der vollständige Wert meist nicht mehr angezeigt.
- Legen Sie getrennte Keys für Test und Produktion an und richten Sie Budget- oder Nutzungsalarme ein.
Beim ZSQH AI Gateway ist der Ablauf ähnlich: Konto auf der Registrierungsseite erstellen, im Kundenportal Key anlegen und aufladen, dann wie weiter unten beschrieben OpenAI-kompatibel aufrufen. Verwenden Sie auf beiden Seiten nicht denselben Key; sonst lässt sich bei Problemen kaum unterscheiden, ob Guthaben, Ratenlimit oder Konfiguration die Ursache ist.
3. Base URL und Modellname: erst prüfen, dann programmieren
Die offizielle Dokumentation nennt als OpenAI-kompatiblen Zugang aktuell https://api.deepseek.com, der Chat-Pfad ist /chat/completions. Manche älteren Anleitungen verwenden https://api.deepseek.com/v1; ob das funktioniert, richtet sich nach der aktuellen offiziellen Dokumentation. Im Zweifel zuerst die Adresse aus dem offiziellen Beispiel verwenden.
| Punkt | Offizielle Direktanbindung | ZSQH AI Gateway |
|---|---|---|
| Base URL | https://api.deepseek.com |
https://ai.zhongshangqihang.com/v1 |
| Chat-Pfad | /chat/completions |
/v1/chat/completions |
| Key-Quelle | Offizielle Plattform | Gateway-Konsole |
| Modellname | Laut offizieller Dokumentation | Laut Modellpreisen |
| Geeignet für | Nur DeepSeek, stabiler offizieller Zugang und Zahlung | Einheitlicher Zugang, mehrere Modelle oder Abrechnung in RMB |
Stand Oktober 2026 listet die offizielle Dokumentation die Modellnamen deepseek-flash und deepseek-v4-pro; die Namen deepseek-chat und deepseek-reasoner aus älteren Artikeln sind nicht zwingend weiterhin verfügbar. Füllen Sie Modellnamen nicht aus dem Gedächtnis aus, sondern gleichen Sie sie vor dem Aufruf mit der offiziellen Dokumentation oder der Preisübersicht ab.
4. Erster curl-Aufruf: zuerst die minimale Anfrage
Deaktivieren Sie zunächst Thinking, um Variablen zu reduzieren. Beispiel für den offiziellen Zugang:
export DEEPSEEK_API_KEY="sk-IHR_KEY"
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": "Antworte nur mit OK"}],
"thinking": {"type": "disabled"},
"max_tokens": 32
}'
Wenn 200 zurückkommt und choices[0].message.content Inhalt enthält, stimmen Key, Base URL und Modellname. Beim Gateway ersetzen Sie nur die URL durch https://ai.zhongshangqihang.com/v1/chat/completions und verwenden den Gateway-Key.
Beachten Sie, dass thinking ein DeepSeek-spezifischer Parameter ist und nicht von jedem OpenAI-kompatiblen Dienst unterstützt wird. Wenn das Gateway ihn nicht unterstützt, entfernen Sie das Feld oder verwenden Sie die im Gateway dokumentierte Entsprechung.
5. Erster Python-Aufruf mit dem OpenAI SDK
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DEEPSEEK_API_KEY"],
base_url="https://api.deepseek.com", # beim Gateway: https://ai.zhongshangqihang.com/v1
)
resp = client.chat.completions.create(
model="deepseek-flash",
messages=[
{"role": "system", "content": "Du bist ein technischer Assistent. Antworte knapp."},
{"role": "user", "content": "Erkläre in drei Sätzen, was eine Vektordatenbank ist."},
],
max_tokens=512,
extra_body={"thinking": {"type": "disabled"}},
)
print(resp.choices[0].message.content)
print(resp.usage)
Das OpenAI SDK kennt das Feld thinking nicht und überträgt es deshalb über extra_body. Prüfen Sie nach dem ersten erfolgreichen Aufruf usage: wie viele Eingabe- und Ausgabe-Tokens anfallen, ob Cache-Treffer ausgewiesen werden und ob Denkinhalte separat gezählt werden. Diese Werte sind für Kosten- und Timeout-Planung aussagekräftiger als ein Gefühl von „schnell oder langsam“.
6. Streaming und reasoning_content
Thinking ist standardmäßig aktiv und die Standardstärke ist high. Bei aktivem Thinking enthält die Antwort reasoning_content auf derselben Ebene wie der endgültige Text content; im Streaming wird der Denkinhalt blockweise in delta.reasoning_content zurückgegeben.
stream = client.chat.completions.create(
model="deepseek-flash",
messages=[{"role": "user", "content": "Schreibe ein Python-Beispiel zum Einlesen einer CSV-Datei."}],
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("Denkprozess:", "".join(reasoning))
print("Endgültige Antwort:", "".join(answer))
Bei mehrstufigen Dialogen mit tools in der Anfrage muss reasoning_content der vorherigen Runde vollständig zurückgesendet werden, sonst kann ein 400 zurückkommen. Ohne tools kann das Feld entfallen; der Dienst ignoriert es dann. Gegenüber Endnutzern sollte der Denkinhalt eingeklappt dargestellt werden und nicht standardmäßig vollständig ausgebreitet werden.
7. max_tokens, temperature und thinking passend konfigurieren
| Aufgabe | Thinking | Empfohlener Startwert | Erläuterung |
|---|---|---|---|
| Verbindungstest | Aus | max_tokens 32–128 | Es wird nur eine kurze Antwort benötigt |
| Klassifikation, Extraktion | Aus | 256–1024 | Strukturierte Ausgabe reduziert Denkaufwand |
| Kundendienst, Textarbeit | Ein | 1024–4096 | Effort je nach Ergebnis anpassen |
| Code, komplexe Schlussfolgerung | Ein | 4096 oder mehr | Ausreichend Budget für den Denkprozess |
Die offizielle Dokumentation nennt aktuell eine Kontextlänge von 1 Mio. Tokens und einen Bereich für max_tokens von 1 bis 384K. Ohne Angabe gelten standardmäßig 8K ohne Thinking und 64K mit Thinking; bei reasoning_effort auf max liegt der Standard bei 128K. Diese Werte können sich ändern; maßgeblich ist die offizielle Dokumentation.
Im Thinking-Modus wirken temperature, presence_penalty und frequency_penalty nicht. Ihre Änderung erzeugt keinen Fehler, verändert aber das Ergebnis nicht. Auch max_tokens darf nicht zu klein gewählt werden: Der Denkprozess verbraucht Ausgabebudget; ist es zu knapp, wird möglicherweise noch vor dem eigentlichen Text abgeschnitten.
8. Fehlersuche bei 401, 402, 429 und Timeouts
| Symptom | Häufige Ursache | Behandlung |
|---|---|---|
| 401 | Falscher Key, fehlendes Bearer, Key und Base URL gehören nicht zur selben Plattform | Key erneut kopieren, Header prüfen, Zugang zuordnen |
| 402 | Guthaben des Kontos reicht nicht | Nach Aufladung erneut versuchen; zuerst Guthaben prüfen, dann Code ändern |
| 429 | Zu schnelle Anfragen, Parallelität oder QPS überschritten | Parallelität senken, exponentielles Backoff, Keys nach Projekt trennen |
| 400/422 | Ungültige Parameter, Modellname oder Kontext | Fehlermeldung lesen, Modellname und max_tokens prüfen |
| Timeout | Netzwerk, lange Ausgabe, Thinking-Dauer | Verbindungs- und Lese-Timeout getrennt setzen, Ausgabe begrenzen |
| 500/503 | Upstream-Fehler oder Überlastung | Kurz warten, dann mit Backoff wiederholen |
Das Parallelitätslimit bei 429 wird pro Konto gezählt, nicht gleichmäßig auf einzelne Keys verteilt. Mehrere Keys unter demselben Konto teilen das Kontingent; „mehr Keys anlegen“ umgeht die Parallelitätsgrenze daher nicht. Laut offizieller Dokumentation wird die Verbindung getrennt, wenn innerhalb von 10 Minuten keine Inferenz beginnt; der Client muss dies erkennen und erneut versuchen.
9. Key-Sicherheit: mindestens fünf Dinge vor dem Produktivstart
- Keys nur in serverseitigen Umgebungsvariablen oder einem Secret-Manager speichern, nicht in Frontend, Repository oder Logs.
- Je einen Key für Test, Staging und Produktion verwenden, damit Probleme schnell lokalisiert und Dienste gezielt gestoppt werden können.
- Guthabenalarme oder Ausgabenobergrenzen einrichten, um bei auffälligen Aufrufen sofort zu bremsen.
- In Logs nur Key-Präfix oder Fingerprint erfassen, nie den vollständigen Wert.
- Bei Personalwechsel oder Verdacht auf Offenlegung sofort rotieren und die letzten Nutzungsdaten prüfen.
10. Vom offiziellen Zugang zum Gateway: nur zwei Stellen ändern
Ändern Sie bei der Migration zuerst base_url und api_key und bestätigen Sie den Modellnamen anhand der Gateway-Preisübersicht; der übrige Request-Body bleibt möglichst unverändert. Vergleichen Sie mit denselben echten Prompts Ausgabe, Laufzeit und usage und beobachten Sie 3–7 Tage, bevor Sie die Produktion umstellen. Behalten Sie die offizielle Direktanbindung als Ausweichkanal, um bei Problemen schnell zurückzurollen.
Für einen einheitlichen Zugang oder Multi-Modell-Abrechnung können Sie im ZSQH AI Gateway einen Test-Key erstellen; Preise und verfügbare Modelle stehen in den Modellpreisen.
Weiterlesen:
- DeepSeek API über Relay und Proxy: Preis, Stabilität und Migration
- DeepSeek API Preise und Abrechnung
- Modellpreise und Abrechnung
Häufige Fragen
Muss die Base URL nun /v1 enthalten?
Maßgeblich ist das aktuelle offizielle Beispiel. Der offizielle OpenAI-kompatible Zugang lautet https://api.deepseek.com, der Chat-Pfad /chat/completions; Gateways verwenden üblicherweise das Präfix /v1. Raten Sie nicht anhand alter Anleitungen, sondern testen Sie zuerst die vollständige Adresse mit curl.
Ist 401 ein falscher Key oder fehlendes Guthaben?
401 bedeutet fehlgeschlagene Authentifizierung. Prüfen Sie zuerst, ob der Key korrekt ist, ob Bearer mitgesendet wird und ob Key und Base URL zur selben Plattform gehören. Fehlendes Guthaben führt üblicherweise zu 402; die beiden Fälle sollten nicht vermischt werden.
Sollte Thinking beim ersten Aufruf aktiv sein?
Empfohlen ist zunächst „aus“, um mit der kürzesten Anfrage die Verbindung zu bestätigen. Erst wenn Key, Adresse und Modellname stimmen, aktivieren Sie Thinking je nach Aufgabe und beginnen mit einem niedrigeren reasoning_effort.
Welcher max_tokens-Wert ist sinnvoll?
Wählen Sie zunächst einen für die Aufgabe ausreichenden Wert und straffen Sie ihn nach dem ersten Lauf. Klassifikation und Extraktion können mit einigen Hundert beginnen, lange Texte und Code brauchen einige Tausend. Im Thinking-Modus muss Budget für den Denkprozess bleiben; ist es zu klein, wird der eigentliche Text abgeschnitten.
Kann ein offizieller Key direkt mit der Gateway-Adresse verwendet werden?
Nein. Ein offizieller Key gehört nur zum offiziellen Zugang, ein Gateway-Key nur zum Gateway. Eine Mischung führt meist zu 401. Beim Wechsel des Zugangs müssen Key und Base URL gemeinsam getauscht werden.
