Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Zur Responses API migrieren

Die Responses API ist unsere neue grundlegende API-Schnittstelle. Sie entwickelt Chat Completions weiter, vereinfacht die Integration und bietet leistungsfähige Bausteine für Agenten.

Wir unterstützen Chat Completions weiterhin. Für alle neuen Projekte empfehlen wir Responses.

Überblick über die Responses API

Die Responses API bietet eine einheitliche Schnittstelle, mit der du leistungsfähige Anwendungen entwickeln kannst, die wie Agenten handeln. Sie unterstützt:

Vorteile von Responses

Die Responses API bietet gegenüber Chat Completions mehrere Vorteile:

  • Bessere Modellleistung: Reasoning-Modelle wie GPT-5 lösen Aufgaben mit Responses besser als mit Chat Completions. In unseren internen Tests fiel das Ergebnis auf SWE-bench bei gleichem Prompt und Setup um 3 % besser aus.
  • Mehrere Tool-Aufrufe pro Anfrage: Das Modell kann standardmäßig innerhalb einer einzigen API-Anfrage mehrere Tools aufrufen, etwa web_search, image_generation, file_search und code_interpreter, aber auch Remote-MCP-Server und deine eigenen Funktionen.
  • Geringere Kosten: Responses nutzt den Cache besser und senkt dadurch die Kosten. In internen Tests verbesserte sich die Cache-Nutzung gegenüber Chat Completions um 40 % bis 80 %.
  • Kontext über mehrere Gesprächsrunden: Mit store: true speicherst du den Zustand, sodass der Reasoning- und Tool-Kontext für die nächste Gesprächsrunde erhalten bleibt.
  • Flexible Eingaben: Übergib die Eingabe als Zeichenkette oder als Liste von Nachrichten. Mit Anweisungen kannst du Vorgaben auf Systemebene machen.
  • Verschlüsseltes Reasoning: Du kannst erweitertes Reasoning nutzen, ohne den Zustand zu speichern.
  • Für künftige Modelle ausgelegt: Die API ist bereits auf kommende Modelle ausgerichtet.
Funktionen Chat Completions API Responses API
Textgenerierung
Audio Demnächst verfügbar
Bildverständnis
Strukturierte Ausgaben
Funktionsaufruf
Websuche
Dateisuche
Computernutzung
Code Interpreter
MCP
Bildgenerierung
Reasoning-Zusammenfassungen

Beispiele

Die folgenden Beispiele zeigen, wie sich die Responses API und die Chat Completions API in der Praxis unterscheiden.

Nachrichten und Elemente im Vergleich

Beide APIs können mit unseren Modellen Ausgaben generieren. Bei einem Aufruf von Chat Completions bestehen sowohl die Eingabe als auch das Ergebnis aus einem Array von Nachrichten. Die Responses API verwendet dagegen Elemente. Ein Element kann einen von mehreren Typen haben, die unterschiedliche Aktionen des Modells abbilden. Eine message ist ebenso ein Elementtyp wie ein function_call oder ein function_call_output. Während eine Nachricht in Chat Completions mehrere Aspekte in einem Objekt bündelt, bildet bei Responses jedes Element eine eigenständige Einheit des Modellkontexts ab.

Chat Completions kann außerdem mehrere parallel generierte Ergebnisse als choices zurückgeben, wenn du den Parameter n verwendest. Die Responses API hat diesen Parameter nicht und gibt nur ein generiertes Ergebnis zurück.

Chat Completions API
from openai import OpenAI

client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[
        {
            "role": "user",
            "content": "Write a one-sentence bedtime story about a unicorn.",
        }
    ],
)

print(completion.choices[0].message.content)
Responses API
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    input="Write a one-sentence bedtime story about a unicorn.",
)

print(response.output_text)

Die Antwort der Responses API enthält etwas andere Felder. Anstelle einer message erhältst du ein typisiertes response-Objekt mit einer eigenen id. Responses speichert Antworten standardmäßig. Bei Chat Completions ist die Speicherung für neue Konten standardmäßig aktiviert. Mit store: false deaktivierst du die Speicherung bei beiden APIs.

Auch die zurückgegebenen Objekte unterscheiden sich leicht. Bei Chat Completions erhältst du ein Array von choices, die jeweils eine message enthalten. Bei Responses erhältst du ein Array von Elementen im Feld output.

Chat Completions API
{
  "id": "chatcmpl-C9EDpkjH60VPPIB86j2zIhiR8kWiC",
  "object": "chat.completion",
  "created": 1756315657,
  "model": "gpt-5.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Under a blanket of starlight, a sleepy unicorn tiptoed through moonlit meadows, gathering dreams like dew to tuck beneath its silver mane until morning.",
        "refusal": null,
        "annotations": []
      },
      "finish_reason": "stop"
    }
  ],
  ...
}
Responses API
{
  "id": "resp_68af4030592c81938ec0a5fbab4a3e9f05438e46b5f69a3b",
  "object": "response",
  "created_at": 1756315696,
  "model": "gpt-5.5",
  "output": [
    {
      "id": "rs_68af4030baa48193b0b43b4c2a176a1a05438e46b5f69a3b",
      "type": "reasoning",
      "content": [],
      "summary": []
    },
    {
      "id": "msg_68af40337e58819392e935fb404414d005438e46b5f69a3b",
      "type": "message",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "annotations": [],
          "logprobs": [],
          "text": "Under a quilt of moonlight, a drowsy unicorn wandered through quiet meadows, brushing blossoms with her glowing horn so they sighed soft lullabies that carried every dreamer gently to sleep."
        }
      ],
      "role": "assistant"
    }
  ],
  ...
}

Weitere Unterschiede

  • Responses speichert Antworten standardmäßig. Bei Chat Completions ist die Speicherung für neue Konten standardmäßig aktiviert. Mit store: false deaktivierst du die Speicherung bei beiden APIs.
  • Modelle mit Reasoning können über die Responses API Tools effektiver nutzen. Ab GPT-5.4 unterstützt Chat Completions Tool-Aufrufe nur, wenn reasoning_effort den Wert none hat.
  • Die APIs verwenden unterschiedliche Formate für strukturierte Ausgaben. Verwende anstelle von response_format bei Responses das Feld text.format. Mehr dazu erfährst du im Leitfaden zu strukturierten Ausgaben.
  • Auch bei Funktionsaufrufen unterscheiden sich die Formate. Das betrifft sowohl die Funktionskonfiguration in der Anfrage als auch die Funktionsaufrufe in der Antwort. Einen vollständigen Vergleich findest du im Leitfaden zu Funktionsaufrufen.
  • Das Responses SDK bietet mit output_text eine Lesehilfe für die Textausgabe. Im Chat Completions SDK gibt es diese Hilfe nicht.
  • Bei Chat Completions musst du den Gesprächszustand selbst verwalten. Die Responses API unterstützt die Conversations API für dauerhaft gespeicherte Gespräche. Alternativ kannst du mit previous_response_id Antworten miteinander verknüpfen.

Von Chat Completions migrieren

Für die Migration sind drei Änderungen wichtig. Sende Anfragen an /v1/responses, lies die Ausgabe aus einem typisierten output-Array und lege fest, wie deine Anwendung den Zustand von einer Gesprächsrunde in die nächste übernimmt.

1. Endpunkte für die Generierung aktualisieren

Stelle zuerst deine Endpunkte für die Generierung von post /v1/chat/completions auf post /v1/responses um.

Wenn du weder Funktionen noch multimodale Eingaben verwendest, kannst du reine Textnachrichten in beiden APIs unverändert als Eingabe verwenden:

Textnachrichten als Eingabe wiederverwenden
const context: { role: "system" | "user"; content: string }[] = [
  { role: "system", content: "You are a helpful assistant." },
  { role: "user", content: "Hello!" },
];

const completion = await client.chat.completions.create({
  model: "gpt-6-astra",
  messages: context,
});

const response = await client.responses.create({
  model: "gpt-6-astra",
  input: context,
});

Bei Chat Completions erstellst du ein messages-Array und liest den vom Modell generierten Text aus completion.choices[0].message.content.

Text mit einem Modell generieren
import OpenAI from "openai";
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const completion = await client.chat.completions.create({
  model: "gpt-6-astra",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Hello!" },
  ],
});
console.log(completion.choices[0].message.content);

2. Nachrichten den passenden Elementen zuordnen

Chat Completions verwendet messages sowohl für die Eingabe als auch für die Ausgabe. Responses verwendet für input und output Arrays aus typisierten Elementen. Neben message gibt es weitere Elementtypen wie reasoning, function_call und function_call_output.

Konzept in Chat Completions Entsprechung in Responses
messages[] input als Zeichenkette oder als Array von Eingabeelementen
Anweisungen auf System- oder Entwicklerebene instructions auf der obersten Ebene oder kompatible Nachrichtenelemente, wenn du einen bestehenden Gesprächsverlauf erhalten musst
Nachricht der nutzenden Person Eingabeelement für eine Nachricht mit role: "user"
Nachricht des Assistenten Ausgabeelement für eine Nachricht in response.output. Übergib es wieder in input, wenn du den Zustand selbst verwaltest.
Tool- oder Funktionsaufruf Ausgabeelement vom Typ function_call
Ergebnis eines Tool- oder Funktionsaufrufs Eingabeelement vom Typ function_call_output, das über call_id mit dem Aufruf verknüpft ist
Mehrere generierte Ergebnisse mit n In Responses nicht verfügbar. Sende separate Anfragen, wenn du mehrere mögliche Ausgaben benötigst.

Wenn du nur den fertigen Text benötigst, verwende die SDK-Lesehilfe output_text. Wenn dein Ablauf Reasoning, Tools oder multimodale Ausgaben nutzt, durchlaufe response.output und verarbeite jedes Element entsprechend seinem type.

3. Gespräche mit mehreren Runden aktualisieren

Wenn deine Anwendung Gespräche über mehrere Runden unterstützt, passe an, wie sie den Kontext verwaltet. Bei Responses hast du dafür drei gängige Möglichkeiten:

  • Verwende previous_response_id, wenn OpenAI den Kontext früherer Antworten verwalten soll. Sende unveränderte instructions bei jeder Anfrage erneut, denn previous_response_id übernimmt die instructions auf der obersten Ebene der vorherigen Antwort nicht.
  • Übergib frühere output-Elemente in der nächsten Anfrage erneut, wenn du den Kontext selbst verwalten oder kürzen musst.
  • Verwende die Conversations API, wenn du ein dauerhaft gespeichertes Gesprächsobjekt benötigst.

Bei Chat Completions speicherst du den Gesprächsverlauf selbst und sendest bei jeder Anfrage das messages-Array mit allen bisherigen Nachrichten.

Gespräch über mehrere Runden
let messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
  { role: "system", content: "You are a helpful assistant." },
  { role: "user", content: "What is the capital of France?" },
];
const res1 = await client.chat.completions.create({
  model: "gpt-6-astra",
  messages,
});

messages = messages.concat([res1.choices[0].message]);
messages.push({ role: "user", content: "And its population?" });

const res2 = await client.chat.completions.create({
  model: "gpt-6-astra",
  messages,
});

Auch wenn du previous_response_id verwendest, rechnet die API alle bisherigen Eingabetoken der Antworten in der Kette als Eingabetoken ab.

4. Festlegen, wann der Zustand gespeichert wird

Responses speichert Antworten standardmäßig. Bei Chat Completions ist die Speicherung für neue Konten standardmäßig aktiviert. Mit store: false deaktivierst du die Speicherung bei beiden APIs.

Manche Organisationen dürfen den Zustand bei der Nutzung der Responses API aufgrund von Compliance- oder Aufbewahrungsvorgaben nicht speichern. Dazu zählen Organisationen, für die keine Datenaufbewahrung (ZDR) zulässig ist. Für diese Fälle bietet OpenAI verschlüsselte Reasoning-Elemente an. Damit kannst du Reasoning-Elemente auch in einem zustandslosen Workflow nutzen.

So nutzt du Reasoning, ohne den Zustand zu speichern:

  • Gib store: false im Feld für die Speicherung an.
  • Bewahre jedes zurückgegebene Reasoning-Element auf und übergib es bei der nächsten Anfrage erneut. Wenn du eine Antwort erstellst, enthält jedes dieser Elemente standardmäßig encrypted_content.

Die API gibt dann die Reasoning-Token in verschlüsselter Form zurück. Du kannst sie wie reguläre Reasoning-Elemente in späteren Anfragen erneut übergeben. Für Organisationen mit ZDR erzwingt OpenAI automatisch store: false. Enthält eine Anfrage encrypted_content, entschlüsselt OpenAI den Inhalt im Arbeitsspeicher, nutzt ihn zum Generieren der nächsten Antwort und verwirft ihn anschließend sicher. Neue Reasoning-Token werden sofort verschlüsselt und an dich zurückgegeben. So wird kein Zwischenzustand dauerhaft gespeichert.

5. Funktionsdefinitionen und -ausgaben aktualisieren

Bei Funktionsdefinitionen unterscheiden sich Chat Completions und Responses in zwei Punkten:

  1. Bei Chat Completions steht die Typkennzeichnung außerhalb der Funktionsdefinition. Bei Responses steht sie innerhalb der Definition.
  2. Bei Chat Completions ist der strikte Modus für Funktionen standardmäßig deaktiviert. Wenn du bei Responses strict weglässt, versucht die API, den strikten Modus zu verwenden. Lässt sich das Schema dafür nicht anpassen, führt Responses Funktionsaufrufe nach Möglichkeit ohne strikte Prüfung aus und gibt das Tool mit der ermittelten Einstellung strict: false zurück. Wenn du den strikten Modus bei Responses ausdrücklich deaktivieren möchtest, setze strict: false.

Das Funktionsbeispiel für die Responses API rechts ist funktional gleichwertig mit dem Beispiel für Chat Completions links.

Chat Completions API
{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Determine weather in my location",
    "strict": true,
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "location"
      ]
    }
  }
}
Responses API
{
  "type": "function",
  "name": "get_weather",
  "description": "Determine weather in my location",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string"
      }
    },
    "additionalProperties": false,
    "required": [
      "location"
    ]
  }
}

Bewährte Vorgehensweisen für Funktionsaufrufe beachten

Bei Responses sind Tool-Aufrufe und ihre Ausgaben zwei unterschiedliche Elementtypen. Die Zuordnung erfolgt über eine call_id. Wie Funktionsaufrufe in Responses funktionieren, erfährst du in der Dokumentation zu Funktionsaufrufen.

6. Definitionen für strukturierte Ausgaben aktualisieren

In der Responses API findest du die Definitionen für strukturierte Ausgaben jetzt anstelle von response_format unter text.format:

Strukturierte Ausgaben
const completion = await openai.chat.completions.create({
  model: "gpt-6-astra",
  messages: [
    {
      role: "user",
      content: "Jane, 54 years old",
    },
  ],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "person",
      strict: true,
      schema: {
        type: "object",
        properties: {
          name: {
            type: "string",
            minLength: 1,
          },
          age: {
            type: "number",
            minimum: 0,
            maximum: 130,
          },
        },
        required: ["name", "age"],
        additionalProperties: false,
      },
    },
  },
  reasoning_effort: "medium",
});

7. Verarbeitung von Streams aktualisieren

Beim Streaming liefert Chat Completions die Ausgabe stückweise in Datenblöcken mit einem delta-Feld. Responses verwendet typisierte Server-Sent Events. Passe die Verarbeitung deiner Streams so an, dass sie anhand von type zwischen den Ereignissen unterscheidet und die Ereignisse verarbeitet, die deine Benutzeroberfläche oder Orchestrierungsschicht benötigt.

Achte beim Textstreaming auf Ereignisse wie:

  • response.created
  • response.output_text.delta
  • response.completed
  • error

Streams für Funktionsaufrufe können auch Ereignisse wie response.function_call_arguments.delta und response.function_call_arguments.done ausgeben. Mehr dazu findest du im Leitfaden zum Streaming mit Responses und in der Referenz zu Streaming-Ereignissen in Responses.

8. Auf native Tools umstellen

Wenn sich die nativen Tools von OpenAI für einen Anwendungsfall eignen, kannst du deine Tool-Aufrufe so anpassen, dass sie diese Tools direkt nutzen.

Bei Chat Completions kannst du von OpenAI gehostete Tools nicht direkt nutzen. Du musst die Tool-Integration selbst schreiben. Dieses Beispiel verwendet GPT-5.6 Terra mit deaktiviertem Reasoning. GPT-6 Astra und GPT-6.1 Sol benötigen für Tool-Aufrufe die Responses API.

Tool für die Websuche
async function web_search(query: string) {
  const res = await fetch(`https://api.example.com/search?q=${query}`);
  const data = await res.json();
  return data.results;
}

const completion = await client.chat.completions.create({
  model: "gpt-5.6-terra",
  reasoning_effort: "none",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Who is the current president of France?" },
  ],
  functions: [
    {
      name: "web_search",
      description: "Search the web for information",
      parameters: {
        type: "object",
        properties: { query: { type: "string" } },
        required: ["query"],
      },
    },
  ],
});

9. Code auf häufige Migrationsfehler prüfen

Achte auf diese Fehler, wenn du Code von Chat Completions auf Responses umstellst:

  • Du liest choices[0].message.content anstelle von response.output_text oder response.output aus.
  • Du behandelst jeden Eintrag in output als Nachricht. Für Reasoning, Tool-Aufrufe und Funktionsaufrufe gibt es eigene Elementtypen.
  • Du lässt Elemente für Reasoning, Funktionsaufrufe oder deren Ausgaben weg, wenn du den Kontext manuell für die nächste Antwort übergibst.
  • Du sendest ein Funktionsergebnis ohne die zugehörige call_id.
  • Du verwendest in einer Responses-Anfrage response_format anstelle von text.format.
  • Du verwendest den Code zur Verarbeitung von Streaming-Datenblöcken aus Chat Completions weiter, ohne die typisierten Ereignisse von Responses zu verarbeiten.
  • Du gehst davon aus, dass bei Verwendung von previous_response_id für den bisherigen Kontext keine Kosten anfallen. Die bisherigen Eingabetoken der Antwortkette werden weiterhin als Eingabetoken abgerechnet.

Checkliste für die schrittweise Umstellung

Wir unterstützen Chat Completions weiterhin. Du kannst die Abläufe in deiner Anwendung also einzeln migrieren.

  • Beginne mit einem Ablauf zur Textgenerierung.
  • Aktualisiere den Endpunkt, den Anfragekörper und die Verarbeitung der Ausgabe.
  • Lege fest, ob du für diesen Ablauf previous_response_id verwendest, Elemente manuell erneut übergibst oder die Conversations API nutzt.
  • Füge bei einem zustandslosen Ablauf oder bei ZDR store: false hinzu. Übergib verschlüsselte Reasoning-Elemente, wenn du den Reasoning-Kontext über mehrere Gesprächsrunden hinweg benötigst.
  • Migriere die Funktionsdefinitionen und prüfe, ob die Ausgaben der Funktionsaufrufe die richtige call_id enthalten.
  • Verschiebe die Schemas für strukturierte Ausgaben von response_format nach text.format.
  • Passe die Stream-Verarbeitung an die typisierten Ereignisse von Responses an.
  • Ersetze deine eigene Orchestrierung durch von OpenAI gehostete Tools, wo sie zum Workflow passen.
  • Vergleiche Verhalten, Latenz, Tokenverbrauch und Fehler, bevor du weitere Anfragen an Responses leitest.

Wir empfehlen, nach und nach alle Abläufe auf die Responses API umzustellen, damit du die neuesten Funktionen und Verbesserungen von OpenAI nutzen kannst.

Assistants API

Auf Grundlage der Rückmeldungen aus der Entwicklercommunity zur Betaversion der Assistants API haben wir die Responses API in wichtigen Punkten verbessert. Dadurch ist sie flexibler, schneller und einfacher zu nutzen. Die Responses API bildet künftig die Grundlage für die Entwicklung von Agenten mit OpenAI.

OpenAI hat die Assistants API am 26. August 2026 offiziell eingestellt. Sie ist nicht mehr verfügbar. Folge dem Migrationsleitfaden, um deine Integration auf die Responses API umzustellen.