For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
기본 탐색 메뉴
Theme

Responses API로 마이그레이션하기

Responses API는 Chat Completions에서 발전한 OpenAI의 새로운 기본 API입니다. 애플리케이션에 더 간편하게 통합할 수 있으며, 에이전트를 구현하는 데 필요한 강력한 기본 기능을 제공합니다.

Chat Completions는 계속 지원되며, 모든 신규 프로젝트에는 Responses를 권장합니다.

Responses API 소개

Responses API는 에이전트처럼 동작하는 강력한 애플리케이션을 구축하기 위한 통합 인터페이스입니다. 다음 기능을 제공합니다.

  • 웹 검색, 파일 검색, 컴퓨터 사용, 코드 인터프리터, 원격 MCP 서버 등의 기본 제공 도구를 사용할 수 있습니다.
  • 여러 턴에 걸쳐 대화를 자연스럽게 이어 갈 수 있습니다. 이전 응답을 전달하면 더 정확한 추론 결과를 얻을 수 있습니다.
  • 텍스트와 이미지를 함께 처리하는 멀티모달 기능을 기본으로 지원합니다.

Responses의 장점

Responses API는 Chat Completions에 비해 다음과 같은 장점이 있습니다.

  • 성능 향상: GPT-5와 같은 추론 모델은 Chat Completions보다 Responses에서 문제를 더 잘 해결합니다. 동일한 프롬프트와 설정으로 진행한 내부 평가에서 SWE-bench 성능이 3% 향상되었습니다.
  • 에이전트 루프 기본 지원: 모델은 API 요청 한 번으로 web_search, image_generation, file_search, code_interpreter, 원격 MCP 서버, 직접 정의한 함수 등 여러 도구를 호출할 수 있습니다.
  • 비용 절감: 캐시를 더 효율적으로 활용해 비용이 줄어듭니다. 내부 테스트에서 캐시 활용 효율이 Chat Completions보다 40~80% 향상되었습니다.
  • 턴 간 컨텍스트 유지: store: true를 설정하면 턴이 바뀌어도 상태가 유지되어 추론과 도구 사용에 관한 컨텍스트가 보존됩니다.
  • 유연한 입력: input에 문자열이나 메시지 목록을 전달할 수 있습니다. 시스템 수준의 지침은 instructions로 전달합니다.
  • 암호화된 추론: 상태를 저장하지 않고도 고급 추론 기능을 사용할 수 있습니다.
  • 향후 모델 지원: 앞으로 출시될 모델을 지원하도록 설계되었습니다.
기능 Chat Completions API Responses API
텍스트 생성
오디오 지원 예정
이미지 인식
구조화된 출력값
함수 호출
웹 검색
파일 검색
컴퓨터 사용
코드 인터프리터
MCP
이미지 생성
추론 요약

예시

구체적인 예시를 통해 Responses API와 Chat Completions API의 차이를 살펴보세요.

메시지와 항목의 차이

두 API 모두 OpenAI 모델로 출력을 생성할 수 있습니다. Chat Completions 호출에서는 입력과 결과를 메시지 배열로 표현하지만 Responses API에서는 항목 단위로 표현합니다. 항목은 모델이 수행할 수 있는 다양한 동작을 나타내는 여러 타입의 유니온입니다. message는 항목 타입 중 하나이며, function_call과 function_call_output도 각각 하나의 항목 타입입니다. Chat Completions 메시지는 여러 역할을 하나의 객체에 담지만, Responses에서는 역할별로 항목을 구분하므로 모델 컨텍스트의 기본 단위를 더 잘 표현할 수 있습니다.

또한 Chat Completions는 여러 결과를 병렬로 생성해 choices로 반환할 수 있습니다. 생성할 결과 수는 n 매개변수로 지정합니다. Responses API에는 이 매개변수가 없으며 결과를 하나만 반환합니다.

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)

Responses API가 반환하는 응답은 필드 구성이 조금 다릅니다. message 대신 타입이 지정된 response 객체를 받으며, 이 객체에는 고유한 id가 있습니다. Responses는 기본적으로 응답을 저장합니다. Chat Completions는 신규 계정에서 기본적으로 응답을 저장합니다. 어느 API에서든 저장을 비활성화하려면 store: false를 설정하세요.

두 API가 반환하는 객체의 구조도 조금 다릅니다. Chat Completions에서는 choices 배열을 받으며, 각 요소에는 message가 들어 있습니다. Responses에서는 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"
    }
  ],
  ...
}

그 밖의 차이점

  • Responses는 기본적으로 응답을 저장합니다. Chat Completions는 신규 계정에서 기본적으로 응답을 저장합니다. 어느 API에서든 저장을 비활성화하려면 store: false를 설정하세요.
  • 추론 모델은 Responses API에서 도구를 더 효과적으로 활용할 수 있습니다. GPT-5.4부터 Chat Completions에서는 reasoning_effort 값이 none일 때만 도구 호출을 지원합니다.
  • 구조화된 출력값을 지정하는 API 형식이 다릅니다. Responses에서는 response_format 대신 text.format을 사용하세요. 자세한 내용은 구조화된 출력값 가이드를 참고하세요.
  • 함수 호출의 API 형식도 다릅니다. 요청에서 함수를 설정하는 형식과 응답으로 반환되는 함수 호출 형식이 모두 달라집니다. 전체 차이점은 함수 호출 가이드에서 확인하세요.
  • Responses SDK에는 output_text 헬퍼가 있습니다. Chat Completions SDK에는 이 헬퍼가 없습니다.
  • Chat Completions에서는 대화 상태를 직접 관리해야 합니다. Responses API에서는 Conversations API로 대화를 지속적으로 유지하거나 previous_response_id를 전달해 응답을 서로 연결할 수 있습니다.

Chat Completions에서 마이그레이션하기

마이그레이션할 때는 서로 연관된 세 가지를 함께 살펴보세요. 요청을 /v1/responses로 보내고, 타입이 지정된 항목으로 구성된 output 배열에서 출력을 읽고, 애플리케이션에서 턴 간 상태를 유지할 방법을 선택하세요.

1. 생성 엔드포인트 변경하기

먼저 생성 엔드포인트를 post /v1/chat/completions에서 post /v1/responses로 변경하세요.

함수나 멀티모달 입력을 사용하지 않는다면 텍스트만 포함된 메시지 입력을 두 API에서 그대로 사용할 수 있습니다.

텍스트만 포함된 메시지 입력 재사용하기
const context = [
  { 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,
});

Chat Completions에서는 messages 배열을 만들고 모델이 생성한 텍스트를 completion.choices[0].message.content에서 읽습니다.

모델로 텍스트 생성하기
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. 메시지를 항목에 매핑하기

Chat Completions에서는 입력과 출력에 모두 messages를 사용합니다. Responses에서는 input과 output에 타입이 지정된 항목의 배열을 사용합니다. message는 항목 타입 중 하나이며, 그 밖에도 reasoning, function_call, function_call_output 등의 항목 타입이 있습니다.

Chat Completions의 개념 Responses에서의 대응 방식
messages[] input에 문자열 또는 입력 항목 배열 전달
시스템 또는 개발자 지침 최상위 instructions에 지정. 기존 대화 기록을 보존해야 한다면 호환되는 메시지 항목 사용
사용자 메시지 role: "user"가 지정된 입력 메시지 항목
어시스턴트 메시지 response.output에 포함된 출력 메시지 항목. 상태를 직접 관리한다면 input에 다시 전달
도구 또는 함수 호출 function_call 출력 항목
도구 또는 함수 실행 결과 function_call_output 입력 항목. call_id로 해당 호출과 연결
n을 사용한 여러 결과 생성 Responses에서는 지원하지 않음. 후보 출력이 여러 개 필요하면 각각 별도로 요청

최종 텍스트만 필요하다면 SDK의 output_text 헬퍼를 사용하세요. 플로우에서 추론, 도구 또는 멀티모달 출력을 사용한다면 response.output을 순회하면서 각 항목을 type에 따라 처리하세요.

3. 멀티턴 대화 처리 방식 변경하기

애플리케이션에서 여러 턴에 걸쳐 대화를 이어 간다면 컨텍스트 처리 로직을 변경하세요. Responses에서 흔히 사용하는 상태 관리 방식은 세 가지입니다.

  • OpenAI가 이전 응답의 컨텍스트를 관리하도록 하려면 previous_response_id를 사용하세요. 매번 동일하게 적용할 instructions는 요청마다 다시 보내세요. previous_response_id를 사용해도 이전 응답의 최상위 instructions는 다음 요청에 전달되지 않습니다.
  • 컨텍스트를 직접 관리하거나 줄여야 한다면 이전 output 항목을 다음 요청의 입력으로 다시 전달하세요.
  • 지속적으로 유지되는 대화 객체가 필요하다면 Conversations API를 사용하세요.

Chat Completions에서는 대화 기록을 저장하고 요청할 때마다 지금까지 누적된 messages 배열을 보냅니다.

멀티턴 대화
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-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,
});

previous_response_id를 사용하더라도 응답 체인에서 이전 응답을 생성할 때 사용한 모든 입력 토큰은 API에서 입력 토큰으로 과금됩니다.

4. 상태를 저장할 시점 결정하기

Responses는 기본적으로 응답을 저장합니다. Chat Completions는 신규 계정에서 기본적으로 응답을 저장합니다. 어느 API에서든 저장을 비활성화하려면 store: false를 설정하세요.

데이터 비보관(ZDR) 요건을 적용하는 조직 등 일부 조직은 규정 준수 요건이나 데이터 보존 정책 때문에 상태를 저장하는 방식으로 Responses API를 사용할 수 없습니다. 이런 경우를 위해 OpenAI는 암호화된 추론 항목을 제공합니다. 워크플로우에서 상태를 저장하지 않고도 추론 항목을 활용할 수 있습니다.

상태 저장을 중단하고 추론을 계속 사용하려면 다음과 같이 설정하세요.

  • store: false를 store 필드에 설정하세요.
  • 반환된 추론 항목을 모두 보존하고 다음 요청에 다시 전달하세요. 응답을 생성하면 각 추론 항목에 기본적으로 encrypted_content가 포함됩니다.

이렇게 하면 API가 추론 토큰을 암호화해 반환합니다. 일반 추론 항목과 마찬가지로 이후 요청에 다시 전달할 수 있습니다. ZDR 조직에는 OpenAI가 store: false를 자동으로 적용합니다. 요청에 encrypted_content가 포함되어 있으면 메모리에서 복호화해 다음 응답을 생성하는 데 사용한 뒤 안전하게 폐기합니다. 새로 생성한 추론 토큰도 즉시 암호화해 반환하므로 중간 상태가 영구 저장되지 않습니다.

5. 함수 정의와 출력 변경하기

Chat Completions와 Responses의 함수 정의 방식에는 두 가지 차이가 있습니다.

  1. Chat Completions에서는 함수 정의 외부에 타입 태그를 지정합니다. Responses에서는 함수 정의 내부에 지정합니다.
  2. Chat Completions에서는 기본적으로 함수에 엄격 모드를 적용하지 않습니다. Responses에서는 strict를 생략하면 먼저 엄격 모드를 적용하려고 시도합니다. 스키마를 엄격 모드와 호환되도록 조정할 수 없으면 비엄격 모드로 전환해 가능한 범위에서 스키마에 맞춰 함수를 호출하고, 최종 도구 정의에 strict: false를 포함해 반환합니다. Responses에서 비엄격 모드를 명시적으로 유지하려면 strict: false를 설정하세요.

오른쪽의 Responses API 함수 예시는 왼쪽의 Chat Completions 예시와 동일하게 동작합니다.

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"
    ]
  }
}

함수 호출 권장 사항 따르기

Responses에서 도구 호출과 호출 결과는 서로 다른 타입의 항목이며, call_id로 연결됩니다. Responses에서 함수 호출이 어떻게 동작하는지 자세히 알아보려면 함수 호출 문서를 참고하세요.

6. 구조화된 출력값 정의 변경하기

Responses API에서는 구조화된 출력값의 정의 위치가 response_format에서 text.format으로 바뀌었습니다.

구조화된 출력값
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. 스트림 처리 로직 변경하기

Chat Completions는 스트리밍 시 delta 필드에 새로 생성된 내용을 담아 청크 단위로 반환합니다. Responses는 타입이 지정된 서버 전송 이벤트를 사용합니다. 스트림 처리 로직이 각 이벤트의 type에 따라 분기하도록 변경하고, UI나 오케스트레이션 계층에 필요한 이벤트를 처리하세요.

텍스트를 스트리밍할 때는 다음과 같은 이벤트를 수신하세요.

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

함수 호출 스트림에서는 response.function_call_arguments.delta와 response.function_call_arguments.done 같은 이벤트도 발생할 수 있습니다. Responses 스트리밍 가이드와 Responses 스트리밍 이벤트 레퍼런스를 참고하세요.

8. 기본 제공 도구로 전환하기

애플리케이션에 OpenAI의 기본 제공 도구가 적합한 사용 사례가 있다면, 도구 호출을 변경해 OpenAI 도구를 바로 사용할 수 있습니다.

Chat Completions에서는 OpenAI가 호스팅하는 도구를 기본 기능으로 사용할 수 없어 도구 연동 코드를 직접 작성해야 합니다. 이 예시에서는 추론을 비활성화한 GPT-5.6 Terra를 사용합니다. GPT-6 Astra와 GPT-6.1 Sol에서 도구를 호출하려면 Responses API를 사용해야 합니다.

웹 검색 도구
async function web_search(query) {
  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. 마이그레이션 시 자주 발생하는 오류 확인하기

Chat Completions에서 Responses로 코드를 옮길 때는 다음과 같은 실수에 주의하세요.

  • 기존의 choices[0].message.content를 계속 읽는 경우. Responses에서는 response.output_text 또는 response.output을 읽어야 합니다.
  • output의 모든 항목을 메시지로 처리하는 경우. 추론, 도구 호출, 함수 호출은 별도의 항목 타입입니다.
  • 다음 응답에 컨텍스트를 직접 전달하면서 추론, 함수 호출 또는 함수 호출 출력 항목을 누락하는 경우.
  • 함수 실행 결과를 보낼 때 해당 호출의 call_id를 누락하는 경우.
  • Responses 요청에 response_format을 사용하는 경우. Responses에서는 text.format을 사용해야 합니다.
  • Chat Completions의 스트리밍 청크 핸들러를 재사용하면서 Responses 이벤트를 타입별로 처리하지 않는 경우.
  • previous_response_id를 사용하면 이전 컨텍스트에 대한 요금이 발생하지 않는다고 가정하는 경우. 응답 체인의 이전 입력 토큰도 입력 토큰으로 과금됩니다.

단계적 전환 체크리스트

Chat Completions는 계속 지원되므로 사용자 플로우를 하나씩 마이그레이션할 수 있습니다.

  • 텍스트 생성 플로우부터 시작하세요.
  • 엔드포인트, 요청 본문, 출력 처리 방식을 변경하세요.
  • 플로우에서 previous_response_id를 사용할지, 이전 항목을 직접 다시 전달할지, Conversations API를 사용할지 결정하세요.
  • 상태를 저장하지 않는 플로우이거나 ZDR이 적용된다면 store: false를 추가하세요. 이때 여러 턴에 걸쳐 추론 컨텍스트를 유지해야 한다면 암호화된 추론 항목도 포함하세요.
  • 함수 정의를 마이그레이션하고 함수 호출 출력에 올바른 call_id가 포함되어 있는지 확인하세요.
  • 구조화된 출력값 스키마를 response_format에서 text.format으로 옮기세요.
  • Responses 이벤트를 타입별로 처리하도록 스트림 처리 로직을 변경하세요.
  • 워크플로우에 적합하다면 직접 구현한 오케스트레이션을 OpenAI가 호스팅하는 도구로 대체하세요.
  • Responses로 보내는 트래픽을 늘리기 전에 동작, 지연 시간, 토큰 사용량, 오류를 비교하세요.

OpenAI의 최신 기능과 개선 사항을 활용하려면 모든 플로우를 단계적으로 Responses API로 마이그레이션하는 것이 좋습니다.

Assistants API

OpenAI는 Assistants API 베타에 대한 개발자 의견을 반영해 Responses API의 유연성과 속도를 높이고 사용법을 간소화했습니다. 앞으로 OpenAI에서 에이전트를 구축하는 데 중심이 될 API는 Responses API입니다.

Assistants API는 2026년 8월 26일에 공식 종료되어 더 이상 사용할 수 없습니다. 마이그레이션 가이드에 따라 애플리케이션을 Responses API로 전환하세요.