Migrate to the Responses API

import { CheckCircleFilled, XCircle, } from "@components/react/oai/platform/ui/Icon.react";

The Responses API is our new API primitive, an evolution of Chat Completions which brings added simplicity and powerful agentic primitives to your integrations.

While Chat Completions remains supported, Responses is recommended for all new projects.

About the Responses API

The Responses API is a unified interface for building powerful, agent-like applications. It contains:

Built-in tools like web search, file search , computer use, code interpreter, and remote MCPs.
Seamless multi-turn interactions that allow you to pass previous responses for higher accuracy reasoning results.
Native multimodal support for text and images.

Responses benefits

The Responses API contains several benefits over Chat Completions:

Better performance: Using reasoning models, like GPT-5, with Responses will result in better model intelligence when compared to Chat Completions. Our internal evals reveal a 3% improvement in SWE-bench with same prompt and setup.
Agentic by default: The Responses API is an agentic loop, allowing the model to call multiple tools, like web_search, image_generation, file_search, code_interpreter, remote MCP servers, as well as your own custom functions, within the span of one API request.
Lower costs: Results in lower costs due to improved cache utilization (40% to 80% improvement when compared to Chat Completions in internal tests).
Stateful context: Use store: true to maintain state from turn to turn, preserving reasoning and tool context from turn-to-turn.
Flexible inputs: Pass a string with input or a list of messages; use instructions for system-level guidance.
Encrypted reasoning: Opt-out of statefulness while still benefiting from advanced reasoning.
Future-proof: Future-proofed for upcoming models.

Capabilities	Chat Completions API	Responses API
Text generation
Audio		Coming soon
Vision
Structured Outputs
Function calling
Web search
File search
Computer use
Code interpreter
MCP
Image generation
Reasoning summaries

Examples

See how the Responses API compares to the Chat Completions API in specific scenarios.

Messages vs. Items

Both APIs make it easy to generate output from our models. The input to, and result of, a call to Chat completions is an array of Messages, while the Responses API uses Items. An Item is a union of many types, representing the range of possibilities of model actions. A message is a type of Item, as is a function_call or function_call_output. Unlike a Chat Completions Message, where many concerns are glued together into one object, Items are distinct from one another and better represent the basic unit of model context.

Additionally, Chat Completions can return multiple parallel generations as choices, using the n param. In Responses, we've removed this param, leaving only one generation.

When you get a response back from the Responses API, the fields differ slightly. Instead of a message, you receive a typed response object with its own id. Responses are stored by default. Chat completions are stored by default for new accounts. To disable storage when using either API, set store: false.

The objects you receive back from these APIs will differ slightly. In Chat Completions, you receive an array of choices, each containing a message. In Responses, you receive an array of Items labeled output.

Additional differences

Responses are stored by default. Chat completions are stored by default for new accounts. To disable storage in either API, set store: false.
Reasoning models have a richer experience in the Responses API with improved tool usage. Starting with GPT-5.4, tool calling is not supported in Chat Completions with reasoning: none.
Structured Outputs API shape is different. Instead of response_format, use text.format in Responses. Learn more in the Structured Outputs guide.
The function-calling API shape is different, both for the function config on the request, and function calls sent back in the response. See the full difference in the function calling guide.
The Responses SDK has an output_text helper, which the Chat Completions SDK does not have.
In Chat Completions, conversation state must be managed manually. The Responses API has compatibility with the Conversations API for persistent conversations, or the ability to pass a previous_response_id to easily chain Responses together.

Migrating from Chat Completions

1. Update generation endpoints

Start by updating your generation endpoints from post /v1/chat/completions to post /v1/responses.

If you are not using functions or multimodal inputs, then you're done! Simple message inputs are compatible from one API to the other:

Web search tool

INPUT='[
  { "role": "system", "content": "You are a helpful assistant." },
  { "role": "user", "content": "Hello!" }
]'

curl -s https://api.openai.com/v1/chat/completions \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $OPENAI_API_KEY" \\
  -d "{
    \\"model\\": \\"gpt-5.5\\",
    \\"messages\\": $INPUT
  }"

curl -s https://api.openai.com/v1/responses \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $OPENAI_API_KEY" \\
  -d "{
    \\"model\\": \\"gpt-5.5\\",
    \\"input\\": $INPUT
  }"

const context = [
  { role: 'system', content: 'You are a helpful assistant.' },
  { role: 'user', content: 'Hello!' }
];

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

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

context = [
  { "role": "system", "content": "You are a helpful assistant." },
  { "role": "user", "content": "Hello!" }
]

completion = client.chat.completions.create(
  model="gpt-5.5",
  messages=context
)

response = client.responses.create(
  model="gpt-5.5",
  input=context
)

<> With Chat Completions, you need to create an array of messages that specify different roles and content for each role.

                    Generate text from a model

import OpenAI from 'openai';
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

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

from openai import OpenAI
client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ]
)
print(completion.choices[0].message.content)

curl https://api.openai.com/v1/chat/completions \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $OPENAI_API_KEY" \\
  -d '{
      "model": "gpt-5.5",
      "messages": [
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "Hello!"}
      ]
  }'

</>

<> With Responses, you can separate instructions and input at the top-level. The API shape is similar to Chat Completions but has cleaner semantics.

                    Generate text from a model

import OpenAI from 'openai';
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const response = await client.responses.create({
  model: 'gpt-5.5',
  instructions: 'You are a helpful assistant.',
  input: 'Hello!'
});

console.log(response.output_text);

from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="gpt-5.5",
    instructions="You are a helpful assistant.",
    input="Hello!"
)
print(response.output_text)

curl https://api.openai.com/v1/responses \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $OPENAI_API_KEY" \\
  -d '{
      "model": "gpt-5.5",
      "instructions": "You are a helpful assistant.",
      "input": "Hello!"
  }'

</>

2. Update item definitions

<> With Chat Completions, you need to create an array of messages that specify different roles and content for each role.

                    Generate text from a model

import OpenAI from 'openai';
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

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

from openai import OpenAI
client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ]
)
print(completion.choices[0].message.content)

curl https://api.openai.com/v1/chat/completions \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $OPENAI_API_KEY" \\
  -d '{
      "model": "gpt-5.5",
      "messages": [
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "Hello!"}
      ]
  }'

</>

<> With Responses, you can separate instructions and input at the top-level. The API shape is similar to Chat Completions but has cleaner semantics.

                    Generate text from a model

import OpenAI from 'openai';
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const response = await client.responses.create({
  model: 'gpt-5.5',
  instructions: 'You are a helpful assistant.',
  input: 'Hello!'
});

console.log(response.output_text);

from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="gpt-5.5",
    instructions="You are a helpful assistant.",
    input="Hello!"
)
print(response.output_text)

curl https://api.openai.com/v1/responses \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $OPENAI_API_KEY" \\
  -d '{
      "model": "gpt-5.5",
      "instructions": "You are a helpful assistant.",
      "input": "Hello!"
  }'

</>

3. Update multi-turn conversations

If you have multi-turn conversations in your application, update your context logic.

<> In Chat Completions, you have to store and manage context yourself.

                    Multi-turn conversation

let messages = [
    { '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-5.5',
  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-5.5',
  messages
});

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is the capital of France?"}
]
res1 = client.chat.completions.create(model="gpt-5.5", messages=messages)

messages += [res1.choices[0].message]
messages += [{"role": "user", "content": "And its population?"}]

res2 = client.chat.completions.create(model="gpt-5.5", messages=messages)

</>

<> With responses, the pattern is similar, you can pass outputs from one response to the input of another.

                    Multi-turn conversation

context = [
    { "role": "user", "content": "What is the capital of France?" }
]
res1 = client.responses.create(
    model="gpt-5.5",
    input=context,
)

# Append the first response's output to context
context += res1.output

# Add the next user message
context += [
    { "role": "user", "content": "And its population?" }
]

res2 = client.responses.create(
    model="gpt-5.5",
    input=context,
)

let context = [
  { role: "user", content: "What is the capital of France?" }
];

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

// Append the first response’s output to context
context = context.concat(res1.output);

// Add the next user message
context.push({ role: "user", content: "And its population?" });

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

                    As a simplification, we've also built a way to simply reference inputs and outputs from a previous response by passing its id.
                    You can use `previous_response_id` to form chains of responses that build upon one other or create forks in a history.

                    Multi-turn conversation

const res1 = await client.responses.create({
  model: 'gpt-5.5',
  input: 'What is the capital of France?',
  store: true
});

const res2 = await client.responses.create({
  model: 'gpt-5.5',
  input: 'And its population?',
  previous_response_id: res1.id,
  store: true
});

res1 = client.responses.create(
    model="gpt-5.5",
    input="What is the capital of France?",
    store=True
)

res2 = client.responses.create(
    model="gpt-5.5",
    input="And its population?",
    previous_response_id=res1.id,
    store=True
)

</>

### 4. Decide when to use statefulness

Some organizations—such as those with Zero Data Retention (ZDR) requirements—cannot use the Responses API in a stateful way due to compliance or data retention policies. To support these cases, OpenAI offers encrypted reasoning items, allowing you to keep your workflow stateless while still benefiting from reasoning items.

To disable statefulness, but still take advantage of reasoning:
- set `store: false` in the [store field](https://developers.openai.com/api/docs/api-reference/responses/create#responses_create-store)
- add `["reasoning.encrypted_content"]` to the [include field](https://developers.openai.com/api/docs/api-reference/responses/create#responses_create-include)

The API will then return an encrypted version of the reasoning tokens, which you can pass back in future requests just like regular reasoning items.
For ZDR organizations, OpenAI enforces store=false automatically. When a request includes encrypted_content, it is decrypted in-memory (never written to disk), used for generating the next response, and then securely discarded. Any new reasoning tokens are immediately encrypted and returned to you, ensuring no intermediate state is ever persisted.


### 5. Update function definitions

There are two minor, but notable, differences in how functions are defined between Chat Completions and Responses.

1. In Chat Completions, functions are defined using externally tagged polymorphism, whereas in Responses, they are internally-tagged.
2. In Chat Completions, functions are non-strict by default, whereas in the Responses API, functions _are_ strict by default.

The Responses API function example on the right is functionally equivalent to the Chat Completions example on the left.

#### Follow function-calling best practices

In Responses, tool calls and their outputs are two distinct types of Items that are correlated using a `call_id`. See
the [tool calling docs](https://developers.openai.com/api/docs/guides/function-calling#function-tool-example) for more detail on how function calling works in Responses.

### 6. Update Structured Outputs definition

In the Responses API, defining structured outputs have moved from `response_format` to `text.format`:

Structured Outputs

curl https://api.openai.com/v1/chat/completions \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $OPENAI_API_KEY" \\
  -d '{
  "model": "gpt-5.5",
  "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"
}'

from openai import OpenAI
client = OpenAI()

response = client.chat.completions.create(
  model="gpt-5.5",
  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"
)

const completion = await openai.chat.completions.create({
  model: "gpt-5.5",
  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"
});

Structured Outputs

curl https://api.openai.com/v1/responses \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $OPENAI_API_KEY" \\
  -d '{
  "model": "gpt-5.5",
  "input": "Jane, 54 years old",
  "text": {
    "format": {
      "type": "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
      }
    }
  }
}'

response = client.responses.create(
  model="gpt-5.5",
  input="Jane, 54 years old", 
  text={
    "format": {
      "type": "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
      }
    }
  }
)

const response = await openai.responses.create({
  model: "gpt-5.5",
  input: "Jane, 54 years old",
  text: {
    format: {
      type: "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
      }
    },
  }
});

### 7. Upgrade to native tools

If your application has use cases that would benefit from OpenAI's native [tools](https://developers.openai.com/api/docs/guides/tools), you can update your tool calls to use OpenAI's tools out of the box.

<> With Chat Completions, you cannot use OpenAI's tools natively and have to write your own. Web search tool

async function web_search(query) {
    const fetch = (await import('node-fetch')).default;
    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.5',
  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']
      }
    }
  ]
});

import requests

def web_search(query):
    r = requests.get(f"https://api.example.com/search?q={query}")
    return r.json().get("results", [])

completion = client.chat.completions.create(
    model="gpt-5.5",
    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"]
            }
        }
    ]
)

curl https://api.example.com/search \\
  -G \\
  --data-urlencode "q=your+search+term" \\
  --data-urlencode "key=$SEARCH_API_KEY"\

</>

<> With Responses, you can simply specify the tools that you are interested in.

                    Web search tool

const answer = await client.responses.create({
    model: 'gpt-5.5',
    input: 'Who is the current president of France?',
    tools: [{ type: 'web_search' }]
});

console.log(answer.output_text);

answer = client.responses.create(
    model="gpt-5.5",
    input="Who is the current president of France?",
    tools=[{"type": "web_search"}]
)

print(answer.output_text)

curl https://api.openai.com/v1/responses \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $OPENAI_API_KEY" \\
  -d '{
    "model": "gpt-5.5",
    "input": "Who is the current president of France?",
    "tools": [{"type": "web_search"}]
  }'

</>

Incremental migration

The Responses API is a superset of the Chat Completions API, and Chat Completions remains supported. You can migrate one user flow at a time:

Start with a simple text-generation flow and update the endpoint, input, and output handling.
Update multi-turn state management, then migrate function calling and Structured Outputs.
For streaming flows, update consumers to handle typed Responses events such as response.output_text.delta. See the streaming Responses guide.
Compare behavior, latency, and errors before routing more traffic to Responses.

We recommend migrating all flows to the Responses API over time to take advantage of the latest OpenAI features and improvements.

Assistants API

Based on developer feedback from the Assistants API beta, we've incorporated key improvements into the Responses API to make it more flexible, faster, and easier to use. The Responses API represents the future direction for building agents on OpenAI.

We now have Assistant-like and Thread-like objects in the Responses API. Learn more in the migration guide. As of August 26th, 2025, we're deprecating the Assistants API, with a sunset date of August 26, 2026.

guides/migrate-to-responses.md +60 −58

71Responses are stored by default. Chat completions are stored by default for new accounts.71Responses are stored by default. Chat completions are stored by default for new accounts.

72To disable storage when using either API, set `store: false`.72To disable storage when using either API, set `store: false`.

73 73

~~74The objects you recieve back from these APIs will differ slightly. In Chat Completions, you receive an array of~~74The objects you receive back from these APIs will differ slightly. In Chat Completions, you receive an array of

~~75`choices`, each containing a `message`. In Responses, you receive an array of Items labled `output`.~~75`choices`, each containing a `message`. In Responses, you receive an array of Items labeled `output`.

76 76

77### Additional differences77### Additional differences

78 78

103 -H "Content-Type: application/json" \\103 -H "Content-Type: application/json" \\

104 -H "Authorization: Bearer $OPENAI_API_KEY" \\104 -H "Authorization: Bearer $OPENAI_API_KEY" \\

105 -d "{105 -d "{

106 \\"model\\": \\"gpt-5\\",106 \\"model\\": \\"gpt-5.5\\",

107 \\"messages\\": $INPUT107 \\"messages\\": $INPUT

108 }"108 }"

109 109

111 -H "Content-Type: application/json" \\111 -H "Content-Type: application/json" \\

112 -H "Authorization: Bearer $OPENAI_API_KEY" \\112 -H "Authorization: Bearer $OPENAI_API_KEY" \\

113 -d "{113 -d "{

114 \\"model\\": \\"gpt-5\\",114 \\"model\\": \\"gpt-5.5\\",

115 \\"input\\": $INPUT115 \\"input\\": $INPUT

116 }"116 }"

117```117```

123];123];

124 124

125const completion = await client.chat.completions.create({125const completion = await client.chat.completions.create({

126 model: 'gpt-5',126 model: 'gpt-5.5',

127 messages: messages127 messages: context

128});128});

129 129

130const response = await client.responses.create({130const response = await client.responses.create({

131 model: "gpt-5",131 model: "gpt-5.5",

132 input: context132 input: context

133});133});

134```134```

140]140]

141 141

142completion = client.chat.completions.create(142completion = client.chat.completions.create(

143 model="gpt-5",143 model="gpt-5.5",

144 messages=messages144 messages=context

145)145)

146 146

147response = client.responses.create(147response = client.responses.create(

148 model="gpt-5",148 model="gpt-5.5",

149 input=context149 input=context

150)150)

151```151```

165const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });165const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

166 166

167const completion = await client.chat.completions.create({167const completion = await client.chat.completions.create({

168 model: 'gpt-5',168 model: 'gpt-5.5',

169 messages: [169 messages: [

170 { 'role': 'system', 'content': 'You are a helpful assistant.' },170 { 'role': 'system', 'content': 'You are a helpful assistant.' },

171 { 'role': 'user', 'content': 'Hello!' }171 { 'role': 'user', 'content': 'Hello!' }

179client = OpenAI()179client = OpenAI()

180 180

181completion = client.chat.completions.create(181completion = client.chat.completions.create(

182 model="gpt-5",182 model="gpt-5.5",

183 messages=[183 messages=[

184 {"role": "system", "content": "You are a helpful assistant."},184 {"role": "system", "content": "You are a helpful assistant."},

185 {"role": "user", "content": "Hello!"}185 {"role": "user", "content": "Hello!"}

193 -H "Content-Type: application/json" \\193 -H "Content-Type: application/json" \\

194 -H "Authorization: Bearer $OPENAI_API_KEY" \\194 -H "Authorization: Bearer $OPENAI_API_KEY" \\

195 -d '{195 -d '{

196 "model": "gpt-5",196 "model": "gpt-5.5",

197 "messages": [197 "messages": [

198 {"role": "system", "content": "You are a helpful assistant."},198 {"role": "system", "content": "You are a helpful assistant."},

199 {"role": "user", "content": "Hello!"}199 {"role": "user", "content": "Hello!"}

216const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });216const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

217 217

218const response = await client.responses.create({218const response = await client.responses.create({

219 model: 'gpt-5',219 model: 'gpt-5.5',

220 instructions: 'You are a helpful assistant.',220 instructions: 'You are a helpful assistant.',

221 input: 'Hello!'221 input: 'Hello!'

222});222});

229client = OpenAI()229client = OpenAI()

230 230

231response = client.responses.create(231response = client.responses.create(

232 model="gpt-5",232 model="gpt-5.5",

233 instructions="You are a helpful assistant.",233 instructions="You are a helpful assistant.",

234 input="Hello!"234 input="Hello!"

235)235)

241 -H "Content-Type: application/json" \\241 -H "Content-Type: application/json" \\

242 -H "Authorization: Bearer $OPENAI_API_KEY" \\242 -H "Authorization: Bearer $OPENAI_API_KEY" \\

243 -d '{243 -d '{

244 "model": "gpt-5",244 "model": "gpt-5.5",

245 "instructions": "You are a helpful assistant.",245 "instructions": "You are a helpful assistant.",

246 "input": "Hello!"246 "input": "Hello!"

247 }'247 }'

269const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });269const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

270 270

271const completion = await client.chat.completions.create({271const completion = await client.chat.completions.create({

272 model: 'gpt-5',272 model: 'gpt-5.5',

273 messages: [273 messages: [

274 { 'role': 'system', 'content': 'You are a helpful assistant.' },274 { 'role': 'system', 'content': 'You are a helpful assistant.' },

275 { 'role': 'user', 'content': 'Hello!' }275 { 'role': 'user', 'content': 'Hello!' }

283client = OpenAI()283client = OpenAI()

284 284

285completion = client.chat.completions.create(285completion = client.chat.completions.create(

286 model="gpt-5",286 model="gpt-5.5",

287 messages=[287 messages=[

288 {"role": "system", "content": "You are a helpful assistant."},288 {"role": "system", "content": "You are a helpful assistant."},

289 {"role": "user", "content": "Hello!"}289 {"role": "user", "content": "Hello!"}

297 -H "Content-Type: application/json" \\297 -H "Content-Type: application/json" \\

298 -H "Authorization: Bearer $OPENAI_API_KEY" \\298 -H "Authorization: Bearer $OPENAI_API_KEY" \\

299 -d '{299 -d '{

300 "model": "gpt-5",300 "model": "gpt-5.5",

301 "messages": [301 "messages": [

302 {"role": "system", "content": "You are a helpful assistant."},302 {"role": "system", "content": "You are a helpful assistant."},

303 {"role": "user", "content": "Hello!"}303 {"role": "user", "content": "Hello!"}

320const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });320const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

321 321

322const response = await client.responses.create({322const response = await client.responses.create({

323 model: 'gpt-5',323 model: 'gpt-5.5',

324 instructions: 'You are a helpful assistant.',324 instructions: 'You are a helpful assistant.',

325 input: 'Hello!'325 input: 'Hello!'

326});326});

333client = OpenAI()333client = OpenAI()

334 334

335response = client.responses.create(335response = client.responses.create(

336 model="gpt-5",336 model="gpt-5.5",

337 instructions="You are a helpful assistant.",337 instructions="You are a helpful assistant.",

338 input="Hello!"338 input="Hello!"

339)339)

345 -H "Content-Type: application/json" \\345 -H "Content-Type: application/json" \\

346 -H "Authorization: Bearer $OPENAI_API_KEY" \\346 -H "Authorization: Bearer $OPENAI_API_KEY" \\

347 -d '{347 -d '{

348 "model": "gpt-5",348 "model": "gpt-5.5",

349 "instructions": "You are a helpful assistant.",349 "instructions": "You are a helpful assistant.",

350 "input": "Hello!"350 "input": "Hello!"

351 }'351 }'

376 { 'role': 'user', 'content': 'What is the capital of France?' }376 { 'role': 'user', 'content': 'What is the capital of France?' }

377 ];377 ];

378const res1 = await client.chat.completions.create({378const res1 = await client.chat.completions.create({

379 model: 'gpt-5',379 model: 'gpt-5.5',

380 messages380 messages

381});381});

382 382

384messages.push({ 'role': 'user', 'content': 'And its population?' });384messages.push({ 'role': 'user', 'content': 'And its population?' });

385 385

386const res2 = await client.chat.completions.create({386const res2 = await client.chat.completions.create({

387 model: 'gpt-5',387 model: 'gpt-5.5',

388 messages388 messages

389});389});

390```390```

394 {"role": "system", "content": "You are a helpful assistant."},394 {"role": "system", "content": "You are a helpful assistant."},

395 {"role": "user", "content": "What is the capital of France?"}395 {"role": "user", "content": "What is the capital of France?"}

396]396]

397res1 = client.chat.completions.create(model="gpt-5", messages=messages)397res1 = client.chat.completions.create(model="gpt-5.5", messages=messages)

398 398

399messages += [res1.choices[0].message]399messages += [res1.choices[0].message]

400messages += [{"role": "user", "content": "And its population?"}]400messages += [{"role": "user", "content": "And its population?"}]

401 401

402res2 = client.chat.completions.create(model="gpt-5", messages=messages)402res2 = client.chat.completions.create(model="gpt-5.5", messages=messages)

403```403```

404 404

405 </>405 </>

414 414

415```python415```python

416context = [416context = [

417 { "role": "role", "content": "What is the capital of France?" }417 { "role": "user", "content": "What is the capital of France?" }

418]418]

419res1 = client.responses.create(419res1 = client.responses.create(

420 model="gpt-5",420 model="gpt-5.5",

421 input=context,421 input=context,

422)422)

423 423

424// Append the first response’s output to context424# Append the first response's output to context

425context += res1.output425context += res1.output

426 426

427// Add the next user message427# Add the next user message

428context += [428context += [

429 { "role": "role", "content": "And it's population?" }429 { "role": "user", "content": "And its population?" }

430]430]

431 431

432res2 = client.responses.create(432res2 = client.responses.create(

433 model="gpt-5",433 model="gpt-5.5",

434 input=context,434 input=context,

435)435)

436```436```

437 437

438```javascript438```javascript

439let context = [439let context = [

440 { role: "role", content: "What is the capital of France?" }440 { role: "user", content: "What is the capital of France?" }

441];441];

442 442

443const res1 = await client.responses.create({443const res1 = await client.responses.create({

444 model: "gpt-5",444 model: "gpt-5.5",

445 input: context,445 input: context,

446});446});

447 447

449context = context.concat(res1.output);449context = context.concat(res1.output);

450 450

451// Add the next user message451// Add the next user message

452context.push({ role: "role", content: "And its population?" });452context.push({ role: "user", content: "And its population?" });

453 453

454const res2 = await client.responses.create({454const res2 = await client.responses.create({

455 model: "gpt-5",455 model: "gpt-5.5",

456 input: context,456 input: context,

457});457});

458```458```

465 465

466```javascript466```javascript

467const res1 = await client.responses.create({467const res1 = await client.responses.create({

468 model: 'gpt-5',468 model: 'gpt-5.5',

469 input: 'What is the capital of France?',469 input: 'What is the capital of France?',

470 store: true470 store: true

471});471});

472 472

473const res2 = await client.responses.create({473const res2 = await client.responses.create({

474 model: 'gpt-5',474 model: 'gpt-5.5',

475 input: 'And its population?',475 input: 'And its population?',

476 previous_response_id: res1.id,476 previous_response_id: res1.id,

477 store: true477 store: true

480 480

481```python481```python

482res1 = client.responses.create(482res1 = client.responses.create(

483 model="gpt-5",483 model="gpt-5.5",

484 input="What is the capital of France?",484 input="What is the capital of France?",

485 store=True485 store=True

486)486)

487 487

488res2 = client.responses.create(488res2 = client.responses.create(

489 model="gpt-5",489 model="gpt-5.5",

490 input="And its population?",490 input="And its population?",

491 previous_response_id=res1.id,491 previous_response_id=res1.id,

492 store=True492 store=True

540 -H "Content-Type: application/json" \\540 -H "Content-Type: application/json" \\

541 -H "Authorization: Bearer $OPENAI_API_KEY" \\541 -H "Authorization: Bearer $OPENAI_API_KEY" \\

542 -d '{542 -d '{

543 "model": "gpt-5",543 "model": "gpt-5.5",

544 "messages": [544 "messages": [

545 {545 {

546 "role": "user",546 "role": "user",

547 "content": "Jane, 54 years old",547 "content": "Jane, 54 years old"

548 }548 }

549 ],549 ],

550 "response_format": {550 "response_format": {

573 }573 }

574 }574 }

575 },575 },

576 "verbosity": "medium",

577 "reasoning_effort": "medium"576 "reasoning_effort": "medium"

578}'577}'

579```578```

583client = OpenAI()582client = OpenAI()

584 583

585response = client.chat.completions.create(584response = client.chat.completions.create(

586 model="gpt-5",585 model="gpt-5.5",

587 messages=[586 messages=[

588 {587 {

589 "role": "user",588 "role": "user",

616 }615 }

617 }616 }

618 },617 },

619 verbosity="medium",

620 reasoning_effort="medium"618 reasoning_effort="medium"

621)619)

622```620```

623 621

624```javascript622```javascript

625const completion = await openai.chat.completions.create({623const completion = await openai.chat.completions.create({

626 model: "gpt-5",624 model: "gpt-5.5",

627 messages: [625 messages: [

628 {626 {

629 "role": "user",627 "role": "user",

649 }647 }

650 },648 },

651 required: [649 required: [

652 name,650 "name",

653 age651 "age"

654 ],652 ],

655 additionalProperties: false653 additionalProperties: false

656 }654 }

657 }655 }

658 },656 },

659 verbosity: "medium",

660 reasoning_effort: "medium"657 reasoning_effort: "medium"

661});658});

662```659```

671 -H "Content-Type: application/json" \\668 -H "Content-Type: application/json" \\

672 -H "Authorization: Bearer $OPENAI_API_KEY" \\669 -H "Authorization: Bearer $OPENAI_API_KEY" \\

673 -d '{670 -d '{

674 "model": "gpt-5",671 "model": "gpt-5.5",

675 "input": "Jane, 54 years old",672 "input": "Jane, 54 years old",

676 "text": {673 "text": {

677 "format": {674 "format": {

704 701

705```python702```python

706response = client.responses.create(703response = client.responses.create(

707 model="gpt-5",704 model="gpt-5.5",

708 input="Jane, 54 years old", 705 input="Jane, 54 years old",

709 text={706 text={

710 "format": {707 "format": {

737 734

738```javascript735```javascript

739const response = await openai.responses.create({736const response = await openai.responses.create({

740 model: "gpt-5",737 model: "gpt-5.5",

741 input: "Jane, 54 years old",738 input: "Jane, 54 years old",

742 text: {739 text: {

743 format: {740 format: {

758 }755 }

759 },756 },

760 required: [757 required: [

761 name,758 "name",

762 age759 "age"

763 ],760 ],

764 additionalProperties: false761 additionalProperties: false

765 }762 }

793}790}

794 791

795const completion = await client.chat.completions.create({792const completion = await client.chat.completions.create({

796 model: 'gpt-5',793 model: 'gpt-5.5',

797 messages: [794 messages: [

798 { role: 'system', content: 'You are a helpful assistant.' },795 { role: 'system', content: 'You are a helpful assistant.' },

799 { role: 'user', content: 'Who is the current president of France?' }796 { role: 'user', content: 'Who is the current president of France?' }

820 return r.json().get("results", [])817 return r.json().get("results", [])

821 818

822completion = client.chat.completions.create(819completion = client.chat.completions.create(

823 model="gpt-5",820 model="gpt-5.5",

824 messages=[821 messages=[

825 {"role": "system", "content": "You are a helpful assistant."},822 {"role": "system", "content": "You are a helpful assistant."},

826 {"role": "user", "content": "Who is the current president of France?"}823 {"role": "user", "content": "Who is the current president of France?"}

894 891

895## Incremental migration892## Incremental migration

896 893

897The Responses API is a superset of the Chat Completions API. The Chat Completions API will also continue to be supported. As such, you can incrementally adopt the Responses API if desired. You can migrate user flows who would benefit from improved reasoning models to the Responses API while keeping other flows on the Chat Completions API until you're ready for a full migration.894The Responses API is a superset of the Chat Completions API, and Chat Completions remains supported. You can migrate one user flow at a time:

895

8961. Start with a simple text-generation flow and update the endpoint, input, and output handling.

8972. Update multi-turn state management, then migrate function calling and Structured Outputs.

8983. For streaming flows, update consumers to handle typed Responses events such as `response.output_text.delta`. See the [streaming Responses guide](https://developers.openai.com/api/docs/guides/streaming-responses?api-mode=responses).

8994. Compare behavior, latency, and errors before routing more traffic to Responses.

898 900

899As a best practice, we encourage all users to migrate to the Responses API to take advantage of the latest features and improvements from OpenAI.901We recommend migrating all flows to the Responses API over time to take advantage of the latest OpenAI features and improvements.

900 902

901## Assistants API903## Assistants API

902 904

guides/migrate-to-responses.md 2026-06-03 06:53 UTC to 2026-06-04 06:52 UTC

Migrate to the Responses API

About the Responses API

Responses benefits

Examples

Messages vs. Items

Additional differences

Migrating from Chat Completions

1. Update generation endpoints

2. Update item definitions

3. Update multi-turn conversations

Incremental migration

Assistants API