KI API in Python ansprechen: Schritt-für-Schritt-Anleitung

👁 119 Aufrufe

Die erste Anfrage an ein KI-Modell in Python erfordert lediglich zehn Zeilen Code: Sie installieren die OpenAI-Bibliothek, geben Endpunkt und API-Schlüssel an, senden eine Liste von Nachrichten ab und lesen die Antwort aus. Im Folgenden führe ich Sie durch jeden einzelnen Schritt: von der Python-Installation unter Windows über das Erstellen einer virtuellen Umgebung bis hin zu Streaming, Fehlerbehandlung und automatischen Wiederholungsversuchen (Retries). Jeder Beispielcode wurde von Piotr Olszewski am 4. Oktober 2026 unter Windows 11 mit Python 3.13.15 über OpenRouter ausgeführt und zeigt reale Ergebnisse. Dies ist der dritte Schritt des Leitfadens KI-API von Grund auf.

Schritt 1. Python unter Windows installieren

1. Öffnen Sie python.org/downloads und laden Sie das aktuelle Windows-Installationsprogramm herunter (Python 3.13 oder neuer; die openai-Bibliothek setzt mindestens Version 3.10 voraus).
2. Aktivieren Sie im ersten Dialogfenster des Installationsprogramms unbedingt die Option Add python.exe to PATH. Andernfalls findet das Terminal Python nicht - die häufigste Fehlerquelle für Einsteiger.
3. Alternative für die Befehlszeile: winget install Python.Python.3.13.
4. Starten Sie ein neues Terminal (PowerShell oder Windows Terminal) und prüfen Sie die Installation: python --version. Es sollte die Versionsnummer ausgegeben werden und nicht der Microsoft Store aufpoppen.

Sollte sich statt der Versionsnummer der Microsoft Store öffnen, deaktivieren Sie in den Windows-Einstellungen unter Apps → Erweiterte App-Einstellungen → App-Ausführungsaliase die Einträge für python.exe und python3.exe.

Schritt 2. Virtuelle Umgebung einrichten (venv)

Ein venv dient als isolierter Arbeitsbereich für die Abhängigkeiten eines einzelnen Projekts. Auf diese Weise verhindert man, dass Modulversionen verschiedener Vorhaben kollidieren. Die Einrichtung erfolgt einmalig pro Projekt:

mkdir meine-api
cd meine-api
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install openai python-dotenv

Nach der Aktivierung erscheint am Anfang der Terminal-Eingabeaufforderung der Präfix (.venv). Verweigert PowerShell die Ausführung des Skripts, genügt einmalig der Befehl Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. In Git Bash erfolgt die Aktivierung mittels source .venv/Scripts/activate, unter Linux und macOS über source .venv/bin/activate.

Der API-Schlüssel wird in einer Datei namens .env im Hauptverzeichnis des Projekts hinterlegt (als einzelne Zeile: OPENROUTER_API_KEY=sk-or-v1-...). Wie Sie diesen Schlüssel beschaffen und schützen, erklärt der Leitfaden API-Schlüssel: Bezug und Absicherung.

Schritt 3. Die erste API-Anfrage

Hier kommt die offizielle OpenAI-Bibliothek zum Einsatz, jedoch adressiert an den Endpunkt von OpenRouter. Das Datenformat ist identisch, weshalb Sie mit einem einzigen Schlüssel Zugang zu Modellen von OpenAI, Anthropic, Google, DeepSeek und hunderten weiteren Anbietern erhalten. Um das Modell zu wechseln, genügt die Anpassung eines einzigen Textwerts.

"""Erste Anfrage an ein KI-Modell via OpenRouter (OpenAI SDK)."""
import os
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()  # Lädt Umgebungsvariablen aus der Datei .env im aktuellen Verzeichnis

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
)

odpowiedz = client.chat.completions.create(
    model=os.getenv("MODEL", "openai/gpt-6-luna"),
    messages=[
        {"role": "system", "content": "Antworte kurz und präzise."},
        {"role": "user", "content": "Erkläre in zwei Sätzen, was eine API ist."},
    ],
)

print(odpowiedz.choices[0].message.content)
print("---")
print("Modell:", odpowiedz.model)
print("Input-Tokens:", odpowiedz.usage.prompt_tokens)
print("Output-Tokens:", odpowiedz.usage.completion_tokens)
szczegoly = odpowiedz.usage.completion_tokens_details
if szczegoly and szczegoly.reasoning_tokens:
    print("  davon Reasoning-Tokens:", szczegoly.reasoning_tokens)
koszt = getattr(odpowiedz.usage, "cost", None)  # OpenRouter liefert die Kosten in USD
if koszt is not None:
    print(f"Kosten: {koszt:.6f} USD")

Die Funktionsweise Zeile für Zeile:

• load_dotenv() lädt den Schlüssel aus der .env-Datei in die Umgebungsvariablen.
• OpenAI(base_url=..., api_key=...) initialisiert den Client - ohne base_url würde direkt eine Verbindung zu den Servern von OpenAI hergestellt.
• messages enthält den Dialogverlauf: system legt die Rahmenbedingungen fest, user stellt die Anfrage (weitere Details zu Rollen und Parametern finden Sie unter System-Prompt, Temperatur und Kontextfenster).
• odpowiedz.choices[0].message.content enthält die generierte Antwort.
• usage liefert die Token-Zählung, während OpenRouter zusätzlich das Feld cost mit den aufgelaufenen Kosten bereitstellt.

Die gemessene Ausgabe für das Standardmodell GPT-6 Luna (Hinweis: Die ursprüngliche Testabfrage erfolgte auf Polnisch; die Systemantwort wurde hier ins Deutsche übersetzt):

Eine API ist eine Reihe von Regeln und Werkzeugen, über die verschiedene Programme miteinander kommunizieren können. Sie legt fest, wie Anfragen gesendet und Daten oder Funktionen von einem anderen System empfangen werden.
---
Modell: openai/gpt-6-luna
Input-Tokens: 40
Output-Tokens: 58
Kosten: 0.000033 USD (ca. 0.000030 EUR)

Gleicher Testablauf bei Gemini 3.8 Flash (lediglich die Umgebungsvariable MODEL wurde modifiziert; deutsche Übersetzung der polnischen Testantwort):

Eine API (Programmierschnittstelle) ist ein Regelwerk, das es verschiedenen Programmen und Systemen ermöglicht, sicher miteinander zu kommunizieren und Daten auszutauschen. Sie fungiert als Vermittler, der es einer Anwendung erlaubt, Funktionen oder Ressourcen einer anderen zu nutzen, ohne deren internen Aufbau kennen zu müssen.
---
Modell: google/gemini-3.8-flash
Input-Tokens: 29
Output-Tokens: 462
  davon Reasoning-Tokens: 390
Kosten: 0.001754 USD (ca. 0.001569 EUR)

Ein Blick auf die Zähler zeigt: Gemini erzeugte für zwei Sätze insgesamt 462 Output-Tokens, da 390 davon für Denkprozesse („Reasoning“) vor der Antwort aufgewendet wurden. Diese Denk-Tokens werden wie reguläre Generierungen berechnet. Daher beliefen sich die Kosten hier auf ca. 0,001569 EUR (0,001754 USD) - mehr als das Fünfzigfache im Vergleich zu Luna. Bei Budgetkalkulationen ist daher stets das Feld usage maßgeblich, nicht die reine Textlänge der Rückgabe. Vertiefende Informationen finden Sie unter KI-Tokens: Funktionsweise und Abrechnung.

Schritt 4. Streaming: Antworten in Echtzeit empfangen

Ohne Streaming verweilt das Skript im Wartezustand, bis die Ausgabe vollständig berechnet ist, und liefert das Gesamtergebnis auf einmal. Beim Streaming werden Textfragmente sukzessive übertragen, vergleichbar mit der Benutzeroberfläche von ChatGPT. Dies empfiehlt sich für interaktive Interfaces und Anwendungen mit direkter Nutzereinsicht.

"""Streaming: Die Antwort trifft stückweise ein, wie bei ChatGPT."""
import os
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
client = OpenAI(base_url="https://openrouter.ai/api/v1", api_key=os.environ["OPENROUTER_API_KEY"])

strumien = client.chat.completions.create(
    model=os.getenv("MODEL", "openai/gpt-6-luna"),
    messages=[{"role": "user", "content": "Nenne 5 Namensideen für einen Kochblog. Nur eine Liste."}],
    stream=True,
    stream_options={"include_usage": True},  # Das letzte Fragment enthält die Token-Statistik
)

for kawalek in strumien:
    if kawalek.choices and kawalek.choices[0].delta.content:
        print(kawalek.choices[0].delta.content, end="", flush=True)
    if kawalek.usage:  # Trifft ganz am Ende ein
        print(f"\n--- Tokens: {kawalek.usage.prompt_tokens} Input, {kawalek.usage.completion_tokens} Output")

Ausgabe des Testlaufs (die Anfrage wurde im Test auf Polnisch gestellt; hier die deutsche Übersetzung des Resultats):

1. Direkt aus der Pfanne
2. Eine Prise Geschmack
3. Kochen mit Köpfchen
4. Mit der Gabel über den Teller
5. Kulinarischer Hafen
--- Tokens: 20 Input, 439 Output

Beim Streaming wird der Token-Zähler standardmäßig nicht mitgesendet. Er muss explizit über den Parameter stream_options={"include_usage": True} angefordert werden und trifft im finalen Chunk ein.

Schritt 5. Fehlerbehandlung und Wiederholungslogik (Retry)

Im Produktivbetrieb können Netzwerk- und Schnittstellenanfragen scheitern: ungültige Schlüssel, Tippfehler im Modellnamen, Ratenbegrenzungen pro Minute (HTTP 429) oder temporäre Ausfälle des Anbieters (5xx). Die Grundregel lautet:

• Clientseitige Fehler (400, 401, 403, 404) nicht wiederholen - ein neuer Versuch liefert dasselbe Resultat, der Fehler liegt im Code oder in den Zugangsdaten.
• Flüchtige Fehler (429, 500, 502, 503, Verbindungsabbrüche) mit progressiver Verzögerung wiederholen: z. B. 2 s, 4 s, 8 s, ergänzt um einen Zufallsfaktor (Jitter), damit parallele Clients den Dienst nicht zeitgleich erneut überlasten.

"""Fehlerbehandlung: 401, 429, 5xx und Wiederholungen mit exponentiellem Backoff."""
import os, sys, time, random
from dotenv import load_dotenv
import openai
from openai import OpenAI

load_dotenv()
client = OpenAI(
    # BASE_URL kann für lokale Tests auf testy/serwer_429.py umgebogen werden
    base_url=os.getenv("BASE_URL", "https://openrouter.ai/api/v1"),
    api_key=os.environ.get("OPENROUTER_API_KEY", ""),
    max_retries=0,   # Deaktiviert integrierte Retries, um die manuelle Logik zu demonstrieren
    timeout=60,      # Sekunden; verhindert dauerhaftes Hängenbleiben bei Verbindungsproblemen
)


def zapytaj(pytanie, model, proby=4):
    for proba in range(1, proby + 1):
        try:
            r = client.chat.completions.create(model=model, messages=[{"role": "user", "content": pytanie}])
            return r.choices[0].message.content
        except openai.AuthenticationError as e:      # 401: Ungültiger oder inaktiver Schlüssel
            sys.exit(f"401: API-Schlüssel prüfen ({e.message})")
        except openai.PermissionDeniedError as e:    # 403: Kein Zugriff (z. B. Regionssperre, Moderation)
            sys.exit(f"403: Zugriff verweigert ({e.message})")
        except openai.NotFoundError as e:            # 404: Falscher Modellname oder Endpunkt
            sys.exit(f"404: Modell oder Adresse nicht gefunden ({e.message})")
        except openai.BadRequestError as e:          # 400: Syntax- oder Strukturfehler in der Anfrage
            sys.exit(f"400: Anfrage anpassen ({e.message})")
        except (openai.RateLimitError, openai.InternalServerError,
                openai.APIConnectionError, openai.APITimeoutError) as e:
            # 429 (Rate Limit / Guthaben erschöpft), 5xx (Serverausfall), Verbindungsabbruch
            if proba == proby:
                raise
            przerwa = 2 ** proba + random.random()   # 2, 4, 8 s + Zufallsanteil
            kod = getattr(e, "status_code", "Netzwerk")
            print(f"[Versuch {proba}] Fehler {kod}, warte {przerwa:.1f} s...")
            time.sleep(przerwa)
        except openai.APIStatusError as e:           # Weitere Statuscodes, z. B. 402
            sys.exit(f"{e.status_code}: {e.message}")


if __name__ == "__main__":
    model = sys.argv[1] if len(sys.argv) > 1 else os.getenv("MODEL", "openai/gpt-6-luna")
    print(zapytaj("Wie viel ist 17 * 23? Gib nur das Ergebnis an.", model))

Im Praxistest wurden vier Szenarien geprüft. Zunächst der reguläre Aufruf:

391

Anschließend mit fehlerhaftem Schlüssel sowie nicht existierendem Modell (OpenRouter quittiert falsche Modellbezeichner mit 400 statt 404):

401: API-Schlüssel prüfen (Error code: 401 - {'error': {'message': 'User not found.', 'code': 401}})

400: Anfrage anpassen (Error code: 400 - {'error': {'message': 'openai/gpt-7-nie-istnieje is not a valid model ID', 'code': 400}})

Das Testen von HTTP 429 erweist sich im Live-Betrieb oft als schwierig, da hierfür die Ratenbegrenzung gezielt provoziert werden müsste. Daher wurde ein lokaler Mock-Server aufgesetzt, der die ersten beiden Anfragen mit 429 abweist und erst die dritte erfolgreich beantwortet:

"""Mock-API-Server: Weist zwei Anfragen mit 429 ab, beantwortet die dritte regulär.
Dient zur Verifikation der Retry-Logik ohne externe Kosten.

Fenster 1: python testy/serwer_429.py
Fenster 2: set BASE_URL=http://127.0.0.1:8429/v1   (PowerShell: $env:BASE_URL="http://127.0.0.1:8429/v1")
           python 03_bledy_i_retry.py
"""
import json
from http.server import BaseHTTPRequestHandler, HTTPServer

licznik = {"n": 0}


class Obsluga(BaseHTTPRequestHandler):
    def do_POST(self):
        self.rfile.read(int(self.headers.get("Content-Length", 0)))
        licznik["n"] += 1
        if licznik["n"] <= 2:
            kod, tresc = 429, {"error": {"message": "Rate limit exceeded (test)", "code": 429}}
        else:
            kod, tresc = 200, {
                "id": "test-1", "object": "chat.completion", "created": 0, "model": "test-modell",
                "choices": [{"index": 0, "finish_reason": "stop",
                             "message": {"role": "assistant", "content": "391"}}],
                "usage": {"prompt_tokens": 10, "completion_tokens": 1, "total_tokens": 11},
            }
        body = json.dumps(tresc).encode()
        self.send_response(kod)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)
        print(f"Anfrage {licznik['n']} -> {kod}")


HTTPServer(("127.0.0.1", 8429), Obsluga).serve_forever()

[Versuch 1] Fehler 429, warte 2.8 s...
[Versuch 2] Fehler 429, warte 4.2 s...
391

Die Wiederholungslogik griff wie vorgesehen: Nach zwei Abweisungen und Pausen von 2,8 s sowie 4,2 s lieferte der dritte Versuch das Resultat. Das OpenAI-SDK besitzt ebenfalls eine integrierte Wiederholungsfunktion (standardmäßig 2 Versuche, konfigurierbar über max_retries), die hier zugunsten der Anschauung deaktiviert wurde. Im Produktivcode empfiehlt sich meist die SDK-eigene Variante mit max_retries=5.

Drei Praxishinweise für den stabilen Betrieb:

• Timeouts definieren. Ohne explizite Angabe wartet das SDK bis zu 10 Minuten. Bei komplexen Reasoning-Modellen können 60 Sekunden gelegentlich zu knapp bemessen sein; passen Sie den Wert an das Aufgabengebiet an.
• Kosten pro Aufruf protokollieren. Das Mitschreiben des Felds usage.cost liefert nach kurzer Laufzeit verlässlichere Zahlen als theoretische Hochrechnungen.
• HTTP 429 differenziert betrachten. Bei OpenAI signalisiert dieser Statuscode mitunter auch ein erschöpftes Budgetlimit (project_spend_limit_exceeded). In einem solchen Fall helfen Retries nicht weiter.

Alternative Umsetzung in JavaScript (Node.js)

Die offizielle OpenAI-Bibliothek für Node.js folgt einer nahezu identischen Nomenklatur. Getestet wurde unter Node.js 26.10: Nach npm install openai dotenv (Versionen 7.27.0 und 18.0.5) und Setzen von "type": "module" in der package.json deckt das Skript Einzelabfrage, Streaming und Fehlerbehandlung ab.

// Erste API-Anfrage in Node.js via OpenRouter: Standardabfrage und Streaming.
// Ausführung im Verzeichnis: npm install   und anschließend   node erste_anfrage.mjs
import "dotenv/config";          // Lädt .env aus dem aktuellen Verzeichnis
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
});
const model = process.env.MODEL ?? "openai/gpt-6-luna";

// 1. Standardabfrage
const r = await client.chat.completions.create({
  model,
  messages: [
    { role: "system", content: "Antworte kurz." },
    { role: "user", content: "Was unterscheidet JavaScript von Java? Ein Satz." },
  ],
});
console.log(r.choices[0].message.content);
console.log(`--- ${r.usage.prompt_tokens} + ${r.usage.completion_tokens} Tokens, Kosten: ${r.usage.cost} USD\n`);

// 2. Streaming
const strumien = await client.chat.completions.create({
  model,
  messages: [{ role: "user", content: "Nenne drei Flüsse in Polen. Nur Namen, kommagetrennt." }],
  stream: true,
});
for await (const kawalek of strumien) {
  process.stdout.write(kawalek.choices[0]?.delta?.content ?? "");
}
console.log();

// 3. Fehlerbehandlung: Ungültiges Modell
try {
  await client.chat.completions.create({ model: "nicht/vorhanden", messages: [{ role: "user", content: "test" }] });
} catch (e) {
  if (e instanceof OpenAI.APIError) console.log(`Fehler ${e.status}: ${e.message}`);
  else throw e;
}

Die Testausgabe unter Node.js (die Abfragen wurden im Test auf Polnisch durchgeführt; Text hier ins Deutsche übertragen):

JavaScript ist eine dynamische Skriptsprache, die überwiegend im Browser eingesetzt wird, während Java eine statisch typisierte, objektorientierte Sprache für die JVM ist.
--- 39 + 54 Tokens, Kosten: 0.0000309 USD (ca. 0.0000276 EUR)

Weichsel, Oder, Warthe
Fehler 400: 400 nicht/vorhanden is not a valid model ID

Die syntaktischen Abweichungen zu Python sind gering: baseURL statt base_url, await vor API-Aufrufen sowie for await bei Stream-Iteratoren. Auch in Node.js gehört der API-Schlüssel in die .env-Datei und darf niemals in clientseitigen Browser-Code gelangen.

Skripte zum Download

Sämtliche Skripte aus diesem Leitfaden stehen im Paket API-Starter-Archiv mitsamt Beispieldatei .env.example bereit. Nach dem Entpacken und Eintragen des API-Schlüssels lässt sich der Code direkt via python 01_pierwsze_zapytanie.py starten.

Nächste Schritte

• Modellparameter gezielt steuern: System-Prompt, Temperatur, Kontextfenster und Max Tokens.
• Antworten in validem JSON erzwingen: Structured Outputs Schritt für Schritt.
• Aufwände kalkulieren: API-Kostenrechner für KI-Modelle.
• Automatisierung: Leitfaden KI-Agenten von Grund auf sowie der erste funktionale Agent in Python.

Häufig gestellte Fragen (FAQ)

Muss für OpenAI-Modelle zwingend OpenRouter genutzt werden?

Nein. Liegt ein direkter API-Schlüssel von OpenAI vor, entfällt der Parameter base_url und das Modell wird ohne Anbieter-Präfix adressiert (z. B. gpt-6-luna). Entsprechende Konfigurationen für OpenAI, Anthropic und Google finden sich im Beitrag zu API-Schlüsseln.

Fehlermeldung: ModuleNotFoundError: No module named ‚openai‘. Was ist die Ursache?

Das Modul wurde in einer anderen Python-Umgebung installiert als der, aus der der Aufruf erfolgt. Aktivieren Sie die virtuelle Umgebung (.venv\Scripts\Activate.ps1) und wiederholen Sie die Installation, oder rufen Sie den Interpreter direkt über .venv\Scripts\python auf.

Warum erscheint KeyError: ‚OPENROUTER_API_KEY‘?

Das Skript kann die Umgebungsvariable nicht finden. Prüfen Sie, ob die Datei exakt .env heißt (unter Windows wird gelegentlich unbemerkt .txt angehängt), ob sie im aktuellen Ausführungsverzeichnis liegt und keine Leerzeichen um das Gleichheitszeichen enthält.

Chat Completions API oder Responses API?

Für Neuentwicklungen verweist OpenAI auf die modernere Responses API. Die Chat Completions API bleibt jedoch uneingeschränkt funktionsfähig und stellt den de-facto Standard dar, der von OpenRouter, DeepSeek, Mistral sowie lokalen Schnittstellen wie Ollama unterstützt wird. Daher nutzt diese Einführung das universell einsetzbare Chat-Completions-Format.

Mit welchen Kosten ist beim Ausprobieren zu rechnen?

Die Beträge für erste Tests liegen im Centbereich. Alle in diesem Artikel gezeigten Aufrufe verursachten Gesamtkosten von etwa einem halben US-Cent (ca. 0,0045 EUR). Zudem stehen auf Plattformen wie OpenRouter kostenfreie Modellvarianten (gekennzeichnet mit :free) oder kostenlose Testkontingente bei Gemini bereit.

Quellen und Überprüfungsdatum

• openai-python - Offizielles Python SDK
• openai-node - Offizielles Node.js SDK
• OpenRouter - Quickstart-Dokumentation
• OpenRouter - API-Fehlercodes
• Python Documentation - venv-Modul
• python.org - Offizielle Downloads für Windows

// weiterlesenWie ein Meme erstellen mit AI: Schritt für SchrittAnleitungenWie den Textstil verbessern mit KI: Schritt für SchrittAnleitungenWie Content-Ideen generieren mit KI: Schritt für SchrittAnleitungen

Kinetyra