Dieser Leitfaden führt Sie durch die End-to-End-Nutzung der OpenAI Responses API: Am Ende werden Sie in der Lage sein, eine Anfrage an POST /v1/responses zu senden, die verschachtelte Ausgabe zu lesen, integrierte Tools zu aktivieren, den Gesprächsstatus über mehrere Aufrufe hinweg zu übertragen und den gesamten Vertrag innerhalb von Apidog zu überprüfen. Die Responses API ist OpenAIs neuere Schnittstelle zur Generierung von Modellausgaben, und der offizielle Responses-Leitfaden erklärt, warum OpenAI neue Projekte nun darauf ausrichtet. Wenn Sie den älteren Endpunkt bereits testen, können Sie einen Großteil dieser Einrichtung wiederverwenden, ähnlich dem Workflow in unserem ChatGPT API-Testleitfaden.
Was Sie zuerst benötigen
Bevor Sie eine Anfrage senden, stellen Sie sicher, dass Sie einige Dinge vorbereitet haben:
- Einen OpenAI API-Schlüssel mit Zugriff auf ein aktuelles Allzweckmodell. Bewahren Sie den Schlüssel in einer Umgebungsvariable auf, nicht in einen Befehl oder eine freigegebene Datei eingefügt.
- Einen Modellnamen, den Ihr Konto tatsächlich aufrufen kann. Anstatt einen fest zu kodieren, überprüfen Sie die Modellliste in Ihrem OpenAI-Dashboard und gleichen Sie diese mit dem Endpunkt ab.
- Eine Möglichkeit, rohe HTTP-Anfragen zu senden und das zurückkommende JSON zu überprüfen. Ein Terminal mit
curlfunktioniert für einen ersten Aufruf, und Apidog werden Sie später verwenden, um die Antwort zu bestätigen und zu simulieren.
Es hilft auch, zu wissen, was der Endpunkt tut, bevor Sie ihn aufrufen. Die Responses API stellt einen einzigen Endpunkt zur Verfügung: POST /v1/responses. Sie senden einen Modellnamen und einen input, und Sie erhalten ein Antwortobjekt zurück, das Klartext, Funktionsaufrufe und die Ergebnisse von OpenAI-gehosteten Tools wie Websuche oder Dateisuche enthalten kann. Ein einziger Aufruf kann einen ganzen mehrstufigen Durchlauf ausführen: Das Modell entscheidet sich, das Web zu durchsuchen, liest die Ergebnisse, schreibt dann eine Antwort, und die Antwort protokolliert jeden Schritt, den es unternommen hat.
Zwei Dinge unterscheiden sie von einem reinen Text-Endpunkt. Erstens kann sie integrierte Tools serverseitig ausführen, sodass Sie Ihre eigene Suche oder Sandbox nicht selbst einrichten müssen. Zweitens ist sie standardmäßig zustandsbehaftet. Jede Antwort erhält eine id, und Sie können diese id an die nächste Anfrage übergeben, damit OpenAI den Gesprächsverlauf für Sie speichert. OpenAI beschreibt die Responses API als die Weiterentwicklung von Chat Completions und empfiehlt sie für neue Projekte, wobei Erfahrungen aus der Assistants API Beta einfließen. Anstelle von drei Denkmodellen erhalten Sie also eines.
So unterscheidet sie sich von Chat Completions
Wenn Sie POST /v1/chat/completions verwendet haben, liegt die Änderung hauptsächlich in Form und Zustand. Chat Completions nimmt ein messages-Array entgegen und gibt choices zurück. Sie verwalten das gesamte Transkript selbst und senden bei jedem Aufruf jede vorherige Runde erneut. Tools sind etwas, das Sie auf Ihrer Seite implementieren.
Die Responses API nimmt einen input (einen String oder eine Liste von typisierten Elementen) entgegen und gibt ein output (eine Liste von typisierten Elementen) zurück. Sie kann die Runde für Sie speichern und gehostete Tools ohne zusätzlichen Aufwand ausführen.
Hier ist der praktische Vergleich:
| Aspekt | Chat Completions | Responses API |
|---|---|---|
| Endpunkt | POST /v1/chat/completions |
POST /v1/responses |
| Anfragekörper | messages Array |
input (String oder Elemente) + instructions |
| Ausgabeformat | choices[].message |
output Liste typisierter Elemente |
| Konversationszustand | Sie senden den gesamten Verlauf erneut | store + previous_response_id |
| Integrierte Tools | Sie bauen sie | web_search, file_search, code_interpreter und mehr |
| Status | Unterstützt, keine Einstellung angekündigt | Empfohlen für neue Projekte |
Chat Completions wird nicht verschwinden. OpenAI sagt, dass es weiterhin unterstützt wird, und Sie können einen Benutzerfluss nach dem anderen migrieren, anstatt alles auf einmal neu zu schreiben. Die Assistants API hat eine Frist: OpenAI hat sie am 26. August 2025 eingestellt, mit einem angegebenen Enddatum am 26. August 2026, daher sollten neue Agentenarbeiten mit Responses beginnen.
Ihre erste Anfrage stellen
Hier ist ein minimaler Aufruf. Ersetzen Sie den Modellnamen durch das, worauf Ihr Konto Zugriff hat, und halten Sie Ihren Schlüssel außerhalb des Befehls selbst.
curl https://api.openai.com/v1/responses \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"input": "Write one sentence describing what an API mock server does.",
"instructions": "You are a concise technical writer. No marketing language.",
"store": true
}'
Sie übergeben hier drei wichtige Dinge: das model, den input (Ihre Eingabeaufforderung) und instructions (die Systemsteuerung). Das Setzen von store auf true weist OpenAI an, die Antwort zu speichern, damit Sie den Thread später fortsetzen können.
Die Antwort lesen
Eine gekürzte Antwort sieht so aus:
{
"id": "resp_abc123",
"object": "response",
"status": "completed",
"model": "gpt-5.5",
"output": [
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "A mock server returns predefined API responses so clients can be developed and tested before the real backend exists."
}
]
}
],
"usage": {
"input_tokens": 28,
"output_tokens": 24,
"total_tokens": 52
}
}
Beachten Sie die Struktur, denn dieser Teil verwirrt viele. Der gewünschte Text befindet sich unter output[0].content[0].text und nicht in einem Top-Level-Feld. Die offiziellen SDKs fügen einen output_text-Convenience-Accessor hinzu, der alle Textelemente zu einem String zusammenfasst, aber diese Eigenschaft ist ein SDK-Helfer, kein Teil des rohen HTTP-JSON. Wenn Sie den Endpunkt direkt aufrufen, lesen Sie den verschachtelten Pfad. Die Top-Level-id ist das, was Sie für den Zustand wiederverwenden werden, und usage.total_tokens sagt Ihnen, was der Aufruf gekostet hat.
Integrierte Tools hinzufügen
Das Hauptmerkmal ist, dass OpenAI bestimmte Tools für Sie ausführt. Sie listen diese in einem tools-Array auf, und das Modell entscheidet, wann sie aufgerufen werden. Die verifizierten integrierten Typen umfassen:
web_searchfür Live-Internetsuchen mit Zitaten (das ältereweb_search_previewfunktioniert weiterhin für ältere Integrationen, verfügt aber nicht über neuere Steuerelemente).file_searchzur Abfrage von hochgeladenen Dateien.code_interpreterzum Ausführen und Analysieren von Code in einer Sandbox.computer_usezur Steuerung einer Computerschnittstelle.image_generationzur Inline-Bilderzeugung.
Das Aktivieren eines Tools ist eine kleine Ergänzung zum Body:
{
"model": "gpt-5.5",
"input": "What changed in the latest OpenAPI release? Cite sources.",
"tools": [{ "type": "web_search" }]
}
Wenn das Modell ein Tool verwendet, erhält das output-Array Einträge, die den Schritt dokumentieren, z. B. ein web_search_call-Element neben der endgültigen message. Das ist später nützlich: Sie können überprüfen, ob ein Tool tatsächlich ausgelöst wurde, und nicht nur, ob Text zurückkam.
Konversation über mehrere Aufrufe hinweg fortsetzen
Der Zustand wird über zwei Parameter gesteuert. store ist standardmäßig auf true gesetzt, was bedeutet, dass OpenAI das Antwortobjekt speichert (standardmäßig 30 Tage lang aufbewahrt) und eine id zurückgibt. Übergeben Sie diese id als previous_response_id bei Ihrem nächsten Aufruf, und das Modell setzt den Thread fort, ohne dass Sie das Transkript erneut senden müssen:
{
"model": "gpt-5.5",
"input": "Now rewrite that for a non-technical audience.",
"previous_response_id": "resp_abc123"
}
Wenn Sie die Dinge lieber zustandslos halten möchten oder eine Anforderung zur Null-Datenaufbewahrung haben, setzen Sie store auf false und verwalten Sie den Kontext selbst. Für Echtzeit-Sprach- und Audioflüsse mit geringer Latenz verwendet OpenAI eine andere Oberfläche; unser GPT Echtzeit-API-Leitfaden behandelt diesen Fall. Und wenn Sie mehrstufige Agenten darauf aufbauen, stimmen die Muster mit dem OpenAI Agents SDK überein.
Wie man es in Apidog testet
Apidog ist eine Plattform für API-Tests, -Design und -Mocks. Es ist kein OpenAI SDK oder eine Codebibliothek, daher werden Sie kein Python damit schreiben. Was Sie stattdessen tun: Bauen Sie die rohe HTTP-Anfrage an /v1/responses, senden Sie sie und schreiben Sie Assertions auf das zurückkommende JSON. Das ist genau die Art von Vertragsprüfung, die eine fehlerhafte Integration erkennt, bevor Ihre Benutzer es tun.
Hier ist die Einrichtung, Schritt für Schritt.
Den Schlüssel in einer Umgebungsvariable speichern
Erstellen Sie in Apidog eine Umgebung (z.B. „OpenAI Prod“) und fügen Sie eine Variable wie OPENAI_API_KEY hinzu. Bewahren Sie den Wert in der Umgebung auf, nicht in der Anfrage, damit das Geheimnis niemals in eine gemeinsam genutzte Sammlung gelangt. Erstellen Sie dann eine neue POST-Anfrage an https://api.openai.com/v1/responses und fügen Sie den Header Authorization: Bearer {{OPENAI_API_KEY}} hinzu. Apidog ersetzt die Variable zum Sendezeitpunkt.
Setzen Sie den Body auf JSON und fügen Sie die vorherige Anfrage ein. Klicken Sie auf Senden. Sie sehen das vollständige Antwortobjekt, formatiert, mit dem verschachtelten output-Array.
Felder der Antwort überprüfen
Ein erfolgreicher 200er-Status ist kein Beweis dafür, dass die Antwort die von Ihrer App erwartete Form hat. Fügen Sie Assertions hinzu, damit ein Fehler lautstark fehlschlägt. Nützliche Prüfungen für eine /v1/responses-Antwort:
statusist gleichcompleted.output[0].content[0].textexistiert und ist nicht leer.usage.total_tokensist größer als 0.- Wenn Sie
toolssenden, hat ein Element inoutputdentypegleichweb_search_call.
Der visuelle Assertion-Builder von Apidog ermöglicht es Ihnen, diese JSON-Pfade anzusprechen, ohne Testskripte schreiben zu müssen, und unsere API-Testfallvorlage zeigt, wie solche Prüfungen strukturiert werden. Speichern Sie die Anfrage in einer Sammlung, und sie wird zu einem wiederholbaren Test, den Sie in CI ausführen können.
Die Antwort für die Offline-Entwicklung simulieren
OpenAI-Aufrufe kosten Geld und erfordern Netzwerkzugriff, was umständlich ist, wenn Sie die Benutzeroberfläche entwickeln, die die Antwort konsumiert, oder Tests in einer Pipeline ausführen, die keine kostenpflichtige API ansprechen sollte. Die Mock-Funktion von Apidog löst dieses Problem. Speichern Sie eine repräsentative /v1/responses-Payload als Mock, richten Sie Ihre App auf die Apidog-Mock-URL aus, und Ihr Frontend erhält die richtige JSON-Form ohne Token-Verbrauch. Wenn sich der echte Endpunkt ändert, aktualisieren Sie einen Mock, anstatt Fehlern bei jedem Test nachzujagen. Unser Mock-API-Erklärer beschreibt den allgemeinen Ansatz.
Diese Unterscheidung ist wichtig. Sie testen gegen den Live-Endpunkt, um den Vertrag von OpenAI zu überprüfen, und Sie simulieren ihn für eine schnelle, Offline- und deterministische Entwicklung. Beide laufen aus demselben Apidog-Projekt.
Häufig gestellte Fragen
Ersetzt die Responses API Chat Completions?
Nicht zwangsläufig. OpenAI bezeichnet Responses als die Weiterentwicklung von Chat Completions und empfiehlt sie für neue Projekte, aber Chat Completions bleibt weiterhin ohne angekündigtes Enddatum unterstützt. Sie können einen Flow nach dem anderen migrieren. Die Assistants API wird eingestellt, mit einem Enddatum im Jahr 2026.
Was ist der Unterschied zwischen store und previous_response_id?
store steuert, ob OpenAI das Antwortobjekt überhaupt speichert (standardmäßig ist es auf true gesetzt und wird 30 Tage lang aufbewahrt). previous_response_id ist die Art und Weise, wie Sie eine neue Anfrage mit einer gespeicherten verknüpfen, damit das Modell die Konversation serverseitig fortsetzt. Sie verwenden sie zusammen für zustandsbehaftete Threads und schalten store aus, wenn Sie zustandsloses Verhalten wünschen.
Welche Modelle unterstützen die Responses API?
Die aktuellen Allzweckmodelle von OpenAI sind so konzipiert, dass sie mit der Responses API funktionieren, aber die Verfügbarkeit hängt von Ihrem Konto und dem von Ihnen gewählten Modell ab. Anstatt einen Modellnamen fest zu kodieren, überprüfen Sie die Modellliste in Ihrem OpenAI-Dashboard und gleichen Sie diese dann mit dem Endpunkt ab. Eine schnelle Anfrage über Apidog zu senden und das model-Feld in der Antwort zu lesen, ist eine schnelle Möglichkeit, zu überprüfen, was Ihr Schlüssel tatsächlich aufrufen kann.
Kann ich die integrierten Tools ohne Code zu schreiben testen?
Ja. Fügen Sie ein tools-Array zum JSON-Body in Apidog hinzu, senden Sie die Anfrage und bestätigen Sie, dass das entsprechende Tool-Call-Element (wie web_search_call) im output-Array erscheint. Sie überprüfen das Verhalten von OpenAI über HTTP, daher ist kein SDK erforderlich. Für umfassendere Tests von Agenten-Tool-Aufrufen siehe wie man API-Testsammlungen aus OpenAPI-Spezifikationen generiert.
Zusammenfassung
Sie haben nun den vollständigen Kreislauf: einen Endpunkt, POST /v1/responses, der Text, gehostete Tools und serverseitigen Konversationszustand verarbeitet. Senden Sie eine Anfrage, lesen Sie die verschachtelte output, fügen Sie ein tools-Array hinzu, wenn Sie Suche oder Codeausführung benötigen, und verketten Sie previous_response_id, um einen Thread am Laufen zu halten. Da die Form anders ist als bei Chat Completions, ist es am sichersten, den Vertrag selbst zu überprüfen, anstatt sich auf Ihre Erinnerung an die ältere API zu verlassen.
Hier passt Apidog. Erstellen Sie die Anfrage, speichern Sie Ihren Schlüssel als Umgebungsvariable, überprüfen Sie die verschachtelten output-Felder und simulieren Sie die Antwort für die Offline-Arbeit, alles in einem Projekt. Laden Sie Apidog herunter und richten Sie einen Test an /v1/responses, um genau zu sehen, was Ihre Integration empfängt. Sie können die gesamte Einrichtung in Apidog vornehmen, ohne eine einzige Zeile Testcode zu schreiben.