OpenAI Responses API 이해하기

기술의 발전 속도가 매우 빠르다. 특히 OpenAI를 사용할 때는 더 빠르게 느껴진다.

Chat Completions API를 잘 사용하고 있었는데, 새로운 API가 나왔다.

(글 작성시점은 8월인데 3월에 나온 것으로 안다.)

 

OpenAI Responses API를 알아보자.

https://platform.openai.com/docs/guides/migrate-to-responses#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, images, and audio.

3가지 큰 특징이 있다.

• built-in tools를 사용할 수 있고
• multi-turn interactions을 편리하게 사용할 수 있고
• multimodal을 지원한다.

Responses benefits

The Responses API contains several benefits over Chat Completions:

• Stateful conversations: Use store: true and previous_response_id to maintain context without resending the entire history.
• Encrypted reasoning: Keep your workflow stateless while still benefiting from reasoning items.
• Built-in tools: Add capabilities like web_search_preview, file_search, and custom function calls directly in your request.
• Flexible inputs: Pass a string with input or a list of messages; use instructions for system-level guidance.
• Better reasoning: Results in better reasoning performance (3% improvement in SWE-benchmark with same prompt and setup compared to Chat Completions)
• Lower costs: Results in lower costs due to improved cache utilization (40% to 80% improvementwhen compared to Chat Completions in internal tests).
• Future-proof: Future-proofed for upcoming models.

Benefits에서는 store: true 설정을 하면 previous_response_id를 통해 context를 유지할 수 있는 점이 가장 큰 특성이다.

 

Comparison to Chat Completions

The Responses API is a superset of the Chat Completions API. It has a predictable, event-driven architecture, whereas the Chat Completions API continuously appends to the content field as tokens are generated—requiring you to manually track differences between each state. Multi-step conversational logic and reasoning are easier to implement with the Responses API.

The Responses API clearly emits semantic events detailing precisely what changed (e.g., specific text additions), so you can write integrations targeted at specific emitted events (e.g., text changes), simplifying integration and improving type safety.

 

Responses API는 Chat Completions API의 superset이다.

Multi-step conversational logic, reasoning을 다루는데 좀 더 적합한데, Chat Completions API와 달리 content를 직접 관리하지 않아도 된다.

두 API의 차이점을 정리한 표이다. built-in tools 지원 유무가 다르다.

 

Chat Completions API에 익숙한 유저라면 어떤 차이점이 있는지 잘 구별해서 써야한다.

두 API의 호출과 응답 형태를 보자.

	Chat Completions API	Responses API
호출	from openai import OpenAI client = OpenAI() completion = client.chat.completions.create(   model="gpt-5",   messages=[       {           "role": "user",           "content": "Write a one-sentence bedtime story about a unicorn."       }   ] ) print(completion.choices[0].message.content)	from openai import OpenAI client = OpenAI() response = client.responses.create(   model="gpt-5",   input=[       {           "role": "user",           "content": "Write a one-sentence bedtime story about a unicorn."       }   ] ) print(response.output_text)
응답	[ {   "index": 0,   "message": {     "role": "assistant",     "content": "Under the soft glow of the moon, Luna the unicorn danced through fields of twinkling stardust, leaving trails of dreams for every child asleep.",     "refusal": null   },   "logprobs": null,   "finish_reason": "stop" } ]	[ {   "id": "msg_67b73f697ba4819183a15cc17d011509",   "type": "message",   "role": "assistant",   "content": [     {       "type": "output_text",       "text": "Under the soft glow of the moon, Luna the unicorn danced through fields of twinkling stardust, leaving trails of dreams for every child asleep.",       "annotations": []     }   ] } ]

payload 형태와 response의 형태가 다르다.

 

Additional differences

• Reasoning models have a richer experience in the Responses API with improved tool usage.
• The Responses API returns output, while the Chat Completions API returns a choices array.
• Structured Outputs API shape is different. Instead of response_format, use text.format in Responses. Learn more in the Structured Outputs guide.
• 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.
• Conversation state: You have to manage conversation state yourself in Chat Completions, while Responses has previous_response_id to help you with long-running conversations.
• Responses are stored by default. Chat completions are stored by default for new accounts. To disable storage, set store: false.

추가로 보면 여러 부분에서 Chat Completions API와의 차이가 있다.

• output의 형태가 다르고, response_format에서 차이, function calling 형태가 다르다.