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 of74The 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
