OpenAI Chat Completions API: Funktionen und Anwendungsleitfaden

Bei der Entwicklung einer KI-gestützten Anwendung geht es nicht nur darum, ein Modell Antworten generieren zu lassen. Du brauchst auch eine zuverlässige Möglichkeit, Unterhaltungen zu verwalten, Antworten zu steuern und alles mit deiner Anwendung zu verbinden. Die OpenAI Chat Completions API ermöglicht dies, indem sie Entwicklern Kontrolle darüber gibt, wie KI Nachrichten verarbeitet und Antworten generiert. In diesem Artikel erfährst du alles Wichtige darüber, wie sie funktioniert und wie du sie in deinen eigenen Projekten einsetzen kannst.

Mit der OpenAI Chat Completions API können Entwickler die Sprachmodelle von OpenAI in Anwendungen und Dienste integrieren. Sie generiert Antworten aus einer Abfolge von Nachrichten und unterstützt Aufgaben wie Unterhaltungen, die Beantwortung von Fragen, die Erstellung von Inhalten und die Textanalyse.

Chat Completions wird weiterhin unterstützt. Für neue Projekte empfiehlt OpenAI die Responses API. Dieser Leitfaden konzentriert sich auf Chat Completions und erläutert das Nachrichtenformat, die Anfrageparameter und die Nutzung mit kompatiblen SDKs.

Anders als der ältere Completions-Endpunkt (/v1/completions), der einen Text-prompt akzeptiert, akzeptiert Chat Completions eine strukturierte Liste von Nachrichten. Jede Nachricht hat eine Rolle wie developer, user oder assistant, die dem Modell hilft, Anweisungen und den Kontext der Unterhaltung einzuordnen. Die unterstützten Rollen und Inhaltstypen hängen vom ausgewählten Modell ab.

Entwickler können die API nutzen, um verschiedene KI-gestützte Funktionen zu entwickeln, darunter:

• Dialoganwendungen: Erstelle KI-Chatbots, virtuelle Assistenten und Kundensupportsysteme, die auf Nutzernachrichten reagieren.

• Inhaltserstellung: Generiere Artikel, Produktbeschreibungen, E-Mails, Zusammenfassungen und andere schriftliche Inhalte.

• Textanalyse: Klassifiziere Texte, extrahiere Informationen, analysiere Stimmungen und identifiziere Schlüsselpunkte in Dokumenten.

• Programmierunterstützung: Generiere Code-Snippets, erkläre Programmierkonzepte und hilf Entwicklern bei der Fehlerbehebung.

• Sprachverarbeitung: Übersetze, überarbeite, vereinfache und korrigiere Texte in verschiedenen Sprachen.

Die API bietet eine flexible Möglichkeit, Sprachmodelle mit bestehender Software zu verbinden. So können Entwickler KI-generierte Antworten in ihre Anwendungen integrieren, ohne eigene Sprachmodelle entwickeln und hosten zu müssen.

Die Chat Completions API folgt einem Anfrage-Antwort-Workflow. Eine Anwendung sendet eine Anfrage mit einer Modellkennung und einer Liste von Nachrichten an den API-Endpunkt. Das ausgewählte Modell verarbeitet die Eingabe und gibt eine generierte Antwort zurück.

Der grundlegende Workflow umfasst die folgenden Schritte:

1. Unterhaltung vorbereiten: Die Anwendung erfasst die Eingabe des Nutzers und ordnet sie in einer Liste von Nachrichten an. Um Kontext bereitzustellen, können auch vorherige Nachrichten aus der Unterhaltung einbezogen werden.

2. API-Anfrage senden: Die Anwendung sendet eine POST-Anfrage an https://api.openai.com/v1/chat/completions mit dem ausgewählten Modell und der Nachrichtenliste. Anfragen verwenden einen Authorization: Bearer <API_KEY>-Header. Die Methode client.chat.completions.create() des Python SDK übernimmt diese Anfragestruktur und die Authentifizierung.

3. Eingabe verarbeiten: Das Modell interpretiert die Nachrichten, berücksichtigt ihre Rollen und Inhalte und generiert anhand des bereitgestellten Kontexts und der Parameter eine Antwort.

4. Antwort empfangen: Eine nicht gestreamte Anfrage gibt eine JSON-Antwort zurück, die die generierte Vervollständigung und Metadaten enthält. Bei aktiviertem Streaming sendet die API eine Folge von Server-Sent Events (SSE), die die Anwendung bei ihrem Eintreffen verarbeitet.

5. Ausgabe anzeigen oder verarbeiten: Die Anwendung extrahiert die generierte Nachricht und zeigt sie dem Nutzer an oder übergibt sie an eine andere Anwendungskomponente.

Der Workflow basiert auf dem Anfrage- und Antwortmodell der OpenAI Chat Completions API.

Um die Chat Completions API effektiv zu nutzen, müssen Entwickler die wichtigsten Anfrageparameter und deren Einfluss auf das Modellverhalten verstehen.

Der Parameter model legt fest, welches Sprachmodell die Anfrage verarbeitet. Verschiedene Modelle können unterschiedliche Fähigkeiten, Antwortgeschwindigkeiten, Leistungen beim Reasoning und Preise bieten.

Entwickler sollten ein Modell anhand der Komplexität der Aufgabe, der erwarteten Antwortqualität, der Latenzanforderungen und des Budgets auswählen.

Der Parameter messages enthält ein Array mit Nachrichten aus einer Unterhaltung. Jede Nachricht umfasst in der Regel die Felder role und content.

Zu den gängigen Rollen gehören:

Wähle die von deinem Modell unterstützte Rolle für Anweisungen; du musst nicht sowohl system- als auch developer-Nachrichten für dieselben Anweisungen senden. Um den Kontext über mehrere Gesprächsrunden hinweg zu bewahren, füge jeder Anfrage den relevanten Gesprächsverlauf hinzu. Kompatible Anbieter unterstützen möglicherweise unterschiedliche Rollen. Halte dich daher bei der Anpassung einer Integration an die jeweilige Modelldokumentation.

Bei Modellen und Konfigurationen, die dies unterstützen, steuert temperature die Zufälligkeit bei der Stichprobenauswahl. Die API-Referenz definiert einen Bereich von 0 bis 2 mit einem Standardwert von 1. Prüfe vor dem Festlegen eines benutzerdefinierten Werts, ob das ausgewählte Modell diesen Parameter unterstützt.

• Niedrigere Temperatur: Erzeugt fokussiertere und besser vorhersehbare Antworten und eignet sich daher für Klassifizierung, Informationsextraktion und strukturierte Aufgaben.

• Höhere Temperatur: Ermöglicht mehr Variation im generierten Text, was für Brainstorming und kreatives Schreiben nützlich sein kann.

Einige Reasoning-Konfigurationen akzeptieren keine benutzerdefinierten Werte für temperature oder top_p. Lass bei diesen Konfigurationen diese Sampling-Parameter weg und nutze stattdessen unterstützte Steuerungsmöglichkeiten wie den Reasoning-Aufwand und Ausgabelimits.

Sofern unterstützt, steuert top_p die Token-Auswahl über Nucleus Sampling. Es legt den kumulativen Wahrscheinlichkeitsschwellenwert fest, anhand dessen Kandidaten-Token ausgewählt werden.

Ein Wert von 0.1 bedeutet beispielsweise, dass das Modell Token innerhalb der obersten 10 % der kumulativen Wahrscheinlichkeitsmasse berücksichtigt. Niedrigere Werte erzeugen im Allgemeinen fokussiertere Ausgaben, während höhere Werte mehr Variation zulassen.

OpenAI empfiehlt, entweder temperature oder top_p anzupassen, statt beide gleichzeitig zu ändern.

Der Parameter max_completion_tokens legt die maximale Anzahl an Token fest, die das Modell in einer Antwort generieren kann, einschließlich Reasoning-Token, sofern zutreffend.

Ein angemessenes Limit hilft Entwicklern, die Ausgabelänge zu kontrollieren und den Token-Verbrauch zu verwalten. Erreicht das Modell dieses Limit, bevor es seine Antwort abgeschlossen hat, kann die Completion mit dem Abschlussgrund length enden.

Der Parameter stream bestimmt, ob die API die generierte Antwort auf einmal oder schrittweise während der Generierung zurückgibt.

• false: Gibt die vollständige Antwort zurück, nachdem die Generierung abgeschlossen ist.

• true: Streamt Antwortdaten über Server-Sent Events (SSE) an die Anwendung.

Streaming eignet sich für Chat-Oberflächen und Anwendungen, bei denen Nutzer davon profitieren, Antworten schrittweise erscheinen zu sehen, statt auf die vollständige Ausgabe zu warten.

Der Parameter response_format wählt bei unterstützten Modellen das Ausgabeformat aus. Text ist der Standard. Wenn du type auf json_object setzt, wird der JSON-Modus aktiviert, der gültiges JSON erzeugt, aber kein bestimmtes Schema erzwingt. Füge in die Nachrichten eine Anweisung ein, JSON zurückzugeben.

Für vorhersehbare Felder und Datentypen verwende strukturierte Ausgaben auf Basis von JSON Schema mit type: "json_schema" und strict: true bei einem kompatiblen Modell. Im strikten Modus kann nur die unterstützte Teilmenge von JSON Schema verwendet werden. Prüfe vor der Verarbeitung des Ergebnisses, ob eine Ablehnung oder eine gekürzte Antwort vorliegt. Konfigurationsdetails findest du im Leitfaden zu strukturierten Ausgaben.

Der Parameter tool_choice steuert die Tool-Auswahl, wenn das Modell Tool-Aufrufe über Chat Completions unterstützt. Die Unterstützung hängt sowohl vom Modell als auch von seiner Reasoning-Konfiguration ab; einige neuere Modelle erfordern für die Tool-Nutzung die Responses API. Prüfe diese Anforderungen, bevor du Tools zu einer Anfrage hinzufügst.

Zu den gängigen Einstellungen gehören:

• none: Verhindert, dass das Modell Tools aufruft.

• auto: Ermöglicht dem Modell zu entscheiden, ob es ein verfügbares Tool aufruft.

• required: Erfordert, dass das Modell ein oder mehrere Tools aufruft.

Diese Funktion unterstützt Function Calling, sodass eine Anwendung vom Modell generierte Entscheidungen mit externen Funktionen, Datenbanken und Diensten verknüpfen kann. Die Anwendung ist dafür verantwortlich, die angeforderte Funktion auszuführen und ihr Ergebnis an das Modell zurückzugeben.

Parameterdefinitionen und Anforderungen an die Modellkompatibilität findest du in der Chat Completions API-Referenz. Das folgende Python-Beispiel verwendet eine einfache Textanfrage ohne Tools.

Entwickler können über HTTP-Anfragen oder ein offizielles SDK auf die Chat Completions API zugreifen. Das folgende Beispiel verwendet Python, um eine dialogbasierte Anfrage zu senden und die generierte Antwort abzurufen.

Schritt 1: API-Schlüssel abrufen

Erstelle einen API-Schlüssel auf der OpenAI API-Plattform und stelle sicher, dass dein Konto Zugriff auf das ausgewählte Modell sowie ausreichendes API-Guthaben oder Abrechnungskapazität hat. Speichere den Schlüssel in einer Umgebungsvariablen statt im Quellcode der Anwendung. Führe unter macOS oder Linux Folgendes aus:

Ersetze YOUR_API_KEY durch deinen eigenen Schlüssel. Setze unter Windows dieselbe Variable OPENAI_API_KEY in deiner Shell oder Systemumgebung.

Schritt 2: OpenAI Python SDK installieren

Installiere die offizielle Python-Bibliothek mit pip:

Schritt 3: API-Client initialisieren

Importiere das SDK und initialisiere den Client. OpenAI() liest automatisch die in Schritt 1 gesetzte Umgebungsvariable OPENAI_API_KEY.

Schritt 4: Chat-Completion-Anfrage senden

Rufe client.chat.completions.create() mit einem Modell und einer Liste von Nachrichten auf. Dieses Beispiel verwendet gpt-6-astra mit geringem Reasoning-Aufwand und einem Gesamtlimit von 4.096 Token für die Generierung. Wenn dieses Modell für dein Konto nicht verfügbar ist, wähle ein Modell, das Chat Completions unterstützt, und passe die Parameter an die zugehörige Dokumentation an.

In diesem Beispiel:

• model identifiziert das Sprachmodell, das zur Generierung der Antwort verwendet wird.

• messages enthalten Anweisungen und Nutzereingaben.

• reasoning_effort legt den Reasoning-Aufwand für Modelle fest, die diesen Parameter unterstützen.

• max_completion_tokens begrenzt generierte Token, einschließlich Reasoning-Token. Es garantiert keine bestimmte Menge an sichtbarem Text.

• response.choices[0].message.content extrahiert die Antwort des Assistenten.

API-Antwort verarbeiten

Bei dieser nicht streamenden Anfrage gibt die API JSON mit der Vervollständigung und Metadaten zur Anfrage zurück. Das Python SDK wandelt sie in ein ChatCompletion-Objekt um. Deshalb greift das Beispiel über Attribute wie response.choices[0].message.content auf Felder zu.

Wichtige Antwortfelder sind:

Das Feld finish_reason kann Entwicklern helfen zu verstehen, wie eine Generierung beendet wurde. Häufige Werte sind stop, length und tool_calls.

Entwickler können auch das Feld usage prüfen, um den token-Verbrauch für Eingabe und Ausgabe zu überwachen. Das ist nützlich, um API-Kosten zu schätzen und die Nutzung der Anwendung zu optimieren.

Dieses Beispiel zeigt eine einfache Textantwort. Wenn du Streaming, strukturierte Ausgabe oder Tools hinzufügst, passe sowohl die Anfrage als auch die Logik zur Verarbeitung der Antwort an das gewählte Modell und den Endpunkt an.

Für Entwickler, die Alternativen zur OpenAI Chat Completions API prüfen, bietet Kimi API über ein OpenAI-kompatibles API-Format Zugriff auf die großen Sprachmodelle von Moonshot AI.

Kimi bietet Schnittstellen für Chat Completions, Responses und Messages. Das folgende Beispiel verwendet den OpenAI-kompatiblen Chat-Completions-Endpunkt, sodass du den oben vorgestellten SDK-Workflow wiederverwenden kannst. Konfiguriere einen Kimi API-Schlüssel, lege die Kimi-Basis-URL fest und wähle ein unterstütztes Modell aus. Informationen zu Modellparametern, Nachrichtenrollen und Tool-Unterstützung findest du in der Dokumentation von Kimi.

Schritt 1: Kimi API-Schlüssel abrufen

Registriere dich auf der Kimi API-Plattform und erstelle in der Entwicklerkonsole einen API-Schlüssel. Prüfe vor deiner ersten Anfrage dein Guthaben, deinen Modellzugriff und die Kontolimits.

Speichere den Kimi-Schlüssel in einer separaten Umgebungsvariable. Führe unter macOS oder Linux Folgendes aus:

Ersetze YOUR_KIMI_API_KEY durch deinen eigenen Kimi-Schlüssel. Lege unter Windows dieselbe Variable KIMI_API_KEY in deiner Umgebung fest.

Schritt 2: OpenAI Python SDK installieren

Falls das SDK noch nicht installiert ist, führe Folgendes aus:

Schritt 3: Kimi API-Client konfigurieren

Erstelle mit der Kimi-Basis-URL und der in Schritt 1 festgelegten Variable KIMI_API_KEY einen separaten kimi_client. Durch das Auslesen des Schlüssels mit os.environ wird eine fehlende Umgebungsvariable sofort als Fehler sichtbar.

Schritt 4: Chat-Completions-Anfrage senden

Verwende mit dem Kimi-Client dieselbe SDK-Methode. Diese Anfrage wählt kimi-k3 aus, verwendet die von Kimi unterstützte Rolle system für Anweisungen und gibt eine nicht streamende Textantwort zurück.

• Modelloptionen für unterschiedliche Workloads: Kimi K3.1 Pro unterstützt komplexes Schlussfolgern, langfristige Programmieraufgaben und Wissensarbeit. Die Highspeed-Variante bietet bei gleichen Modellfunktionen eine schnellere Ausgabe. Das obige Beispiel verwendet Kimi K3; Informationen zu Verfügbarkeit und Migration findest du in der aktuellen Modellliste.

• OpenAI API-Kompatibilität: Entwickler, die mit dem OpenAI-Chat-Completions-Format vertraut sind, können bei der Integration von Kimi-Modellen eine ähnliche Anfragestruktur und unterstützte SDK-Workflows wiederverwenden.

• Mehrteilige Unterhaltungen: Entwickler können Nachrichtenverläufe bereitstellen, um kontextbezogene Gespräche, virtuelle Assistenten und interaktive Anwendungen zu unterstützen.

• Streaming und Funktionsaufrufe: Die API unterstützt Streaming-Antworten und Workflows für Tool-Aufrufe. Dadurch können Entwickler interaktivere Anwendungen erstellen und Modelle mit externen Funktionen verbinden.

• Multimodale Eingaben: Unterstützte Kimi-Modelle können je nach Modellfunktionen verschiedene Eingabetypen verarbeiten, darunter Text, Bilder und Videos.

Bei der Arbeit mit der Chat Completions API können Entwickler auf Fehler bei der Authentifizierung, API-Konfiguration, Modellverfügbarkeit oder Anfragelimits stoßen. Wenn du diese häufigen Probleme verstehst, kannst du Ursachen leichter ermitteln und deine Integration reibungslos zum Laufen bringen:

• Ungültiger oder fehlender API-Schlüssel: Authentifizierungsfehler wie HTTP 401 können auftreten, wenn der API-Schlüssel falsch, abgelaufen, widerrufen oder nicht korrekt konfiguriert ist. Prüfe, ob der Schlüssel gültig ist, die Umgebungsvariable korrekt geladen wird und die Anfrage die passenden Anmeldedaten enthält.

• Falsche API-Basis-URL: Anfragen an einen falschen Endpunkt können Fehler wie 404 oder Verbindungsfehler zurückgeben. Vergewissere dich, dass die Basis-URL der Dokumentation des API-Anbieters entspricht und die Anfrage den richtigen Endpunktpfad verwendet. Denke beim Wechsel zwischen OpenAI und kompatiblen Anbietern daran, die Basis-URL entsprechend zu aktualisieren.

• Ungültige oder nicht verfügbare Modell-ID: Eine Anfrage kann fehlschlagen, wenn der angegebene Modellname falsch ist, über dein Konto nicht verfügbar ist oder vom ausgewählten Endpunkt nicht unterstützt wird. Prüfe die Modelldokumentation des Anbieters und stelle sicher, dass die Modell-ID mit der für dein API-Konto verfügbaren ID übereinstimmt.

• Kontextlänge überschritten: Wenn die kombinierten Eingabenachrichten und die generierte Ausgabe das Kontextfenster des Modells überschreiten, kann die API die Anfrage ablehnen. Kürze die Eingabe, entferne unnötigen Gesprächsverlauf oder fasse frühere Nachrichten zusammen, bevor du die Anfrage erneut sendest.

• Ausgabe abgeschnitten: Eine Antwort kann enden, bevor der angeforderte Inhalt vollständig ausgegeben wurde, wenn sie das Limit max_completion_tokens erreicht. Erhöhe das token-Limit, sofern unterstützt, oder teile eine Aufgabe mit langer Generierung in kleinere Anfragen auf. Du kannst auch choices[].finish_reason prüfen, um festzustellen, ob die Antwort aufgrund des Limits length beendet wurde.

• Ratenlimit oder Kontingent überschritten: Bei OpenAI kann HTTP 429 auf ein Ratenlimit für Anfragen oder token, ein Ausgabenlimit oder eine andere Nutzungsbeschränkung hinweisen. Prüfe Fehlertyp und -code, bevor du die Anfrage wiederholst. Verringere bei einem vorübergehenden Ratenlimit die Anfragefrequenz und beachte Retry-After, falls angegeben, oder verwende exponentielles Backoff.

Wenn der Fehler auf aufgebrauchte Guthaben oder ein Abrechnungs- oder Ausgabenlimit hinweist, prüfe den Kontostand und die Abrechnungseinstellungen des Kontos; wiederholte Versuche stellen den Zugriff nicht wieder her. Wenn du Kimi oder einen anderen kompatiblen Anbieter verwendest, befolge dessen Dokumentation zu Fehlercodes, da sich Statuscodes und Kontingentregeln unterscheiden können.

Für ein effizienteres Debugging prüfe den von der API zurückgegebenen HTTP-Statuscode und die Fehlermeldung, bevor du deine Anfrageparameter änderst. Anhand dieser Details kannst du Authentifizierungsprobleme, Konfigurationsfehler und Nutzungsgrenzen unterscheiden.

Die Chat Completions API kann ein breites Spektrum an Anwendungsszenarien unterstützen. Ihr strukturiertes Nachrichtenformat und anpassbare Generierungsparameter eignen sich sowohl für einfache textbasierte Funktionen als auch für komplexere KI-Workflows.

• KI-Chatbots und virtuelle Assistenten: Entwickler können die API nutzen, um dialogorientierte Assistenten für Websites, mobile Anwendungen und Kundenservice-Plattformen zu entwickeln. Indem Anwendungen frühere Nachrichten in nachfolgende Anfragen übernehmen, können sie den Gesprächskontext bewahren und relevantere Antworten bereitstellen.

• Inhaltserstellung und Textbearbeitung: Die API kann Text anhand von Nutzeranweisungen generieren und umwandeln. Anwendungen können sie nutzen, um Blogbeiträge zu entwerfen, Marketingtexte zu schreiben, lange Inhalte zusammenzufassen, Absätze umzuschreiben und Schreibstile für verschiedene Zielgruppen und Zwecke anzupassen.

• Textklassifizierung und Informationsextraktion: Unternehmen können die API in Workflows integrieren, die große Textmengen verarbeiten. Sie kann beispielsweise Kundenfeedback klassifizieren, Stimmungen erkennen, wichtige Informationen aus Nachrichten extrahieren und unstrukturierte Inhalte in vordefinierte Kategorien einordnen.

• Programmierassistenten: Die API kann Tools für die Softwareentwicklung unterstützen, indem sie Code generiert, Programmierkonzepte erklärt, Lösungen vorschlägt und Entwicklern hilft, Fehler zu identifizieren. Anwendungen können das Modell über Function Calling auch mit externen Entwicklungstools verbinden.

• KI-gestützte Geschäftsabläufe: Entwickler können die API in Geschäftsanwendungen integrieren, um wiederkehrende sprachbezogene Aufgaben zu automatisieren. Dazu gehören etwa die Bearbeitung von Kundenanfragen, das Erstellen von Berichten, das Extrahieren von Informationen aus Dokumenten und das Vorbereiten von Antworten anhand vordefinierter Anweisungen.

Die OpenAI Chat Completions API bietet Entwicklern eine praktische Möglichkeit, dialogorientierte KI in ihre Anwendungen zu integrieren und nützlichere Nutzererlebnisse zu schaffen. Die Wahl des richtigen Modells, das Verständnis seiner Parameter und die sorgfältige Verarbeitung von API-Antworten können entscheidend dafür sein, wie gut eine Anwendung funktioniert. Bei der Entwicklung KI-gestützter Lösungen müssen Entwickler sich jedoch nicht auf einen einzigen Anbieter verlassen. Wenn du eine weitere Option erkunden möchtest, probiere die Kimi API aus und finde heraus, wie gut ihre OpenAI-kompatible Einrichtung zu deinen Entwicklungsanforderungen passt.