​
Introduction

In the OpenAI ecosystem, developers can interact with models through two main APIs: the Responses API and the Chat Completions API. This guide explores the differences, use cases, and how to choose the right API for your project.

​
Overview Comparison

​
Responses API

  • Positioning: The latest core API, an agent-type API primitive
  • Features: Combines the simplicity of Chat Completions with more agentic capabilities
  • Recommended for: New users
  • Built-in tools: Web search, file search, computer use

​
Chat Completions API

  • Positioning: Industry standard for building AI applications
  • Features: Stable, widely used
  • Future plans: OpenAI plans to support indefinitely

​
When to Use the Responses API

The Responses API is the latest core API and an agent API primitive that combines the simplicity of chat completions with the ability to perform more agentic tasks. As model capabilities continue to evolve, the Responses API will serve as a flexible foundation for building action-oriented applications with built-in tools:
  • Web Search: Allow models to search the internet for up-to-date information
  • File Search: Enable models to search through uploaded files
  • Computer Use: Let models interact with computer interfaces

​
Key Differences

FeatureResponses APIChat Completions API
EndpointPOST /v1/responsesPOST /v1/chat/completions
Input fieldinputmessages
Output formatoutput array with typed itemschoices array with message
Built-in toolsWeb search, file search, computer useFunction calling only
StreamingSSE with typed eventsSSE with data: chunks
Reasoning controlreasoning.effort parameterNot available
Model supportAll models including o3-pro, codex-miniMost models

​
Migration Guide

To migrate from Chat Completions to Responses API:
  1. Change endpoint from /v1/chat/completions to /v1/responses
  2. Rename messages to input
  3. Update response parsing: choices[0].message.content → output[0].content[0].text
  4. Update streaming event handling to use typed SSE events
For more details, see the official OpenAI documentation.