Skip to main content
POST
OpenAI 네이티브 형식(Responses)

소개

Responses API는 OpenAI의 차세대 대화 인터페이스로, GPT-5 시리즈 및 고급 기능을 위해 설계되었습니다. 기존 Chat Completions API와 비교하여 더 세밀한 추론 제어, 내장 도구 지원, 멀티모달 입력 기능을 제공합니다.

사용 사례

  • 추론 집약적 작업: GPT-5.5, GPT-5.4, GPT-5.4 Pro 등 심층 추론 모델 활용
  • 웹 검색 요구사항: 내장 Web Search Preview 도구
  • 고급 도구 호출: Function Call 및 Custom Tool Call 지원
  • 다중 턴 대화 이어가기: previous_response_id를 통한 대화 기록 관리

인증

string
필수
Bearer Token, 예: Bearer sk-xxxxxxxxxx

요청 매개변수

string
필수
모델 식별자, 지원 모델:
  • GPT-5 시리즈: gpt-5.5, gpt-5.4, gpt-5.4-pro, gpt-5.4-mini, gpt-5.4-nano
  • GPT-4 시리즈: gpt-4o, gpt-4.1, gpt-4o-mini
array
필수
입력 메시지 목록, 여러 형식 지원:
  • 간소화 형식: [{"role": "user", "content": "text"}] (Chat Completions와 유사)
  • 표준 형식: [{"type": "input_text", "text": "text"}]
  • 멀티모달: input_image, input_file 유형 지원
string
시스템 지시, Chat Completions의 system 메시지와 동일
number
최대 출력 토큰 수, 응답 길이 제어
boolean
기본값:"false"
스트리밍 출력 활성화 여부, SSE 형식 청크 데이터 반환
number
기본값:"1.0"
무작위성 제어, 0-2, 값이 높을수록 응답이 더 무작위적
number
기본값:"0.98"
Nucleus 샘플링 매개변수, 0-1, 생성 다양성 제어
object
추론 모델 동작 제어 설정:
  • effort: 추론 강도, 옵션: "none", "low", "medium", "high"
  • summary: 추론 요약, 옵션: "auto", "none", "detailed"
array
도구 목록, 세 가지 유형 지원:
  • 내장 Web Search: {"type": "web_search_preview", "search_context_size": "medium"}
  • 내장 File Search: {"type": "file_search"}
  • 커스텀 함수: 표준 OpenAI Function Call 형식
string|object
기본값:"auto"
도구 선택 전략:
  • "auto": 모델이 도구 호출 여부를 자동 결정
  • "none": 도구 호출 비활성화
  • {"type": "function", "function": {"name": "function_name"}}: 특정 함수 강제 호출
boolean
기본값:"true"
병렬 다중 도구 호출 허용 여부
number
최대 도구 호출 제한
string
대화 이어가기를 위한 이전 응답 ID
string
기본값:"disabled"
잘림 전략: "auto" 또는 "disabled"
object
추적 및 디버깅용 요청 메타데이터
string
사용자 식별자

기본 예시

응답 형식

비스트리밍 응답

스트리밍 응답(SSE 이벤트)

스트리밍 응답은 Server-Sent Events 형식을 사용하며 다음 이벤트 유형이 있습니다: SSE 출력 예시:

고급 기능

내장 Web Search 도구를 활성화하여 실시간 인터넷 정보를 검색합니다.
Web Search 매개변수:
  • search_context_size: 검색 컨텍스트 크기
    • "low": 낮은 컨텍스트, 빠르지만 결과 적음
    • "medium": 중간 컨텍스트(기본값)
    • "high": 높은 컨텍스트, 검색 결과 많지만 느림
  • user_location (선택): 사용자 위치 정보
    • country: 국가 코드(예: “US”, “CN”)
    • region: 주/도
    • city: 도시
    • timezone: 시간대

2. 추론 제어

추론 모델의 추론 깊이와 출력 형식을 제어합니다.
추론 매개변수:
  • effort: 추론 강도 수준
    • "none": 추론 없음
    • "low": 가벼운 추론
    • "medium": 중간 추론(기본값)
    • "high": 심층 추론
  • summary: 추론 요약
    • "none": 추론 요약 없음
    • "auto": 요약 출력 여부 자동 결정
    • "detailed": 상세 추론 과정 출력

3. 커스텀 Function Calling

표준 OpenAI Function Calling 형식을 지원합니다.
Function Call 응답 형식:

4. 멀티모달 입력

텍스트, 이미지, 파일 등 다양한 입력 유형을 지원합니다.

5. 대화 이어가기

previous_response_id를 사용하여 이전 대화를 이어갑니다.

중요 참고 사항

  • 모델 호환성: 모든 모델이 Responses API의 모든 기능을 지원하는 것은 아닙니다
  • Web Search: GPT-4o, GPT-4.1, GPT-5 및 o 시리즈 모델만 지원합니다
  • 추론: o 시리즈 및 일부 GPT-5 모델만 reasoning 매개변수를 지원합니다
  • 콘텐츠 난독화: 스트리밍 응답 델타에 obfuscation 필드(콘텐츠 보호)가 포함될 수 있으며, 전체 평문은 response.output_text.done 이벤트에서 확인할 수 있습니다
  • 표준 Chat Completions 형식이 필요하면 openai/ 모델 접두사와 함께 /v1/chat/completions 엔드포인트를 사용하세요
  • 시스템이 클라이언트 호환성을 위해 형식을 자동 변환합니다

비교: Responses API vs Chat Completions API

관련 리소스

Chat Completions API

표준 대화 인터페이스 문서

Model List

지원되는 모든 모델 보기

FAQ

Responses API FAQ