Wie man die OpenAI Responses API nutzt

Dieser Leitfaden zeigt, wie Sie die OpenAI Responses API praktisch einsetzen: Sie senden eine Anfrage an POST /v1/responses, lesen die verschachtelte Ausgabe, aktivieren integrierte Tools, führen Konversationszustand über mehrere Aufrufe fort und prüfen den HTTP-Vertrag in Apidog. Die Responses API ist OpenAIs neuere Schnittstelle zur Generierung von Modellausgaben. Der offizielle Responses-Leitfaden erklärt, warum OpenAI neue Projekte darauf ausrichtet. Wenn Sie bereits den älteren Endpunkt testen, können Sie viel Setup wiederverwenden, ähnlich wie im ChatGPT API-Testleitfaden.

Testen Sie Apidog noch heute

Voraussetzungen

Bevor Sie die erste Anfrage senden, bereiten Sie Folgendes vor:

• Einen OpenAI API-Schlüssel mit Zugriff auf ein aktuelles Allzweckmodell.
• Einen Modellnamen, den Ihr Konto tatsächlich verwenden darf.
• Ein Tool zum Senden roher HTTP-Anfragen, z. B. curl oder Apidog.
• Eine sichere Ablage für Secrets, z. B. Umgebungsvariablen statt hart codierter Schlüssel.

Die Responses API stellt den Endpunkt POST /v1/responses bereit. Sie senden ein model, einen input und optional instructions, tools oder Zustandsparameter. Zurück kommt ein Response-Objekt, das Textausgaben, Tool-Aufrufe und Nutzungsdaten enthalten kann.

Zwei Eigenschaften sind für die Implementierung wichtig:

1. Gehostete Tools: OpenAI kann serverseitig Tools wie Websuche, Dateisuche oder Codeausführung verwenden.
2. Zustand: Jede Response erhält eine id. Diese können Sie mit previous_response_id an den nächsten Aufruf übergeben.

Unterschied zu Chat Completions

Wenn Sie bisher POST /v1/chat/completions verwendet haben, ändern sich vor allem Struktur und Zustandsverwaltung.

Chat Completions nutzt ein messages-Array und gibt choices zurück. Sie verwalten den Verlauf selbst und senden ihn bei jedem Aufruf erneut.

Die Responses API nutzt input und gibt eine output-Liste mit typisierten Elementen zurück. Sie kann gespeicherte Antwortobjekte referenzieren und gehostete Tools ausführen.

Aspekt	Chat Completions	Responses API
Endpunkt	POST /v1/chat/completions	POST /v1/responses
Anfragekörper	messages-Array	input plus instructions
Ausgabeformat	choices[].message	output-Liste typisierter Elemente
Konversationszustand	Sie senden den Verlauf erneut	store und previous_response_id
Integrierte Tools	Sie implementieren sie selbst	web_search, file_search, code_interpreter und mehr
Status	Weiterhin unterstützt	Für neue Projekte empfohlen

Chat Completions wird weiterhin unterstützt. Sie müssen also nicht alles auf einmal migrieren. Die Assistants API hat dagegen eine Frist: OpenAI hat sie am 26. August 2025 eingestellt, mit einem angegebenen Enddatum am 26. August 2026. Neue Agenten-Workflows sollten daher mit Responses starten.

Erste Anfrage senden

Speichern Sie Ihren API-Schlüssel zuerst als Umgebungsvariable:

export OPENAI_API_KEY="sk-..."

Senden Sie dann eine minimale Anfrage:

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
  }'

Die wichtigsten Felder:

• model: das Modell, das Ihr Konto verwenden kann.
• input: die Nutzereingabe.
• instructions: System- oder Verhaltensanweisungen.
• store: speichert die Response, damit Sie den Thread später fortsetzen können.

Antwortstruktur 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
  }
}

Der eigentliche Text liegt nicht auf der obersten Ebene, sondern hier:

output[0].content[0].text

Wenn Sie direkt per HTTP arbeiten, müssen Sie diesen verschachtelten Pfad lesen. Einige SDKs bieten einen output_text-Accessor, der Textelemente zusammenfasst. Dieser Convenience-Accessor gehört jedoch nicht zum rohen HTTP-JSON.

Wichtige Felder für Ihre Implementierung:

• id: Response-ID für Folgeaufrufe.
• status: sollte bei erfolgreicher Verarbeitung completed sein.
• output: Liste der Nachrichten, Tool-Aufrufe und weiterer Elemente.
• usage.total_tokens: Tokenverbrauch des Aufrufs.

Integrierte Tools aktivieren

Tools werden im Body über ein tools-Array aktiviert. Das Modell entscheidet dann, ob und wann ein Tool verwendet wird.

Verfügbare integrierte Tool-Typen umfassen:

• web_search für Live-Websuche mit Quellen.
• file_search für Abfragen über hochgeladene Dateien.
• code_interpreter für Codeausführung und Analyse in einer Sandbox.
• computer_use zur Steuerung einer Computerschnittstelle.
• image_generation zur Inline-Bilderzeugung.

Beispiel mit Websuche:

{
  "model": "gpt-5.5",
  "input": "What changed in the latest OpenAPI release? Cite sources.",
  "tools": [
    {
      "type": "web_search"
    }
  ]
}

Wenn ein Tool verwendet wird, enthält output zusätzliche Einträge. Bei Websuche kann z. B. ein Element vom Typ web_search_call erscheinen.

Das ist wichtig für Tests: Prüfen Sie nicht nur, ob Text zurückkommt. Prüfen Sie auch, ob das erwartete Tool tatsächlich ausgelöst wurde.

Konversation über mehrere Aufrufe fortsetzen

Die Responses API kann serverseitigen Zustand speichern.

Dazu verwenden Sie zwei Parameter:

• store: steuert, ob OpenAI das Response-Objekt speichert.
• previous_response_id: referenziert eine vorherige Response.

Beispiel für einen Folgeaufruf:

{
  "model": "gpt-5.5",
  "input": "Now rewrite that for a non-technical audience.",
  "previous_response_id": "resp_abc123"
}

Damit setzt das Modell den Thread fort, ohne dass Sie den gesamten Verlauf erneut senden müssen.

Wenn Sie zustandslos arbeiten möchten, setzen Sie store auf false und verwalten den Kontext selbst.

Für Sprach- und Audioflüsse mit niedriger Latenz verwendet OpenAI eine andere Oberfläche. Dieser Fall wird im GPT Echtzeit-API-Leitfaden behandelt. Wenn Sie mehrstufige Agenten bauen, passen die Muster auch zum OpenAI Agents SDK.

Responses API in Apidog testen

Apidog ist eine Plattform für API-Tests, API-Design und API-Mocks. Für die Responses API nutzen Sie Apidog nicht als SDK, sondern als HTTP-Testumgebung:

1. Request an POST /v1/responses erstellen.
2. Header und JSON-Body konfigurieren.
3. Anfrage senden.
4. Response-JSON prüfen.
5. Assertions für den Vertrag speichern.
6. Optional Mock-Antworten für Offline-Entwicklung erzeugen.

1. API-Schlüssel als Umgebungsvariable speichern

Erstellen Sie in Apidog eine Umgebung, z. B. OpenAI Prod.

Fügen Sie eine Variable hinzu:

OPENAI_API_KEY

Speichern Sie den Schlüssel in der Umgebung, nicht direkt in der Anfrage. So landet das Secret nicht in einer gemeinsam genutzten Collection.

Erstellen Sie danach eine neue Anfrage:

POST https://api.openai.com/v1/responses

Header:

Authorization: Bearer {{OPENAI_API_KEY}}
Content-Type: application/json

Apidog ersetzt {{OPENAI_API_KEY}} beim Senden durch den Wert aus der aktiven Umgebung.

2. JSON-Body einfügen

Nutzen Sie zum Start denselben Body wie im curl-Beispiel:

{
  "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
}

Senden Sie die Anfrage. In der Antwortansicht sehen Sie das vollständige JSON inklusive output, usage und id.

3. Response-Felder prüfen

Ein HTTP-Status 200 reicht nicht aus. Ihre Anwendung erwartet eine bestimmte JSON-Struktur. Legen Sie daher Assertions an.

Sinnvolle Checks:

• status ist completed.
• output[0].content[0].text existiert.
• output[0].content[0].text ist nicht leer.
• usage.total_tokens ist größer als 0.
• Wenn tools gesetzt ist: Ein Element in output hat den Typ web_search_call.

Der visuelle Assertion-Builder von Apidog kann diese JSON-Pfade prüfen, ohne dass Sie Testskripte schreiben müssen. Die API-Testfallvorlage zeigt, wie solche Prüfungen strukturiert werden.

Speichern Sie die Anfrage anschließend in einer Collection. Damit wird sie zu einem wiederholbaren Test, den Sie auch in CI ausführen können.

4. Tool-Aufrufe testen

Erweitern Sie den Body um tools:

{
  "model": "gpt-5.5",
  "input": "What changed in the latest OpenAPI release? Cite sources.",
  "tools": [
    {
      "type": "web_search"
    }
  ]
}

Prüfen Sie anschließend, ob output neben der finalen Nachricht auch einen Tool-Call enthält.

Beispielhafte Assertion:

output[*].type contains web_search_call

So validieren Sie nicht nur die Textantwort, sondern auch das Verhalten der Tool-Nutzung.

5. Mock für Offline-Entwicklung erstellen

Live-Aufrufe gegen OpenAI kosten Tokens und benötigen Netzwerkzugriff. Für Frontend-Entwicklung oder CI-Tests ist oft ein stabiler Mock besser.

Vorgehen:

1. Speichern Sie eine repräsentative /v1/responses-Payload.
2. Erstellen Sie daraus in Apidog einen Mock.
3. Richten Sie Ihre Anwendung auf die Apidog-Mock-URL aus.
4. Entwickeln und testen Sie gegen dieselbe JSON-Struktur, ohne OpenAI aufzurufen.

Der Mock-API-Erklärer beschreibt den allgemeinen Ansatz.

Praktisch bedeutet das:

• Live-Test: prüft den echten OpenAI-Vertrag.
• Mock-Test: liefert schnelle, deterministische Antworten für Entwicklung und CI.

Beides kann im selben Apidog-Projekt liegen.

Häufig gestellte Fragen

Ersetzt die Responses API Chat Completions?

Nicht sofort. OpenAI bezeichnet Responses als Weiterentwicklung von Chat Completions und empfiehlt sie für neue Projekte. Chat Completions bleibt weiterhin unterstützt, ohne angekündigtes Enddatum. Sie können Flow für Flow migrieren.

Die Assistants API wird dagegen eingestellt, mit einem Enddatum im Jahr 2026.

Was ist der Unterschied zwischen store und previous_response_id?

store steuert, ob OpenAI das Response-Objekt speichert.

previous_response_id verknüpft eine neue Anfrage mit einer gespeicherten Response.

Typischer zustandsbehafteter Ablauf:

1. Erste Anfrage mit store: true senden.
2. id aus der Antwort speichern.
3. Nächste Anfrage mit previous_response_id senden.

Wenn Sie keinen serverseitigen Zustand möchten, setzen Sie store auf false und senden den Kontext selbst.

Welche Modelle unterstützen die Responses API?

Aktuelle Allzweckmodelle von OpenAI sind für die Responses API ausgelegt. Die konkrete Verfügbarkeit hängt aber von Ihrem Konto und Modellzugriff ab.

Statt Modellnamen hart zu codieren:

1. Modellliste im OpenAI-Dashboard prüfen.
2. Modell im Request verwenden.
3. Response-Feld model kontrollieren.
4. Fehlerfälle in Apidog als Tests speichern.

Kann ich integrierte Tools ohne Code testen?

Ja. Fügen Sie im Apidog-Body ein tools-Array hinzu, senden Sie die Anfrage und prüfen Sie das output-Array auf das passende Tool-Call-Element, z. B. web_search_call.

Sie testen direkt über HTTP. Ein SDK ist dafür nicht erforderlich.

Für breitere Testabdeckung von API- und Agenten-Flows siehe auch den Leitfaden zum Generieren von API-Testsammlungen aus OpenAPI-Spezifikationen.

Zusammenfassung

Die Responses API bündelt Textgenerierung, gehostete Tools und serverseitigen Konversationszustand in einem Endpunkt:

POST /v1/responses

Für die Implementierung sollten Sie besonders auf diese Punkte achten:

• Textausgabe liegt verschachtelt unter output[0].content[0].text.
• Die Response-id kann mit previous_response_id wiederverwendet werden.
• Tools werden über tools aktiviert und erscheinen als eigene Elemente in output.
• Der Vertrag unterscheidet sich von Chat Completions und sollte explizit getestet werden.

Mit Apidog können Sie die Anfrage erstellen, den API-Schlüssel als Umgebungsvariable speichern, JSON-Pfade prüfen und Mock-Antworten für Offline-Entwicklung bereitstellen. Laden Sie Apidog herunter und richten Sie einen Test für /v1/responses ein, um genau zu sehen, welche Struktur Ihre Integration empfängt. Die gesamte Einrichtung funktioniert in Apidog, ohne eine einzige Zeile Testcode zu schreiben.