OpenAI Responses

OpenAI Responses 호환 API로 텍스트, 이미지, 도구 호출 및 추론 응답을 생성합니다.

Responses API는 Typed Items로 텍스트, 이미지, 파일, 도구 호출 및 추론 결과를 통합하여 표현합니다. 멀티모달 입력, 내장 도구, 상태를 유지하는 상호작용 또는 의미 기반 스트리밍 이벤트가 필요한 애플리케이션에 적합합니다. 사용할 수 있는 Item 유형, 도구 및 고급 필드는 모델마다 다를 수 있으므로 현재 계정에 표시되는 모델과 실제 호출 결과를 기준으로 하세요.

POST/v1/responses

텍스트, 이미지, 파일 또는 Typed Input Items를 바탕으로 모델 응답을 생성합니다. API는 메시지, 추론 항목, 도구 호출 등 다양한 Output Items를 반환할 수 있으며 SSE를 통한 의미 기반 이벤트 전송을 지원합니다.

이미지, 내장 도구, 추론, 상태 연결 또는 구조화된 출력 지원 여부는 현재 계정에 표시되는 모델과 해당 상위 채널에 따라 다릅니다. 최소 텍스트 요청을 먼저 완료한 후 고급 필드를 하나씩 활성화하는 것이 좋습니다.

인증

bearerAuth

인증Bearer <token>

Authorization Header에 Bearer your-api-key를 사용합니다.

전달 위치: header

요청 본문

Responses는 Typed Items로 입력, 도구 및 출력을 표현합니다. 작업에 맞는 보기를 선택하세요. 필드 적용 여부는 모델과 채널에 따라 다릅니다.

application/json

텍스트 입력

가장 간단한 방법은 input에 문자열을 직접 전달하는 것입니다. 메시지 형식의 Typed Items도 사용할 수 있습니다.

model: 현재 API 키에 표시되며 Responses를 지원하는 모델 ID입니다.
input: 문자열 또는 Typed Input Items 배열입니다.
instructions: 이번 응답에만 적용되는 상위 수준 지시입니다.

application/json

{
  "model": "MODEL_ID",
  "input": "세 문장으로 자신을 소개해 주세요."
}

기본 텍스트 응답입니다. input에는 문자열 또는 Typed Input Items를 전달할 수 있습니다.

background?boolean|null

응답을 백그라운드에서 실행할지 지정합니다. 백그라운드 모드 사용 가능 여부는 모델, 채널 및 계정 권한에 따라 다릅니다.

기본값false

context_management?array<>|null

지정한 토큰 임계값에 도달했을 때 압축하는 등 현재 요청의 컨텍스트 관리 설정입니다.

conversation?string||null

이 응답이 속한 Conversation입니다. Conversation ID 또는 id를 포함한 객체를 전달할 수 있으며 previous_response_id와 함께 사용할 수 없습니다.

model?string

사용할 Responses 텍스트 모델 ID입니다. 현재 API 키에 표시되는 모델을 선택하세요.

길이1 <= length

input?text input|array<||||||||||||||||||||||||||||||>

텍스트 입력입니다. 문자열, 메시지 또는 기타 Typed Items를 전달할 수 있습니다.

include?array<>|null

응답에 추가할 확장 데이터를 지정합니다.

instructions?string|array<||||||||||||||||||||||||||||||>|null

이번 응답의 상위 수준 지시로 사용하는 시스템 또는 개발자 메시지입니다. previous_response_id를 사용할 때 이전 응답의 instructions는 자동으로 상속되지 않습니다.

max_output_tokens?integer|null

응답에서 생성할 수 있는 토큰 상한이며 사용자에게 표시되는 출력과 추론 토큰을 포함합니다.

max_tool_calls?integer|null

이번 응답에서 처리할 수 있는 내장 도구 호출의 총수 상한이며 도구 종류별 상한이 아닙니다.

범위0 <= value

metadata?|null

응답 객체에 추가하는 키-값 정보입니다. 키는 최대 64자, 값은 최대 512자입니다.

필드properties <= 16

parallel_tool_calls?boolean|null

모델의 병렬 도구 호출을 허용할지 지정합니다.

기본값true

moderation?|null

응답의 입력과 출력에 콘텐츠 검토를 수행하는 설정입니다.

previous_response_id?string|null

상태를 유지하는 상호작용을 계속하기 위한 이전 Response의 고유 ID입니다. conversation과 함께 사용할 수 없으며 이전 응답의 instructions는 자동으로 상속되지 않습니다.

prompt?|null

저장된 Prompt 템플릿 및 해당 변수에 대한 참조입니다.

prompt_cache_key?string|null

유사한 요청의 프롬프트 캐시 적중률을 높이며 user의 캐시 용도를 대체합니다.

prompt_cache_options?|null

요청 수준의 프롬프트 캐시 설정입니다. 콘텐츠 블록에서 prompt_cache_breakpoint로 명시적 캐시 경계를 표시할 수 있습니다.

prompt_cache_retention?string|null

사용 중단 예정

더 이상 권장되지 않습니다. prompt_cache_options.ttl을 사용하세요. 이전 캐시 보관 정책과의 호환성을 위해 유지되는 필드입니다.

허용 값

"in_memory"
"24h"
null

reasoning?|null

추론 모델 설정입니다. 해당 기능을 지원하는 모델에만 적용됩니다.

service_tier?string|null

요청에 사용할 서비스 등급입니다. 요청값과 실제 응답값이 다를 수 있습니다. 예를 들어 fast 요청에 priority가 반환될 수 있습니다.

기본값"auto"

허용 값

"auto"
"default"
"flex"
"scale"
"priority"
"fast"
"ultrafast"
null

safety_identifier?string|null

안전 및 오용 모니터링을 위한 안정적인 최종 사용자 식별자입니다. 개인을 식별할 수 있는 정보를 전달하지 않도록 먼저 해시 처리하는 것이 좋습니다.

길이length <= 64

store?boolean|null

생성된 응답을 저장할지 지정합니다. 실제 저장, 조회 및 보관 기간은 플랫폼 기능에 따라 다릅니다.

기본값true

stream?boolean|null

true이면 Server-Sent Events를 통해 Responses 의미 기반 이벤트를 반환합니다.

기본값false

stream_options?|null

스트리밍 응답 설정입니다. stream이 true일 때만 사용합니다.

temperature?number|null

샘플링 온도입니다. 일반적으로 temperature 또는 top_p 중 하나만 조정합니다.

범위0 <= value <= 2

기본값1

text?

tool_choice?||||||||

모델의 도구 선택 여부와 방식을 제어합니다.

tools?array<|||||||||||||>

모델에서 사용할 내장 도구 또는 사용자 정의 함수입니다. 실제 지원 범위는 모델과 채널에 따라 다릅니다.

top_logprobs?integer|null

각 출력 토큰 위치에서 반환할 가능성이 높은 후보 토큰 수이며 범위는 0~20입니다.

범위0 <= value <= 20

top_p?number|null

Nucleus 샘플링 확률 질량입니다. 일반적으로 top_p 또는 temperature 중 하나만 조정합니다.

범위0 <= value <= 1

기본값1

truncation?string|null

사용 중단 예정

컨텍스트가 윈도 크기를 초과할 때의 잘라내기 정책입니다. disabled에서는 한도를 초과한 요청이 실패합니다.

기본값"disabled"

허용 값

"auto"
"disabled"
null

user?string

사용 중단 예정

더 이상 권장되지 않습니다. 안전 식별자에는 safety_identifier를, 캐시 그룹에는 prompt_cache_key를 사용하세요.

Responses의 도구, 상태, 추론 및 멀티모달 기능은 모델과 상위 채널에 따라 다를 수 있습니다. 최소 텍스트 요청을 먼저 완료한 후 고급 필드를 하나씩 활성화하는 것이 좋습니다.

응답 본문

`application/json`

curl -X POST "https://example.com/v1/responses" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "input": "유니콘에 관한 잠자리 이야기를 세 문장으로 들려주세요."
  }'

{
  "id": "resp_example",
  "object": "response",
  "created_at": 1741476542,
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "MODEL_ID",
  "output": [
    {
      "id": "msg_example",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "달빛 아래에서 유니콘 한 마리가 별이 빛나는 하늘로 이어지는 비밀 오솔길을 발견했습니다.",
          "annotations": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "store": true,
  "temperature": 1,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 18,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 22,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 40
  },
  "user": null,
  "metadata": {}
}

OpenAI Responses 공식 문서상위 프로토콜 정의 및 최신 필드 변경 사항을 확인합니다.

인증

요청 본문

응답 본문

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

502application/json

503application/json

504application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`