Die API: Ihre ersten echten Calls

# Die APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen →: Ihre ersten echten Calls

Der schnellste Weg, aus dem ChatGPT-Fenster herauszuwachsen, ist, dasselbe Modell aus Ihrem eigenen Code heraus antworten zu lassen, und bei OpenAI sind das etwa zehn Zeilen. Diese Lektion dreht sich um diese zehn Zeilen: was OpenAI-spezifisch ist, warum die Responses APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen → jetzt der Standard ist und wie Sie TokensTokensA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.Vollständige Definition ansehen → streamen, sobald sie eintreffen.

Einmal einrichten, dann vergessen

Holen Sie sich einen Key auf der API-keys-Seite. Behandeln Sie ihn wie ein Passwort: ErErThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → hängt am Billing, und wer ihn hat, kann Ihr Guthaben ausgeben. Fügen Sie ihn nie in Code ein und committen Sie ihn nie in git.

Setzen Sie ihn als Umgebungsvariable, damit das SDK ihn automatisch findet:

export OPENAI_API_KEY="sk-proj-..."
pip install openai

Das offizielle Python-SDK liest OPENAI_API_KEY von selbst, Sie schreiben den Key also nie in Ihr Skript. Eine wichtige Abgrenzung: Ihr APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen →-Account und Ihr ChatGPT-Abo sind getrennt. ChatGPT Plus oder Pro gibt Ihnen kein APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen →-Guthaben, und APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen →-Nutzung wird pro TokenTokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.Vollständige Definition ansehen → gegen ein anderes Konto abgerechnet. Sie teilen Modelle, nicht Geldbeutel.

Ihr erster echter Call

Hier ein vollständiges, lauffähiges Skript mit der Responses API, OpenAIs aktueller primärer Schnittstelle:

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-4.1-mini",
    instructions="You are a terse assistant. Answer in one sentence.",
    input="Explain what an idempotent API request is.",
)

print(response.output_text)

Führen Sie es aus, und Sie bekommen einen einzigen klaren Satz zurück. Sehen wir uns nun die Teile an, die spezifisch für OpenAI sind.

client = OpenAI()

Das baut den Client und greift still Ihren Umgebungs-Key ab. Alles, was Sie tun, läuft über dieses Objekt: Textgenerierung, Embeddings, Dateien, Audio. Sie konfigurieren es einmal.

model="gpt-4.1-mini"

Der Modell-String ist eine echte, kostenpflichtige Entscheidung, kein Label. OpenAI liefert mehrere Familien: die GPT-4.1-Linie für allgemeine Arbeit, die kleineren mini- und nano-Varianten für günstigere und schnellere Calls, und die Reasoning-Modelle (die o-Serie, etwa o4-mini), die länger denken, bevor sie antworten. Wählen Sie nach Aufgabe. Ein Classifier oder ein Formatter will mini oder nano. Eine mehrstufige Planungsaufgabe will ein Reasoning-Modell. Prüfen Sie das aktuelle Angebot und die Preise auf der Models-Seite, denn die Aufstellung verschiebt sich.

instructions vs. input

Das ist die klarste Verbesserung, die die Responses APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen → bringt. instructions ist die Steuerung auf System-Ebene (PersonaPersonaA semi-fictional, research-based representation of your ideal customer: their goals, frustrations, behaviours and decision criteria.Vollständige Definition ansehen →, Regeln, Output-Format). input ist der eigentliche User-Turn. Sie bauen für einfache Calls keine Liste rollenmarkierter Message-Dictionaries mehr von Hand. Für einen einzelnen Austausch sind zwei Strings alles, was Sie brauchen.

response.output_text

Ein Convenience-Accessor, der die Response auf den finalen Text-String flacht. Das vollständige response-Objekt trägt mehr: TokenTokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.Vollständige Definition ansehen →-Usage, das Modell, das Sie tatsächlich bedient hat, Tool-Calls und strukturierte Content-Blöcke. Für schnelle Arbeit ist output_text das, was Sie wollen; in der Produktion lesen Sie die reicheren Felder.

Responses oder Chat Completions?

Sie werden beide in Tutorials sehen, also kennen Sie den Unterschied.

Chat Completions (client.chat.completions.create) ist die älteren, breit kopierte Schnittstelle. Sie nimmt eine messages-Liste aus {"role": ..., "content": ...}-Dicts. Sie funktioniert weiter und ist nicht deprecated, bestehender Code ist also sicher.

Responses (client.responses.create) ist das, was OpenAI jetzt für neue Projekte empfiehlt. Es ist stateful-freundlich, hat eingebaute Tools (Web Search, File Search, Code Interpreter), die Sie einschalten kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen, ohne sie selbst zu verkabeln, und es behandelt mehrstufige Tool-Nutzung saubererer. Die Responses-API-Docs sind die kanonische Referenz.

Daumenregel: neuer Code, starten Sie mit Responses. Greifen Sie nur zu Chat Completions, wenn Sie etwas erweitern, das es schon nutzt.

Streaming: TokensTokensA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.Vollständige Definition ansehen →, sobald sie eintreffen

Auf eine lange Antwort zu warten, bis sie vollständig generiert ist, bevor irgendetwas angezeigt wird, fühlt sich für Nutzer nach einem Defekt an. Streaming schickt TokensTokensA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.Vollständige Definition ansehen →, während das Modell sie produziert, also genau der Schreibmaschinen-Effekt, den Sie in ChatGPT sehen.

Sie aktivieren es mit stream=True und iterieren über Events:

from openai import OpenAI

client = OpenAI()

stream = client.responses.create(
    model="gpt-4.1-mini",
    input="Write a two-line haiku about slow APIs.",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
print()

Der Stream liefert typisierte Events, nicht nur rohen Text. Sie filtern auf response.output_text.delta, um die inkrementellen Text-Chunks zu fangen. Andere Event-Typen melden, wann die Response startet, wann ein Tool aufgerufen wird und wann die Generierung abgeschlossen ist. Das flush=True erzwingt, dass jeder Chunk sofort ins Terminal geht, statt gepuffert zu werden.

Streaming ändert nichts an Kosten oder am finalen Ergebnis. Es ändert nur, *wann* Sie die Bytes sehen. Nutzen Sie es für jede Nutzeroberfläche; lassen Sie es bei Batch-Jobs weg, bei denen niemand zuschaut.

Drei OpenAI-spezifische Dinge, die man früh kennen sollte

Structured Outputs

Wenn Sie brauchen, dass das Modell Daten zurückgibt, die Ihr Code parsen kann, betteln Sie nicht im Prompt um JSON und hoffen. Nutzen Sie Structured Outputs, das die Response zwingt, einem von Ihnen definierten SchemaSchemaA schema is the formal blueprint that defines how data is structured, named, typed, and related within a database, file, or message.Vollständige Definition ansehen → zu entsprechen. Sie übergeben ein JSON SchemaSchemaA schema is the formal blueprint that defines how data is structured, named, typed, and related within a database, file, or message.Vollständige Definition ansehen → (oder ein Pydantic-Modell in Python), und OpenAI garantiert die Form, sodass Sie nie wieder defensives Parsing für einen verirrten Markdown-Fence schreiben.

from pydantic import BaseModel
from openai import OpenAI

client = OpenAI()

class Ticket(BaseModel):
    priority: str
    summary: str

response = client.responses.parse(
    model="gpt-4.1-mini",
    input="My checkout button has been broken for two days, losing sales.",
    text_format=Ticket,
)

ticket = response.output_parsed
print(ticket.priority, "|", ticket.summary)

response.output_parsed gibt Ihnen ein typisiertes Ticket-Objekt. Das ist das größte einzelne Zuverlässigkeits-Upgrade für jeden, der echte Features baut. Der Structured-Outputs-Guide behandelt die SchemaSchemaA schema is the formal blueprint that defines how data is structured, named, typed, and related within a database, file, or message.Vollständige Definition ansehen →-Regeln.

Function Calling

Das Modell kann entscheiden, Funktionen aufzurufen, die Sie bereitstellen, und gibt den Funktionsnamen und die Argumente zurück, damit Sie sie ausführen. Sie beschreiben Ihre Funktionen, das Modell wählt eine, wenn sie relevant ist, Sie führen sie aus und speisen dann das Ergebnis zurück. Das ist das Primitiv unter Tool-nutzenden Assistenten. Beachten Sie die Abgrenzung: Function Calling in der APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen → ist nicht dasselbe wie GPT Actions in Custom GPTs. Actions sind die No-Code-Variante innerhalb des ChatGPT-Produkts; Function Calling ist der rohe Mechanismus, den Sie im Code kontrollieren.

Das Agents SDK

Wenn aus einem Function Call eine Schleife aus Planen, Tools aufrufen und Ergebnisse prüfen wird, steigen Sie auf das Agents SDK um. Es ist OpenAIs offizielles Framework für mehrstufige Agenten: Es verwaltet die Tool-Call-Schleife, Handoffs zwischen spezialisierten Agenten und Guardrails, sodass Sie die Orchestrierung nicht selbst zusammenbasteln. Für Ihre ersten Calls brauchen Sie es nicht, aber es ist der natürliche nächste Schritt, sobald ein einzelner Responses-Call nicht mehr reicht. Es baut direkt auf der Responses APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen → auf.

Das Response-Objekt richtig lesen

Für alles jenseits einer Demo hören Sie auf, output_text zu drucken, und beginnen, das ganze Objekt zu inspizieren. Zwei Felder zählen sofort.

Usage. Jede Response berichtet TokenTokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.Vollständige Definition ansehen →-Zahlen:

print(response.usage.input_tokens, response.usage.output_tokens)

So messen Sie Kosten. Input-TokensTokensA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.Vollständige Definition ansehen → (Ihr Prompt und die Instructions) und Output-TokensTokensA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.Vollständige Definition ansehen → (die Generierung) sind unterschiedlich bepreist, und Output ist meist die teurere Seite. Usage von Tag eins an zu loggen bewahrt Sie später vor einer Überraschungsrechnung.

Das bedienende Modell. Das Feld model sagt Ihnen, welche exakte Modellversion geantwortet hat. Wenn Sie einen datierten Snapshot pinnen statt eines Alias, der sich automatisch aktualisiert, ist dieses Feld die Bestätigung, was gelaufen ist. Für reproduzierbares Produktionsverhalten pinnen Sie einen konkreten Snapshot statt eines schwebenden Alias.

Fehler, die Sie tatsächlich treffen werden

Echte Calls scheitern aus echten Gründen. Behandeln Sie die häufigen explizit:

from openai import OpenAI, RateLimitError, APIError

client = OpenAI()

try:
    response = client.responses.create(
        model="gpt-4.1-mini",
        input="Summarize the API economy in one line.",
    )
    print(response.output_text)
except RateLimitError:
    print("Slow down or upgrade your tier, then retry with backoff.")
except APIError as err:
    print(f"OpenAI-side issue: {err}")

RateLimitError ist der, dem Anfänger zuerst begegnen. Neue APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen →-Accounts starten auf einem niedrigen Usage-Tier mit moderaten Limits pro Minute; die Tiers steigen automatisch, je älter Ihr Account wird und je mehr Sie ausgeben. Behandeln Sie ein Rate Limit nicht als Bug. Behandeln Sie es als Signal, Retry-with-Backoff einzubauen, was das SDK über die max_retries-Einstellung am Client für Sie übernehmen kann. APIError und seine Unterklassen deckt Authentifizierung, fehlerhafte Requests und transiente Serverfehler ab. Fangen Sie sie, damit ein Schluckauf nicht Ihre App abstürzen lässt.

Latenz und Kosten im Rahmen halten

Ein paar Gewohnheiten zahlen sich sofort aus:

• Output begrenzen. Setzen Sie max_output_tokens, damit ein geschwätziges Modell nicht ausufern und die Rechnung hochtreiben kann. Ein Summarizer braucht selten mehr als ein paar hundert TokensTokensA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.Vollständige Definition ansehen →.
• Modell passend wählen. Der meiste Produktions-Traffic braucht nicht Ihr größtes Modell. Routen Sie einfache Calls zu einem mini oder nano und reservieren Sie die schweren oder Reasoning-Modelle für Aufgaben, die sie wirklich brauchen.
• Streamen, was Nutzer sehen, den Rest batchen. Wahrgenommene Geschwindigkeit kommt vom Streaming; echter Durchsatz kommt davon, unabhängige Calls gleichzeitig zu senden statt in einer langsamen Schleife.

Diese drei Hebel (Output-Limit, Modellwahl, Concurrency) deckt den größten Teil des Kosten- und Latenz-Tunings ab, das Sie früh machen werden.

Key Takeaways

• Starten Sie neuen Code auf der Responses API (client.responses.create) mit instructions und input; behalten Sie Chat Completions nur für bestehende Codebasen.
• Setzen Sie `OPENAI_API_KEY` als Umgebungsvariable und behalten Sie im Kopf, dass Ihr APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen →-Guthaben von jedem ChatGPT-Abo getrennt ist.
• Nutzen Sie Structured Outputs (`responses.parse` mit einem Pydantic-Modell), wann immer Sie parsebare Daten brauchen, statt nach JSON zu prompten und zu hoffen.
• Lesen Sie `response.usage` von Tag eins an und begrenzen Sie max_output_tokens, damit Kosten sichtbar und beschränkt bleiben.
• Streamen Sie für jede Nutzeroberfläche, indem Sie auf response.output_text.delta-Events filtern, und fangen Sie RateLimitError mit Backoff, statt Ihre App abstürzen zu lassen.