Responses

생성된 텍스트와 도구 호출 요청을 응답 상태와 함께 확인하세요.

input으로 입력을 보내고 output 배열에서 메시지와 도구 호출 등 결과 종류를 구분합니다.

POSThttps://gw.letsur.ai/v1/responses

AUTHAuthorization: Bearer <API_KEY>

요청 필드

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

필드	타입	요구 여부	기본값	설명
`model`	string	필수	—	모델 코드 (에셋)
`input`	string \| array	필수	—	단일 문자열 또는 message 배열
`instructions`	string	선택	—	시스템 프롬프트 (Chat Completions의 `system` role)
`temperature`	number	선택	`1`	0 ~ 2
`top_p`	number	선택	`1`	누적 확률을 기준으로 다음 토큰 후보를 고르는 설정
`max_output_tokens`	integer	선택	모델별	생성할 출력 토큰 수의 상한입니다. 모델의 출력 한도와 전체 컨텍스트 한도 안에서 설정합니다
`stream`	boolean	선택	`false`	이벤트 단위 스트리밍 (스트리밍)
`response_format`	object	선택	—	JSON 모드 등
`tools`	array	선택	—	도구 호출
`tool_choice`	string \| object	선택	`auto`	도구 선택 정책

`input` 형식

단일 문자열이나 아래 형태의 메시지 배열을 입력합니다. 시스템 지시는 별도 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."
  }
}

주요 필드

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

출력이 미완료인 경우

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

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

요청과 응답 예시

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

cURL


(
  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 이벤트에 들어 있습니다. 계산 가능한 호출 비용은 같은 이벤트의 estimated_cost에서 확인하고, 이벤트를 받지 못했다면 분석의 누적 값을 확인합니다.

텍스트 조각을 받았다는 이유만으로 전체 응답이 완료됐다고 처리하지 않습니다. 최종 응답 상태를 확인하기 전에 연결이 끊기면 받은 출력은 부분 응답으로 남깁니다.

오류와 복구

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

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