DEV Community

Cover image for OpenAI Responses API 사용법
Rihpig
Rihpig

Posted on • Originally published at apidog.com

OpenAI Responses API 사용법

이 가이드는 OpenAI Responses API를 처음부터 끝까지 구현하는 방법을 다룹니다. 완료하면 POST /v1/responses로 요청을 보내고, 중첩된 output을 파싱하고, 내장 도구를 활성화하고, 호출 간 대화 상태를 유지하며, Apidog에서 API 계약을 테스트할 수 있습니다. Responses API는 OpenAI의 새로운 모델 출력 생성 인터페이스이며, 공식 Responses 가이드는 OpenAI가 왜 새 프로젝트에 이 API를 권장하는지 설명합니다. 기존 엔드포인트를 테스트 중이라면 ChatGPT API 테스트 가이드의 워크플로를 대부분 재사용할 수 있습니다.

오늘 Apidog를 사용해 보세요

먼저 필요한 것

요청을 보내기 전에 다음을 준비하세요.

  • 현재 범용 모델에 접근할 수 있는 OpenAI API 키
  • 계정에서 실제로 호출 가능한 모델 이름
  • 원시 HTTP 요청을 보내고 JSON 응답을 확인할 도구
    • 첫 호출: curl
    • 반복 테스트, 어설션, 목업: Apidog

API 키는 환경 변수에 저장하세요. 명령어, 문서, 공유 컬렉션에 직접 붙여넣지 않는 것이 좋습니다.

Responses API의 핵심 엔드포인트는 하나입니다.

POST /v1/responses
Enter fullscreen mode Exit fullscreen mode

API 레퍼런스에 따르면 이 엔드포인트는 모델 이름과 input을 받아 응답 객체를 반환합니다. 응답에는 일반 텍스트뿐 아니라 함수 호출, 웹 검색, 파일 검색 같은 OpenAI 호스팅 도구 실행 결과가 포함될 수 있습니다.

예를 들어 한 번의 호출에서 모델은 다음을 수행할 수 있습니다.

  1. 사용자 입력을 해석합니다.
  2. 필요한 경우 웹 검색을 실행합니다.
  3. 검색 결과를 읽습니다.
  4. 최종 답변을 작성합니다.
  5. 각 단계를 output 배열에 기록합니다.

Responses API가 일반 텍스트 생성 API와 다른 점은 크게 두 가지입니다.

첫째, 내장 도구를 서버 측에서 실행할 수 있습니다. 자체 검색 파이프라인이나 코드 실행 샌드박스를 직접 붙이지 않아도 됩니다.

둘째, 기본적으로 상태를 가질 수 있습니다. 각 응답은 id를 가지며, 다음 요청에서 이 값을 previous_response_id로 전달하면 OpenAI가 이전 대화 컨텍스트를 이어서 처리합니다.

OpenAI는 Responses API를 Chat Completions의 진화로 설명하며, 새로운 프로젝트에는 Responses API 사용을 권장합니다.

Chat Completions와 다른 점

POST /v1/chat/completions를 사용해 봤다면 가장 큰 차이는 요청/응답 형태와 상태 관리 방식입니다.

Chat Completions는 messages 배열을 받고 choices를 반환합니다. 대화 기록은 클라이언트가 직접 관리해야 하며, 매 호출마다 이전 메시지를 다시 보내는 방식이 일반적입니다.

Responses API는 input을 받고 output을 반환합니다. input은 문자열이거나 유형화된 항목 목록일 수 있습니다. 또한 store와 previous_response_id를 통해 서버 측 대화 상태를 이어갈 수 있습니다.

측면 Chat Completions Responses API
엔드포인트 POST /v1/chat/completions POST /v1/responses
요청 본문 messages 배열 input + instructions
출력 형태 choices[].message 유형화된 항목 목록인 output
대화 상태 전체 기록을 다시 전송 store + previous_response_id
내장 도구 직접 구현 web_search, file_search, code_interpreter 등
상태 계속 지원됨 새 프로젝트에 권장됨

Chat Completions는 폐기 예정이 아닙니다. 따라서 기존 통합을 한 번에 모두 바꿀 필요는 없습니다. 사용자 흐름 단위로 점진적으로 마이그레이션할 수 있습니다.

반면 Assistants API는 폐기 예정입니다. OpenAI는 2025년 8월 26일 폐기를 발표했고, 2026년 8월 26일을 서비스 종료일로 명시했습니다. 새 에이전트형 작업은 Responses API에서 시작하는 것이 적절합니다.

첫 요청 보내기

가장 작은 형태의 호출부터 시작합니다.

먼저 API 키를 환경 변수로 설정하세요.

export OPENAI_API_KEY="your_api_key"
Enter fullscreen mode Exit fullscreen mode

그다음 POST /v1/responses를 호출합니다.

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "Write one sentence describing what an API mock server does.",
    "instructions": "You are a concise technical writer. No marketing language.",
    "store": true
  }'
Enter fullscreen mode Exit fullscreen mode

여기서 핵심 필드는 다음과 같습니다.

  • model: 호출할 모델 이름
  • input: 사용자 입력 또는 프롬프트
  • instructions: 시스템 수준의 지시
  • store: 응답을 저장해 이후 대화에 재사용할지 여부

모델 이름은 계정 권한에 따라 달라질 수 있습니다. 하드코딩하기 전에 OpenAI 대시보드에서 사용할 수 있는 모델을 확인하세요.

응답 읽기

간략화된 응답은 다음과 같습니다.

{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "gpt-5.5",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "A mock server returns predefined API responses so clients can be developed and tested before the real backend exists."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 28,
    "output_tokens": 24,
    "total_tokens": 52
  }
}
Enter fullscreen mode Exit fullscreen mode

텍스트는 최상위 필드에 있지 않습니다. 원시 HTTP 응답에서 실제 답변 텍스트는 다음 경로에 있습니다.

output[0].content[0].text
Enter fullscreen mode Exit fullscreen mode

확인해야 할 주요 필드는 다음과 같습니다.

  • id: 다음 요청에서 previous_response_id로 사용할 수 있는 응답 ID
  • status: 요청 처리 상태
  • output: 메시지, 도구 호출 등 유형화된 출력 항목
  • usage.total_tokens: 입력과 출력에 사용된 전체 토큰 수

SDK에서는 여러 텍스트 항목을 합쳐주는 output_text 같은 편의 접근자를 제공할 수 있습니다. 하지만 원시 HTTP JSON에서는 중첩된 output[].content[].text 경로를 직접 읽어야 합니다.

예를 들어 jq로 텍스트만 추출하려면 다음처럼 처리할 수 있습니다.

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "Write one sentence describing what an API mock server does."
  }' | jq -r '.output[0].content[0].text'
Enter fullscreen mode Exit fullscreen mode

내장 도구 추가하기

Responses API의 중요한 기능 중 하나는 OpenAI가 특정 도구를 대신 실행할 수 있다는 점입니다.

도구는 tools 배열에 선언합니다. 모델은 입력을 보고 도구 호출이 필요한지 결정합니다.

사용 가능한 내장 도구 유형은 다음과 같습니다.

  • web_search: 인용문을 포함한 실시간 인터넷 검색
  • file_search: 업로드한 파일 기반 검색
  • code_interpreter: 샌드박스에서 코드 실행 및 분석
  • computer_use: 컴퓨터 인터페이스 제어
  • image_generation: 인라인 이미지 생성

예를 들어 웹 검색을 허용하려면 다음처럼 요청합니다.

{
  "model": "gpt-5.5",
  "input": "What changed in the latest OpenAPI release? Cite sources.",
  "tools": [
    {
      "type": "web_search"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

모델이 도구를 사용하면 output 배열에는 최종 메시지뿐 아니라 도구 실행 단계를 나타내는 항목도 포함됩니다.

예를 들어 웹 검색을 실행했다면 web_search_call 유형의 항목이 나타날 수 있습니다. 따라서 통합 테스트에서는 단순히 텍스트가 반환됐는지만 확인하지 말고, 필요한 도구가 실제로 호출됐는지도 확인하는 것이 좋습니다.

호출 간 대화 계속하기

Responses API에서 상태 관리는 store와 previous_response_id로 처리합니다.

기본적으로 store는 true입니다. 이 경우 OpenAI는 응답 객체를 저장하고, 이후 요청에서 참조할 수 있는 id를 반환합니다.

첫 요청에서 받은 응답 ID가 다음과 같다고 가정합니다.

{
  "id": "resp_abc123"
}
Enter fullscreen mode Exit fullscreen mode

이후 요청에서 previous_response_id로 전달하면 이전 대화를 이어갈 수 있습니다.

{
  "model": "gpt-5.5",
  "input": "Now rewrite that for a non-technical audience.",
  "previous_response_id": "resp_abc123"
}
Enter fullscreen mode Exit fullscreen mode

이 방식의 장점은 클라이언트가 전체 대화 기록을 매번 다시 보내지 않아도 된다는 점입니다.

반대로 상태 비저장 방식이 필요하다면 store를 false로 설정하고 컨텍스트를 직접 관리하세요.

{
  "model": "gpt-5.5",
  "input": "Summarize this text.",
  "store": false
}
Enter fullscreen mode Exit fullscreen mode

실시간 음성 또는 오디오 기반 저지연 흐름은 다른 인터페이스를 사용합니다. 해당 사례는 GPT 실시간 API 가이드에서 다룹니다. 다단계 에이전트를 구성하는 경우에는 OpenAI Agents SDK 패턴과도 연결됩니다.

Apidog에서 테스트하는 방법

Apidog는 API 테스트, 설계, 목업 플랫폼입니다. OpenAI SDK나 코드 라이브러리가 아니므로 Python 코드를 작성하지 않습니다.

대신 Apidog에서 다음 작업을 수행합니다.

  1. /v1/responses에 대한 원시 HTTP 요청을 만듭니다.
  2. 환경 변수로 API 키를 관리합니다.
  3. 요청을 전송합니다.
  4. 반환된 JSON 구조를 확인합니다.
  5. 응답 필드에 어설션을 추가합니다.
  6. 필요하면 응답을 목업으로 저장합니다.

이 방식은 실제 앱이 의존하는 API 계약을 직접 검증하는 데 적합합니다.

1. 환경 변수에 API 키 저장하기

Apidog에서 새 환경을 만듭니다.

예:

OpenAI Prod
Enter fullscreen mode Exit fullscreen mode

그다음 환경 변수로 API 키를 추가합니다.

OPENAI_API_KEY=your_api_key
Enter fullscreen mode Exit fullscreen mode

요청에는 실제 키를 직접 넣지 말고 변수를 사용합니다.

Authorization: Bearer {{OPENAI_API_KEY}}
Enter fullscreen mode Exit fullscreen mode

이렇게 하면 공유 컬렉션이나 문서에 비밀 값이 노출되는 것을 피할 수 있습니다.

2. /v1/responses 요청 만들기

Apidog에서 새 POST 요청을 생성합니다.

POST https://api.openai.com/v1/responses
Enter fullscreen mode Exit fullscreen mode

헤더를 추가합니다.

Authorization: Bearer {{OPENAI_API_KEY}}
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode

본문은 JSON으로 설정합니다.

{
  "model": "gpt-5.5",
  "input": "Write one sentence describing what an API mock server does.",
  "instructions": "You are a concise technical writer. No marketing language.",
  "store": true
}
Enter fullscreen mode Exit fullscreen mode

전송하면 Apidog에서 전체 응답 객체와 중첩된 output 배열을 확인할 수 있습니다.

3. 응답 필드에 어설션 추가하기

HTTP 200만 확인하는 것은 충분하지 않습니다. 앱이 기대하는 JSON 형태가 유지되는지 확인해야 합니다.

/v1/responses 응답에서 유용한 어설션은 다음과 같습니다.

  • status가 completed와 같음
  • output[0].content[0].text가 존재함
  • output[0].content[0].text가 빈 문자열이 아님
  • usage.total_tokens가 0보다 큼
  • tools를 보낸 경우 output 항목 중 type이 web_search_call인 항목이 존재함

Apidog의 시각적 어설션 빌더를 사용하면 테스트 스크립트를 직접 작성하지 않고도 JSON 경로 기반 검사를 추가할 수 있습니다. 더 구체적인 구성 방식은 API 테스트 케이스 템플릿을 참고하세요.

요청을 컬렉션에 저장하면 반복 가능한 테스트로 사용할 수 있고, CI에서 실행할 수도 있습니다.

4. 내장 도구 호출 테스트하기

웹 검색 도구를 테스트하려면 본문에 tools 배열을 추가합니다.

{
  "model": "gpt-5.5",
  "input": "What changed in the latest OpenAPI release? Cite sources.",
  "tools": [
    {
      "type": "web_search"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

응답에서 다음을 확인하세요.

output[*].type
Enter fullscreen mode Exit fullscreen mode

도구가 실행되었다면 web_search_call 같은 항목이 포함됩니다.

테스트 기준은 다음처럼 잡을 수 있습니다.

  • 최종 답변 메시지가 존재한다.
  • 도구 호출 항목이 존재한다.
  • 도구 호출 후 생성된 텍스트가 비어 있지 않다.

이렇게 하면 모델이 단순히 답변을 생성했는지뿐 아니라, 기대한 방식으로 도구를 사용했는지도 검증할 수 있습니다.

5. 오프라인 개발을 위한 응답 목업 만들기

OpenAI 호출은 비용이 발생하고 네트워크 접근이 필요합니다. UI 개발이나 CI 테스트에서 매번 실제 API를 호출하면 느리고 불안정할 수 있습니다.

Apidog의 목업 기능을 사용하면 대표적인 /v1/responses 응답을 저장하고, 프런트엔드나 테스트 환경이 Apidog 목업 URL을 바라보게 할 수 있습니다.

예를 들어 다음과 같은 응답 형태를 목업으로 저장합니다.

{
  "id": "resp_mock123",
  "object": "response",
  "status": "completed",
  "model": "gpt-5.5",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "A mock server returns predefined API responses."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 10,
    "output_tokens": 8,
    "total_tokens": 18
  }
}
Enter fullscreen mode Exit fullscreen mode

이후 앱은 실제 OpenAI API 대신 Apidog 목업 URL에서 동일한 JSON 구조를 받을 수 있습니다.

이 접근의 장점은 다음과 같습니다.

  • 토큰 비용 없이 UI 개발 가능
  • 네트워크 장애와 무관하게 테스트 가능
  • 응답 구조를 고정해 결정론적 테스트 가능
  • 실제 API 계약 변경 시 목업만 업데이트 가능

일반적인 목업 방식은 목업 API 설명서에서 확인할 수 있습니다.

실제 엔드포인트 테스트와 목업은 목적이 다릅니다.

  • 실제 엔드포인트 테스트: OpenAI API 계약 확인
  • 목업: 빠르고 오프라인이며 결정론적인 개발 환경 제공

둘 다 같은 Apidog 프로젝트에서 관리할 수 있습니다.

자주 묻는 질문

Responses API가 Chat Completions를 대체하나요?

강제 대체는 아닙니다. OpenAI는 Responses API를 Chat Completions의 진화로 설명하며 새 프로젝트에 권장하지만, Chat Completions는 폐기 날짜 없이 계속 지원됩니다.

기존 앱은 한 번에 모두 옮기기보다 사용자 흐름 단위로 점진적으로 마이그레이션하는 것이 안전합니다.

Assistants API는 폐기 예정이며, 2026년에 서비스 종료될 예정입니다.

store와 previous_response_id의 차이는 무엇인가요?

store는 OpenAI가 응답 객체를 저장할지 여부를 제어합니다. 기본값은 true이며, 저장된 응답은 이후 대화 상태를 이어가는 데 사용할 수 있습니다.

previous_response_id는 새 요청을 이전 응답에 연결하는 필드입니다.

상태 저장 대화를 만들려면 다음처럼 사용합니다.

{
  "model": "gpt-5.5",
  "input": "Continue from the previous answer.",
  "previous_response_id": "resp_abc123"
}
Enter fullscreen mode Exit fullscreen mode

상태 비저장 동작이 필요하면 다음처럼 설정합니다.

{
  "model": "gpt-5.5",
  "input": "Answer without storing this response.",
  "store": false
}
Enter fullscreen mode Exit fullscreen mode

어떤 모델이 Responses API를 지원하나요?

OpenAI의 현재 범용 모델은 Responses API와 작동하도록 설계되었지만, 사용 가능 여부는 계정과 모델 권한에 따라 달라집니다.

권장 절차는 다음과 같습니다.

  1. OpenAI 대시보드에서 사용 가능한 모델을 확인합니다.
  2. 모델 이름을 요청 본문에 넣습니다.
  3. Apidog 또는 curl로 테스트 요청을 보냅니다.
  4. 응답의 model 필드를 확인합니다.

모델 이름을 코드에 하드코딩하기 전에 실제 키로 호출 가능한지 검증하세요.

코드 작성 없이 내장 도구를 테스트할 수 있나요?

네. Apidog에서 JSON 본문에 tools 배열을 추가하고 요청을 보내면 됩니다.

예:

{
  "model": "gpt-5.5",
  "input": "Search the web and summarize the result.",
  "tools": [
    {
      "type": "web_search"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

그다음 output 배열에 도구 호출 항목이 나타나는지 어설션합니다.

예:

output[*].type contains web_search_call
Enter fullscreen mode Exit fullscreen mode

SDK 없이 HTTP 요청만으로 OpenAI의 도구 호출 동작을 확인할 수 있습니다. 에이전트 도구 호출을 더 넓은 범위에서 테스트하려면 OpenAPI 스펙에서 API 테스트 컬렉션을 생성하는 방법을 참고하세요.

마무리

Responses API의 기본 구현 흐름은 다음과 같습니다.

  1. POST /v1/responses로 요청을 보냅니다.
  2. input과 instructions로 모델 동작을 제어합니다.
  3. 응답의 output[0].content[0].text에서 텍스트를 읽습니다.
  4. 검색이나 코드 실행이 필요하면 tools 배열을 추가합니다.
  5. 대화를 이어가려면 이전 응답의 id를 previous_response_id로 전달합니다.
  6. 상태 비저장이 필요하면 store: false를 사용합니다.

Responses API는 Chat Completions와 응답 형태가 다릅니다. 따라서 이전 API의 구조를 가정하지 말고 실제 JSON 계약을 직접 확인하는 것이 안전합니다.

Apidog를 사용하면 하나의 프로젝트에서 요청을 만들고, API 키를 환경 변수로 관리하고, 중첩된 output 필드에 어설션을 추가하고, 오프라인 개발을 위한 응답 목업까지 구성할 수 있습니다.

Apidog를 다운로드한 뒤 /v1/responses 요청을 테스트 컬렉션으로 저장해 통합이 실제로 어떤 응답을 받는지 검증하세요.

Top comments (0)