본문으로 건너뛰기

Responses

구조화된 output과 작업 상태를 OpenAI Responses 형식으로 받으세요.

OpenAI Responses 형식의 요청 필드, 구조화된 output과 SSE 이벤트 계약을 설명합니다.

POSThttps://gw.letsur.ai/v1/responses
AUTHAuthorization: Bearer <API_KEY>

요청 필드

Responses와 Chat Completions는 요청과 응답 형식이 다릅니다. 사용할 모델이 Responses를 지원하는지 에셋에서 확인한 뒤 선택합니다.

필드타입요구 여부기본값설명
modelstring필수—모델 코드 (에셋)
inputstring | array필수—단일 문자열 또는 message 배열
instructionsstring선택—시스템 프롬프트 (Chat Completions의 system role)
temperaturenumber선택10 ~ 2
top_pnumber선택1nucleus sampling
max_output_tokensinteger선택모델별Chat Completions의 max_tokens와 같은 의미입니다
streamboolean선택false이벤트 단위 스트리밍 (스트리밍)
response_formatobject선택—JSON mode 등
toolsarray선택—tool calling
tool_choicestring | object선택autotool 선택 정책

input 형식

Chat Completions의 messages와 호환되는 패턴이지만, system role 대신 별도 instructions 필드를 쓰는 것을 권장합니다.

형식예시
단일 문자열"안녕"
message 배열[{"role": "user", "content": "안녕"}]

응답 (200)

{
  "id": "resp_...",
  "object": "response",
  "created_at": 1730000000,
  "model": "<MODEL_CODE>",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {"type": "output_text", "text": "..."}
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 48,
    "total_tokens": 60
  },
  "estimated_cost": {
    "amount": "0.00032400",
    "currency": "unit",
    "disclaimer": "Estimated based on published pricing. Actual charges may differ."
  }
}

주요 필드

필드의미
statuscompleted / incomplete / failed
output구조화된 응답 블록 배열 (메시지 / tool 호출 / reasoning 등)
output[].typemessage / tool_call / reasoning (모델과 옵션에 따라 달라집니다)
usageinput_tokens / output_tokens (Chat Completions의 prompt_tokens / completion_tokens와 같은 의미입니다)
estimated_cost비스트리밍 응답 최상위의 호출별 비용 객체입니다. 이름에는 estimated가 남아 있지만 과금 기록에 사용한 같은 비용 값을 반환합니다

incomplete 상태

incomplete는 HTTP 오류가 아니라 HTTP 200으로 반환되는 응답 상태입니다. 작업은 끝났지만 출력이 완전하지 않으며, incomplete_details에서 이유를 확인합니다. 출력 길이 한계에 도달했다면 모델 컨텍스트 범위 안에서 max_output_tokens를 늘리거나 기대하는 출력 범위를 줄인 뒤 다시 요청합니다.

Chat Completions와 다른 점은 두 가지입니다. 요청은 단일 messages 배열 대신 input을 받습니다. 응답은 구조화된 output[] 블록 배열로 돌려주며, 블록은 메시지, tool 호출, reasoning 등 여러 종류로 나뉩니다.

요청과 응답 예시

아래 예제는 Bash 또는 서버 runtime의 LETSUR_API_KEY 환경 변수를 읽습니다. 키 설정과 첫 실행은 AI 게이트웨이 시작하기에서 확인합니다.

(
  test -n "${LETSUR_API_KEY:-}" || { echo "LETSUR_API_KEY가 필요합니다." >&2; exit 1; }
  env -u LETSUR_API_KEY curl https://gw.letsur.ai/v1/responses \
    --header @- \
    -H "Content-Type: application/json" \
    -d '{
      "model": "<MODEL_CODE>",
      "input": "안녕"
    }' <<EOF
Authorization: Bearer ${LETSUR_API_KEY}
EOF
)

스트리밍 이벤트

stream: true로 요청하면 응답이 Server-Sent Events(SSE) 이벤트 단위로 도착합니다.

event: response.created
data: {"id":"resp_...","status":"in_progress"}

event: response.output_text.delta
data: {"delta":"안"}

event: response.output_text.delta
data: {"delta":"녕"}

...

event: response.completed
data: {"id":"resp_...","status":"completed","usage":{"input_tokens":12,"output_tokens":48,"total_tokens":60},"estimated_cost":{"amount":"0.00032400","currency":"unit","disclaimer":"Estimated based on published pricing. Actual charges may differ."}}
이벤트의미
response.created작업 시작
response.output_text.delta텍스트 부분 도착
response.output_text.done한 텍스트 블록 완료
response.completed전체 작업 완료, 누적 usage와 계산 가능한 경우 estimated_cost
response.failed실패

누적 usage는 response.completed 이벤트에 들어 있습니다. 계산 가능한 호출 비용은 같은 event의 estimated_cost에서 확인하고, event를 받지 못했다면 분석의 누적 값을 확인합니다.

오류와 복구

이 엔드포인트 문맥에서 자주 확인할 오류를 표시합니다. 인증과 월 사용 한도 같은 공통 에러는 에러 코드와 한도에서 확인합니다.

오류의미와 대응
model_not_found (404)카탈로그에 없는 모델입니다. 대응: 에셋에서 모델 코드와 Responses 지원 여부를 다시 확인합니다.
responses_not_supported (400)선택한 모델이 Responses 엔드포인트를 지원하지 않습니다. 대응: 에셋에서 Responses를 지원하는 모델을 선택합니다.
context_length_exceeded (400)요청이 모델 컨텍스트 한도를 초과했습니다. 대응: 입력을 줄이거나 max_output_tokens를 낮춥니다.
마지막 업데이트