OpenAI Responses API 사용법

이 가이드는 OpenAI Responses API를 처음부터 끝까지 사용하는 방법을 안내합니다: 가이드를 마치면 `POST /v1/responses`로 요청을 보내고, 반환되는 중첩된 출력을 읽고, 내장 도구를 활성화하고, 호출 간에 대화 상태를 유지하며, Apidog 내에서 전체 계약을 확인할 수 있을 것입니다. Responses API는 OpenAI의 새로운 모델 출력 생성 인터페이스이며, 공식 Responses 가이드는 OpenAI가 왜 새로운 프로젝트에 이 API를 권장하는지 설명합니다. 기존 엔드포인트를 이미 테스트하고 있다면, ChatGPT API 테스트 가이드의 워크플로와 마찬가지로 대부분의 설정을 재사용할 수 있습니다.

버튼

먼저 필요한 것

요청을 보내기 전에 몇 가지 준비 사항을 확인하세요:

현재 범용 모델에 접근할 수 있는 OpenAI API 키. 키는 환경 변수에 보관하고, 명령이나 공유 파일에 붙여넣지 마세요.
귀하의 계정이 실제로 호출할 수 있는 모델 이름. 하드코딩하는 대신, OpenAI 대시보드에서 모델 목록을 확인하고 엔드포인트와 대조하여 확인하세요.
원시 HTTP 요청을 보내고 반환되는 JSON을 검사하는 방법. 첫 호출에는 `curl`이 있는 터미널이 작동하며, 나중에 응답을 어설션하고 모의하는 데는 Apidog를 사용할 것입니다.

호출하기 전에 엔드포인트가 무엇을 하는지 아는 것도 도움이 됩니다. Responses API는 단일 엔드포인트인 POST /v1/responses를 노출합니다. 모델 이름과 `input`을 보내면 일반 텍스트, 함수 호출, 웹 검색이나 파일 검색과 같은 OpenAI 호스팅 도구의 결과를 포함할 수 있는 응답 객체가 반환됩니다. 한 번의 호출로 전체 다단계 턴을 실행할 수 있습니다: 모델은 웹을 검색하기로 결정하고, 결과를 읽고, 답변을 작성하며, 응답은 수행한 각 단계를 기록합니다.

이 API를 일반 텍스트 엔드포인트와 차별화하는 두 가지가 있습니다. 첫째, 내장 도구를 서버 측에서 실행할 수 있으므로 자체 검색이나 샌드박스를 연결할 필요가 없습니다. 둘째, 기본적으로 상태를 가집니다. 모든 응답은 `id`를 가지며, 다음 요청에 해당 `id`를 전달하면 OpenAI가 대화 기록을 유지해 줍니다. OpenAI는 Responses API를 Chat Completions의 진화라고 설명하며, Assistants API 베타에서 얻은 교훈을 반영하여 새로운 프로젝트에 이를 권장합니다. 따라서 세 가지 멘탈 모델 대신 하나의 모델을 사용하게 됩니다.

Chat Completions와 다른 점 알아보기

만약 `POST /v1/chat/completions`를 사용해 보셨다면, 변화는 주로 형태와 상태에 있습니다. Chat Completions는 `messages` 배열을 받아 `choices`를 반환합니다. 전체 대화 기록은 각 호출마다 이전 턴을 다시 보내면서 직접 관리합니다. 도구는 사용자가 자체적으로 구현해야 하는 것입니다.

Responses API는 `input` (문자열 또는 유형화된 항목 목록)을 받아 `output` (유형화된 항목 목록)을 반환합니다. 이는 턴을 저장하고 추가적인 연결 없이 호스팅된 도구를 실행할 수 있습니다.

실질적인 비교는 다음과 같습니다:

측면	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는 사라지지 않습니다. OpenAI는 계속 지원될 것이며, 모든 것을 한 번에 다시 작성하는 대신 한 번에 하나의 사용자 흐름을 마이그레이션할 수 있다고 말합니다. Assistants API는 폐기될 예정으로, OpenAI는 2025년 8월 26일에 이를 폐기하고 2026년 8월 26일을 서비스 종료일로 명시했으므로, 새로운 에이전트 작업은 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
  }'

여기서 중요한 세 가지를 전달합니다: `model`, `input` (프롬프트), 그리고 `instructions` (시스템 수준의 지시). `store`를 `true`로 설정하면 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
  }
}

사람들이 혼동하는 부분이기 때문에 구조에 주목하세요. 원하는 텍스트는 최상위 필드가 아닌 `output[0].content[0].text`에 있습니다. 공식 SDK는 모든 텍스트 항목을 하나의 문자열로 집계하는 `output_text` 편의 접근자를 추가하지만, 이 속성은 SDK 헬퍼일 뿐 원시 HTTP JSON의 일부가 아닙니다. 엔드포인트를 직접 호출할 때는 중첩된 경로를 읽습니다. 최상위 `id`는 상태 유지를 위해 재사용할 것이고, `usage.total_tokens`는 호출 비용을 알려줍니다.

내장 도구 추가하기

가장 큰 특징은 OpenAI가 특정 도구를 대신 실행해 준다는 것입니다. `tools` 배열에 도구를 나열하면 모델이 언제 호출할지 결정합니다. 검증된 내장 유형은 다음과 같습니다:

인용문을 포함한 실시간 인터넷 검색을 위한 `web_search` (오래된 `web_search_preview`는 레거시 통합에서 여전히 작동하지만 최신 제어 기능은 부족합니다).
업로드한 파일 전체에서 검색하기 위한 `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" }]
}

모델이 도구를 사용하면 `output` 배열은 최종 `message`와 함께 `web_search_call` 항목과 같이 해당 단계를 문서화하는 항목들을 얻게 됩니다. 이는 나중에 유용합니다: 텍스트가 반환된 것뿐만 아니라 도구가 실제로 실행되었는지 확인할 수 있습니다.

호출 간 대화 계속하기

상태는 두 가지 매개변수를 통해 작동합니다. `store`는 기본적으로 true이며, 이는 OpenAI가 응답 객체를 저장하고 (기본적으로 30일 동안 유지) `id`를 반환한다는 것을 의미합니다. 다음 호출에서 해당 `id`를 `previous_response_id`로 전달하면 모델은 대화 기록을 다시 보내지 않아도 스레드를 계속합니다:

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

상태 비저장을 선호하거나 데이터 보존 요구 사항이 없다면 `store`를 false로 설정하고 컨텍스트를 직접 관리하세요. 실시간, 저지연 음성 및 오디오 흐름의 경우 OpenAI는 다른 인터페이스를 사용합니다; GPT 실시간 API 가이드에서 해당 사례를 다룹니다. 그리고 이 모든 것 위에 다단계 에이전트를 조율하는 경우, 패턴은 OpenAI Agents SDK와 일치합니다.

Apidog에서 테스트하는 방법

Apidog는 API 테스트, 설계 및 목업 플랫폼입니다. 이는 OpenAI SDK나 코드 라이브러리가 아니므로 파이썬 코드를 작성하지 않습니다. 대신 `/v1/responses`로 원시 HTTP 요청을 구축하고, 이를 전송하며, 반환되는 JSON에 대한 어설션을 작성합니다. 이는 사용자들이 깨진 통합을 발견하기 전에 이를 잡아내는 정확한 계약 확인 방식입니다.

다음은 단계별 설정입니다.

환경 변수에 키 저장하기

Apidog에서 환경을 생성하고 (예: "OpenAI Prod"), `OPENAI_API_KEY`와 같은 변수를 추가하세요. 값은 요청이 아닌 환경에 보관하여 비밀이 공유 컬렉션에 커밋되지 않도록 합니다. 그런 다음 `https://api.openai.com/v1/responses`에 대한 새 `POST` 요청을 구축하고 `Authorization: Bearer {{OPENAI_API_KEY}}` 헤더를 추가하세요. Apidog는 전송 시 변수를 대체합니다.

본문을 JSON으로 설정하고 이전에 작성한 요청을 붙여넣으세요. 전송을 누르세요. 중첩된 `output` 배열과 함께 형식화된 전체 응답 객체를 볼 수 있습니다.

응답 필드에 대한 어설션

성공적인 200 응답이 앱이 예상하는 형태로 응답이 구성되었다는 증거는 아닙니다. 회귀가 확실하게 실패하도록 어설션을 추가하세요. `/v1/responses` 응답에 대한 유용한 검사는 다음과 같습니다:

`status`가 `completed`와 같음.
`output[0].content[0].text`가 존재하고 비어 있지 않음.
`usage.total_tokens`가 0보다 큼.
`tools`를 보낼 때, `output`의 항목에 `type`이 `web_search_call`과 같음.

Apidog의 시각적 어설션 빌더를 사용하면 테스트 스크립트를 작성하지 않고도 해당 JSON 경로를 지정할 수 있으며, API 테스트 케이스 템플릿은 이러한 검사를 구성하는 방법을 보여줍니다. 요청을 컬렉션에 저장하면 CI에서 실행할 수 있는 반복 가능한 테스트가 됩니다.

오프라인 개발을 위한 응답 목업

OpenAI 호출은 비용이 발생하고 네트워크 접근이 필요하며, 이는 응답을 사용하는 UI를 구축하거나 유료 API를 호출해서는 안 되는 파이프라인에서 테스트를 실행할 때 불편합니다. Apidog의 목업 기능은 이 문제를 해결합니다. 대표적인 `/v1/responses` 페이로드를 목업으로 저장하고, 앱이 Apidog 목업 URL을 가리키게 하면 프런트엔드는 토큰 소비 없이 올바른 JSON 형태를 얻습니다. 실제 엔드포인트가 변경될 때, 모든 테스트에서 실패를 추적하는 대신 하나의 목업만 업데이트하면 됩니다. 목업 API 설명서는 일반적인 접근 방식을 설명합니다.

이러한 분리는 중요합니다. OpenAI의 계약을 확인하기 위해 실제 엔드포인트를 테스트하고, 빠르고 오프라인이며 결정론적인 개발을 위해 목업합니다. 둘 다 동일한 Apidog 프로젝트에서 실행됩니다.

자주 묻는 질문

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

강제적이지는 않습니다. OpenAI는 Responses를 Chat Completions의 진화라고 부르며 새로운 프로젝트에 권장하지만, Chat Completions는 폐기 날짜 발표 없이 계속 지원됩니다. 한 번에 하나의 흐름을 마이그레이션할 수 있습니다. Assistants API는 2026년에 서비스 종료 예정으로 폐기될 예정입니다.

`store`와 `previous_response_id`의 차이점은 무엇인가요?

store는 OpenAI가 응답 객체를 저장할지 여부를 제어합니다 (기본값은 true이며 30일 동안 유지됩니다). `previous_response_id`는 새로운 요청을 저장된 요청에 연결하여 모델이 서버 측에서 대화를 계속하도록 하는 방법입니다. 상태 저장 스레드에는 이 둘을 함께 사용하며, 상태 비저장 동작을 원할 때는 `store`를 끕니다.

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

OpenAI의 현재 범용 모델은 Responses API와 작동하도록 설계되었지만, 사용 가능 여부는 계정과 선택한 모델에 따라 다릅니다. 모델 이름을 하드코딩하는 대신, OpenAI 대시보드에서 모델 목록을 확인한 다음 엔드포인트와 대조하여 확인하세요. Apidog를 통해 빠른 요청을 보내고 응답의 `model` 필드를 읽는 것은 키가 실제로 호출할 수 있는 모델을 확인하는 빠른 방법입니다.

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

네, 가능합니다. Apidog의 JSON 본문에 `tools` 배열을 추가하고 요청을 보낸 다음, 일치하는 도구 호출 항목 (예: `web_search_call`)이 `output` 배열에 나타나는지 어설션하세요. HTTP를 통해 OpenAI의 동작을 확인하는 것이므로 SDK는 필요하지 않습니다. 에이전트 도구 호출을 더 광범위하게 테스트하려면 OpenAPI 스펙에서 API 테스트 컬렉션을 생성하는 방법을 참조하세요.

마무리

이제 전체 루프를 이해했습니다: 텍스트, 호스팅된 도구, 서버 측 대화 상태를 처리하는 단일 엔드포인트, `POST /v1/responses`. 요청을 보내고, 중첩된 `output`을 읽고, 검색이나 코드 실행이 필요할 때 `tools` 배열을 추가하며, `previous_response_id`를 연결하여 스레드를 계속 유지하세요. 형태가 Chat Completions와 다르기 때문에, 이전 API에 대한 기억을 믿는 대신 직접 계약을 확인하는 것이 가장 안전한 방법입니다.

바로 여기에 Apidog가 들어맞습니다. 하나의 프로젝트에서 요청을 구축하고, 키를 환경 변수로 저장하고, 중첩된 `output` 필드에 대해 어설션하고, 오프라인 작업을 위해 응답을 목업할 수 있습니다. Apidog를 다운로드하고 `/v1/responses`에 테스트를 지정하여 통합이 정확히 무엇을 받는지 확인하세요. Apidog에서 단 한 줄의 테스트 코드도 작성하지 않고 전체 설정을 완료할 수 있습니다.

버튼