Responses API란? Chat Completions와 차이부터 Codex 연결까지

“AI에게 질문을 보내고 답변을 받는 프로그램을 만들고 싶은데, 설명서를 찾아보니 Chat Completions와 Responses라는 이름이 둘 다 나와요. 무엇이 다른 걸까요?” OpenAI API를 처음 접한다면 충분히 헷갈릴 만합니다. 둘 다 프로그램에서 AI 모델에 요청을 보내고 결과를 받아오는 방법이지만, 요청을 작성하는 모양과 결과를 읽는 방법이 다릅니다. 이번에 알아볼 Responses API는 OpenAI가 제공하는 AI 모델 응답 생성용 인터페이스입니다. OpenAI 공식 문서에서는 새 프로젝트를 만든다면 Responses API를 권장하고 있습니다. 다만 기존 Chat Completions도 지원되므로, 이미 잘 동작하는 프로그램을 무조건 바로 고쳐야 하는 것은 아닙니다. 중요한 것은 이름을 외우는 것이 아니라, 내 프로그램은 어떤 형식으로 질문을 보내고, 어떤 형식으로 답을 받아야 하는지 이해하는 것입니다. 이 글에서는 쉬운 비유부터 간단한 Python 코드, 대화 이어가기, 도구 사용, FreeLLMAPI와 Codex CLI 연결까지 단계적으로 설명하겠습니다.

자체 제작 개념도 · EMFLS AI

이 글의 순서

• 1. API는 알겠는데, Responses는 무슨 뜻인가요?
• 2. Responses API가 기존 방식과 다른 이유
• 3. Responses API의 가장 간단한 예시
• 4. 그럼 Chat Completions 코드는 어떻게 생겼나요?
• 5. 왜 Responses API에는 여러 종류의 출력이 있나요?
• 6. ‘이전 대화 이어가기’는 어떤 기능인가요?
• 7. Responses API로 도구도 사용할 수 있나요?
• 8. FreeLLMAPI에서도 Responses API를 사용할 수 있나요?
• 9. Codex CLI가 왜 Responses API를 필요로 하나요?
• 10. 어떤 오류가 자주 발생할까요?
• 11. Chat Completions에서 Responses로 옮길 때 체크할 내용
• 12. 자주 묻는 질문(FAQ)
• 13. 마무리: Responses API는 AI의 답을 주고받는 새로운 방식입니다
• 공식 자료

1. API는 알겠는데, Responses는 무슨 뜻인가요?

API는 여러 프로그램이 서로 기능을 요청하거나 데이터를 주고받기 위한 약속입니다. 예를 들어 음식점에서 손님이 주문서를 작성하면 주방이 음식을 만들고 주문 결과가 전달됩니다. AI API에서도 비슷한 일이 일어납니다.

• 내 프로그램: AI에게 부탁하고 싶은 일을 전달합니다.
• API 요청: 모델과 입력 내용, 필요한 설정을 일정한 형식에 맞춰 보냅니다.
• AI 모델: 요청을 처리해 결과를 생성합니다.
• API 응답: 결과 텍스트 또는 그 밖의 구조화된 출력 정보를 돌려줍니다. Responses API에서 ‘Responses’는 이러한 응답을 생성하고 관리하는 API의 이름입니다. ChatGPT 채팅창에서 직접 질문하는 것과는 다릅니다. ChatGPT는 사용자가 쓰는 제품이고, Responses API는 개발자가 프로그램에 AI 기능을 연결할 때 사용하는 개발 인터페이스입니다. 예를 들어 블로그 관리 프로그램이 새 글의 설명 문구를 생성하도록 만들 때 API를 이용할 수 있습니다. 하지만 원고를 생성하는 것과 실제 Blogger에 발행하는 것은 별도의 작업입니다.

2. Responses API가 기존 방식과 다른 이유

OpenAI의 기존 API를 공부하다 보면 Chat Completions API라는 이름을 많이 만나게 됩니다. Chat Completions는 일반적으로 질문과 대화 내용을 messages라는 배열에 넣어 보냅니다. 응답은 choices 배열 안에 들어 있습니다. Responses API는 입력을 input이라는 속성으로 받으며, 생성된 결과와 도구 호출 등의 정보를 종류가 구분되는 output 아이템 배열로 다룹니다. 아주 간단하게 정리하면 다음과 같습니다.

항목	Chat Completions	Responses API
대표 주소	\/v1/chat/completions\	\/v1/responses\
주요 입력	\messages\	\input\
출력 구조	\choices\	\output\ 아이템 목록
텍스트 추출	\choices\[0\].message.content\	SDK의 \output_text\ 등
대화 상태	개발자가 대화 이력 관리	이력 전달 또는 이전 응답 연결 지원

이 표만 보면 “그냥 이름만 바꾼 것 아닌가요?”라고 생각할 수도 있습니다. 하지만 실제로는 도구 호출 방식, 결과 종류, 대화 상태 관리와 스트리밍 데이터 형식에 차이가 있습니다. 기존 코드에서 API 주소만 바꾸면 모든 기능이 그대로 동작하는 것은 아닙니다.

3. Responses API의 가장 간단한 예시

Python을 처음 쓰는 사람이 AI에게 한 문장을 요청한다고 가정해 보겠습니다. 아래는 OpenAI Python SDK에서 쓰는 코드의 형태입니다.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="YOUR_AVAILABLE_MODEL_ID",
    input="인공지능을 한 문장으로 설명해 줘."
)

print(response.output_text)

여기서 YOUR_AVAILABLE_MODEL_ID는 예시용 자리표시자입니다. 그대로 실행할 수 있는 실제 모델 이름이 아닙니다. 계정에서 지원되는 정확한 모델 ID로 바꿔야 합니다. 실행 전에는 SDK가 설치되어 있어야 하고, 유효한 API 키와 필요한 접근 권한·결제/사용량 조건이 준비돼 있어야 합니다. 이 코드를 한 줄씩 살펴보겠습니다. client = OpenAI() OpenAI API 요청을 보내는 클라이언트를 만듭니다. 보통 서버 환경의 OPENAI_API_KEY 같은 환경변수에 저장된 인증 정보를 사용합니다. client.responses.create(...) Responses API를 이용해 모델에 새로운 응답을 생성해 달라고 요청합니다. model=... 어떤 모델로 처리할지 지정합니다. 모델 이름은 제품·계정에서 사용할 수 있는 값으로 선택해야 합니다. input=... 모델이 처리할 질문이나 자료를 전달합니다. response.output_text Python SDK가 제공하는 편의 속성으로, 응답의 텍스트 결과를 추출할 때 사용합니다. 단, 이것은 학습용 예제이며 실제 API 호출을 시험한 결과가 아닙니다. 모델·쿼터·인증 설정이 올바르지 않으면 요청은 실패할 수 있고, 과금이 발생할 수도 있습니다.

4. 그럼 Chat Completions 코드는 어떻게 생겼나요?

같은 목적을 Chat Completions 방식으로 작성하면 이런 모양입니다.

from openai import OpenAI

client = OpenAI()

completion = client.chat.completions.create(
    model="YOUR_AVAILABLE_MODEL_ID",
    messages=[
        {
            "role": "user",
            "content": "인공지능을 한 문장으로 설명해 줘."
        }
    ]
)

print(completion.choices[0].message.content)

앞의 예제와 목적은 같습니다. 모두 질문 하나를 보내는 코드죠. 그런데 입력 필드와 출력 읽는 방법이 다르다는 점이 보일 것입니다. 기존 코드는 messages 배열에 사용자 역할과 내용을 입력하고, 응답의 첫 번째 선택지를 choices[0]에서 읽습니다. Responses API는 질문 하나라면 input에 문자열을 직접 넣을 수 있습니다. 하지만 여러 가지 도구 결과나 이미지·파일처럼 복잡한 내용을 다룰 때는 input에 여러 종류의 아이템을 포함할 수도 있습니다. 그래서 Responses API를 단순히 messages 이름만 input으로 바꾼 버전이라고 이해하면 부족합니다.

5. 왜 Responses API에는 여러 종류의 출력이 있나요?

우리가 AI에게 ‘오늘 해야 할 일을 정리해 줘’라고 질문하면 결과가 단순한 글 한 문단일 수 있습니다. 반면 조금 복잡한 요청이라면 AI가 특정 도구를 호출하고, 그 결과를 받은 뒤 최종 답변을 만들 수 있습니다. 이때 응답 결과에는 다음과 같은 정보가 포함될 수 있습니다.

• 메시지 아이템: 사용자가 보게 될 답변 내용
• 함수 호출 아이템: 개발자가 정의한 기능을 실행하라는 요청
• 추론 관련 아이템: 지원되는 모델과 설정에 따라 나타나는 중간 처리 관련 정보
• 기타 도구 호출 아이템: 지원되는 내장 도구의 작업 상태나 결과 Responses API는 이러한 결과를 output 배열의 타입별 아이템으로 표현할 수 있습니다. 따라서 output[0]에 최종 답변 문장이 항상 들어 있다고 가정하면 안 됩니다. 텍스트만 필요한 간단한 경우에는 output_text가 편리하지만, 도구 호출 결과나 구조화된 정보를 처리하는 프로그램에서는 각 아이템의 종류를 확인해야 합니다.

6. ‘이전 대화 이어가기’는 어떤 기능인가요?

ChatGPT 웹 채팅을 쓰면 우리가 앞서 나눈 말을 이어서 질문할 수 있죠. API에서는 이러한 대화 상태(Conversation State)를 어떻게 관리할지 정해야 합니다. Chat Completions를 사용할 때는 보통 개발자가 이전 메시지들을 정리해 다음 요청의 messages에 다시 전달합니다. Responses API는 그런 수동 방식 외에도 이전 응답의 ID를 연결하는 방법을 제공합니다. 예를 들어 다음과 같은 대화가 있다고 해 보겠습니다.

1. 첫 번째 질문: “나는 부산으로 여행을 가려고 해.”
2. 첫 번째 응답: “부산 여행 일정에 도움을 드릴게요.”
3. 두 번째 질문: “그러면 1박 2일 일정으로 추천해 줘.” 두 번째 질문만 단독으로 보내면 AI는 ‘어디로 가는 일정인지’를 모를 수 있습니다. Responses API에서는 지원되는 설정에서 previous_response_id를 이용해 앞선 응답과 이어진 요청을 만들 수 있습니다.

first = client.responses.create(
    model="YOUR_AVAILABLE_MODEL_ID",
    input="부산 여행을 계획 중이야."
)

second = client.responses.create(
    model="YOUR_AVAILABLE_MODEL_ID",
    previous_response_id=first.id,
    input="1박 2일 일정을 추천해 줘."
)

print(second.output_text)

위 코드는 지원되는 저장 및 대화 상태 설정을 갖춘 공식 OpenAI Responses API의 개념 예시입니다. 중요한 조건은 이전 응답 ID를 이어 쓰려면 그 상태를 참조할 수 있어야 한다는 것입니다. 저장 설정에 따라 store: false를 사용했거나 다른 호환 서버를 쓰는 경우에는 같은 방법이 그대로 작동한다고 가정해서는 안 됩니다. 또 이전 대화를 연결했다고 해서 이전 내용에 대한 비용이나 토큰 처리가 자동으로 무료가 되는 것은 아닙니다.

7. Responses API로 도구도 사용할 수 있나요?

OpenAI의 공식 Responses API는 다양한 도구와 결합해 사용할 수 있도록 설계되어 있습니다. 예를 들어 설정과 모델의 지원 범위에 따라 웹 검색, 파일 검색, 코드 실행, 외부 연결 기능 등을 활용하는 형태가 가능합니다. 다만 여기서 두 가지를 구분해야 합니다. 첫 번째는 OpenAI 공식 API에서 특정 도구를 지원하는지 여부입니다. 도구 종류마다 요구되는 설정, 접근 권한과 비용·제한이 달라질 수 있습니다. 두 번째는 다른 회사나 오픈소스가 제공하는 ‘OpenAI 호환 Responses API’에서도 똑같이 작동하는가 하는 문제입니다. 주소와 요청 JSON이 비슷해도 실제 서버에서 사용할 수 있는 도구의 종류·내용·반환 방식이 다를 수 있습니다. 특히 어떤 호환 서버는 기능 일부를 지원하지 않고 단순 텍스트 요청만 변환할 수 있습니다. 그러므로 ‘Responses API 지원’이라는 문구 하나만 보고 웹 검색·이미지 처리·함수 호출이 모두 가능하다고 믿으면 안 됩니다.

8. FreeLLMAPI에서도 Responses API를 사용할 수 있나요?

FreeLLMAPI는 여러 AI 업체의 API를 하나의 로컬 게이트웨이로 연결하는 오픈소스 프로젝트입니다. 공식 프로젝트 문서에는 POST /v1/responses 경로가 구현돼 있고, Codex CLI를 연결하는 데 사용하는 Responses 형식의 호환 계층이라고 설명돼 있습니다. 예를 들어 프로젝트를 내 컴퓨터에서 기본 설정으로 실행한다면 다음과 같은 경로를 사용할 수 있습니다.

기본 주소: http://localhost:3001/v1
Responses 요청: http://localhost:3001/v1/responses

여기서 localhost는 실행 중인 자기 컴퓨터 또는 해당 실행 환경을 가리킵니다. FreeLLMAPI를 설치하거나 실행하지 않았으면 주소를 입력해도 서버가 응답하지 않습니다. 또 응답을 받으려면 FreeLLMAPI의 통합 인증 키, 연결한 제공업체 계정 및 정상 사용 가능한 모델이 필요합니다. 가장 중요한 주의점: FreeLLMAPI가 제공하는 /v1/responses는 OpenAI 공식 Responses API와 동일한 모든 기능을 무조건 수행하는 서비스가 아닙니다. 공식 소스 코드에서는 Responses 요청을 내부 채팅 메시지 형식으로 변환하는 방식을 사용합니다. 일부 아이템이나 도구 종류는 변환 과정에서 완전히 같은 기능으로 전달되지 않을 수 있습니다. 프로젝트 문서에도 /v1/responses에서 이미지 입력은 아직 지원되지 않는다는 주의가 있습니다. 그런 요청을 보내야 한다면 기능 지원 안내와 다른 API 경로를 확인해야 합니다. 따라서 단순히 텍스트 요청이 된다고 해서 이미지·파일·내장 검색·모든 함수 기능까지 100% 호환한다고 판단해서는 안 됩니다.

9. Codex CLI가 왜 Responses API를 필요로 하나요?

Codex CLI는 터미널에서 코드 작성·수정·작업을 돕는 AI 코딩 도구입니다. FreeLLMAPI 공식 연결 문서에서는 Codex CLI를 연결할 때 /v1 기본 주소와 Responses 형식이 필요하다고 안내합니다. 반대로 다른 AI 클라이언트는 Chat Completions 형식을 사용할 수 있고, Claude Code는 별도의 Anthropic 메시지 형식을 사용할 수 있습니다. 따라서 여러 코딩 도구의 설정을 복사할 때 API의 주소만 바꾸는 것으로 충분한지, 클라이언트가 실제 어떤 요청 형식을 보내는지 확인해야 합니다. FreeLLMAPI 공식 CLI 설정 도우미에는 setup-codex 같은 명령이 소개됩니다. 하지만 설정 파일을 실제로 변경하기 전에, 지원되는 --dry-run으로 예정 변경 내용을 검토하는 방법을 고려할 수 있습니다. 이 글은 명령 실행에 따른 실제 설치·설정 변경을 수행한 결과가 아닙니다. Codex CLI 연결을 지원한다는 설명을 Codex 데스크톱 앱이나 일반 ChatGPT 대화창의 모든 연결 방식이 같다는 뜻으로 해석해서도 안 됩니다.

10. 어떤 오류가 자주 발생할까요?

Responses API 입문자는 보통 다음 네 부류의 오류를 만나게 됩니다.

① 모델이나 인증 문제

API 키가 없거나 잘못됐거나, 선택한 모델에 대한 사용 권한이 없으면 요청이 실패할 수 있습니다. 또 키가 유효해도 프로젝트·계정·사용량 한도 조건이 맞아야 합니다.

② 요청 형식 문제

/v1/responses 경로에 Chat Completions의 입력 구조만 그대로 전달하면 예상한 형식으로 처리되지 않을 수 있습니다. 특히 도구·출력 포맷·스트리밍 설정은 단순 치환만으로 옮길 수 없는 경우가 있습니다.

③ 응답 읽기 문제

Responses API의 결과를 completion.choices[0].message.content로 읽으려고 하면 필드가 일치하지 않아 오류가 납니다. Responses의 output_text 또는 output을 사용해야 합니다.

④ 제3자 서버의 호환성 문제

로컬 게이트웨이에서 경로는 존재하지만 특정 도구·이미지·함수 결과 아이템이 미지원일 수 있습니다. 이때는 OpenAI 공식 API 자체가 고장 났다고 단정하지 말고 실제로 요청을 받은 서버가 어떤 제품이고 어떤 기능을 구현했는지 확인하는 것이 좋습니다.

11. Chat Completions에서 Responses로 옮길 때 체크할 내용

이미 프로그램을 운영 중이라면 한 번에 전체 코드를 수정하는 대신 주요 항목을 점검하세요.

• 요청 주소: /v1/chat/completions에서 /v1/responses로 변경할 준비가 되었는가?
• 입력 구조: messages와 input 중 실제 엔드포인트에 맞는 형식을 사용하는가?
• 출력 처리: choices 대신 타입별 output과 output_text를 처리하는가?
• 상태 관리: 이전 대화를 어떻게 이어갈 것인가? ID 연결·직접 전송·Conversations 방식 중 조건에 맞는 방법을 정했는가?
• 도구 호출: 함수 정의와 결과 아이템, 내장 도구 지원을 확인했는가?
• JSON 출력: 구조화된 응답의 text.format 등 해당 API 규칙으로 옮겼는가?
• 스트리밍: 실시간 결과 이벤트 처리 로직이 Responses 형식에 맞는가?
• 데이터·비용: 요청 저장 설정, 개인정보 처리, 토큰 사용·요금·제공업체 제한을 확인했는가? 기존 API가 계속 지원된다는 사실과, 새로운 개발에 더 적절한 API가 있다는 사실은 동시에 성립합니다. 따라서 지금 바로 모든 앱을 고치는 것보다 한 가지 기능을 안전하게 시험하고 차이를 확인하면서 바꾸는 방식이 좋습니다.

12. 자주 묻는 질문(FAQ)

Q1. Responses API는 ChatGPT 안에 있는 버튼인가요?

아닙니다. Responses API는 개발자가 프로그램에서 모델을 호출할 때 사용하는 API 인터페이스입니다. 일반 ChatGPT 웹 채팅창의 설정 버튼과는 다릅니다.

Q2. 새 AI 프로그램을 만들 때 꼭 Responses API를 써야 하나요?

무조건 의무는 아니지만 OpenAI 공식 문서에서는 새 프로젝트에 Responses API를 권장합니다. Chat Completions도 계속 지원됩니다.

Q3. Chat Completions와 가장 쉽게 구별하는 방법은 무엇인가요?

Chat Completions는 보통 messages를 보내고 choices를 읽습니다. Responses는 input을 보내고 output 또는 SDK의 output_text를 사용합니다.

Q4. Responses API는 무조건 더 저렴한가요?

그렇다고 보장할 수 없습니다. 모델·입출력량·도구 사용·저장·요금 정책에 따라 비용이 달라지며 실제 조건을 확인해야 합니다.

Q5. previous_response_id를 쓰면 대화를 자동으로 모두 기억하나요?

지원되는 상태 관리 조건에서 이전 응답과 연결할 수 있습니다. 응답이 보존되지 않는 설정이나 제3자 호환 서버에서는 같은 방식이 적용되지 않을 수 있습니다.

Q6. output_text만 읽으면 모든 결과를 알 수 있나요?

단순한 텍스트 답변에는 편리하지만 도구 호출·중간 결과·기타 타입별 아이템을 모두 확인하려면 output 구조를 처리해야 합니다.

Q7. FreeLLMAPI에서도 공식 OpenAI 도구가 전부 작동하나요?

아닙니다. FreeLLMAPI는 호환 계층을 제공하며 실제 구현과 연결된 업스트림 업체에 따라 지원 기능이 달라질 수 있습니다. 예를 들어 Responses 경로의 이미지 입력 제한이 공식 문서에 명시돼 있습니다.

Q8. Responses API가 지원되면 Codex CLI가 항상 정상 작동하나요?

아닙니다. 요청 형식 외에도 모델 기능, 인증, 도구 호출, 스트리밍, 세션 처리, 실제 서버 버전 등의 호환성이 맞아야 합니다.

Q9. API 키를 코드에 직접 써도 되나요?

비밀키를 공개 저장소·브라우저 클라이언트 코드·블로그 예제에 직접 넣지 않는 것이 안전합니다. 서버의 비밀 관리 수단과 권한 설정을 이용해야 합니다.

Q10. 글에 있는 Python 코드를 그대로 복사해 실행하면 되나요?

모델 자리표시자를 실제 이용 가능한 모델 ID로 바꾸고, 공식 SDK 설치와 유효한 키·요금/한도 설정을 먼저 확인해야 합니다. 이 글은 실행 성공·비용을 실측한 가이드가 아니라 기초 학습용 예제입니다.

13. 마무리: Responses API는 AI의 답을 주고받는 새로운 방식입니다

Responses API를 어렵게 볼 필요는 없습니다. 프로그램이 AI 모델에 질문을 보내고, 텍스트뿐 아니라 다양한 출력 아이템과 도구 사용 결과까지 처리할 수 있도록 만든 인터페이스라고 이해하면 됩니다. 가장 먼저 기억할 차이는 Chat Completions의 messages/choices와 Responses의 input/output입니다. 그리고 이전 대화를 이어 가거나 제3자 서버에 연결하는 기능은 별도의 상태·호환 조건에 따라 다르게 작동할 수 있습니다. 앞으로 AI 개발 문서에서 /v1/responses라는 경로를 만나면, 어떤 서버에 보내는 요청인지와 어떤 형식의 결과가 돌아오는지부터 확인해 보세요.

공식 자료

제품의 동작과 제한은 바뀔 수 있으므로 게시 시점에도 공식 문서에서 다시 확인하세요.

• OpenAI Responses API 레퍼런스
• OpenAI Responses API 전환 안내

함께 읽으면 좋은 글

• API란 무엇일까? 앱과 AI가 연결되는 원리 쉽게 설명 — 용어의 기본 정의와 범위를 이어서 확인할 수 있습니다.
• 코드란 무엇일까? HTML·CSS·JavaScript와 AI 코딩 쉽게 이해하기 — 용어의 기본 정의와 범위를 이어서 확인할 수 있습니다.