Responses
POST /v1/responses 는 OpenAI Responses API와 호환되는 엔드포인트입니다. Chat Completions의 후속 엔드포인트입니다. 응답은 구조화된 output 블록과 작업 상태를 함께 담습니다.
POST https://gw.letsur.ai/v1/responses두 엔드포인트는 거의 같은 일을 합니다. 새 코드라면 어느 쪽을 써도 됩니다. 다만 긴 reasoning이나 구조화 output 같은 OpenAI의 새 기능은 Responses에 먼저 들어옵니다.
인증
| 방식 | 헤더 |
|---|---|
| Gateway 키 | Authorization: Bearer <API_KEY> |
요청 파라미터
| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
model | string | ✓ | — | 모델 코드 (카탈로그) |
input | string | array | ✓ | — | 단일 문자열 또는 message 배열 |
instructions | string | ✗ | — | 시스템 프롬프트 (Chat Completions의 system role) |
temperature | number | ✗ | 1 | 0 ~ 2 |
top_p | number | ✗ | 1 | nucleus sampling |
max_output_tokens | integer | ✗ | 모델별 | Chat Completions의 max_tokens와 같은 의미입니다 |
stream | boolean | ✗ | false | 이벤트 단위 스트리밍 (스트리밍) |
response_format | object | ✗ | — | JSON mode 등 |
tools | array | ✗ | — | tool calling |
tool_choice | string | object | ✗ | auto | tool 선택 정책 |
input 형식
| 형식 | 예시 |
|---|---|
| 단일 문자열 | "안녕" |
| message 배열 | [{"role": "user", "content": "안녕"}] |
Chat Completions의 messages와 호환되는 패턴입니다. 다만 system role 대신 별도 instructions 필드를 쓰는 것을 권장합니다.
응답 (200)
{
"id": "resp_...",
"object": "response",
"created_at": 1730000000,
"model": "gpt-4o-mini",
"status": "completed",
"output": [
{
"type": "message",
"role": "assistant",
"content": [
{"type": "output_text", "text": "..."}
]
}
],
"usage": {
"input_tokens": 12,
"output_tokens": 48,
"total_tokens": 60,
"estimated_cost": 0.000324
}
}주요 필드
| 필드 | 의미 |
|---|---|
status | completed / incomplete / failed |
output | 구조화된 응답 블록 배열 (메시지 / tool 호출 / reasoning 등) |
output[].type | message / tool_call / reasoning (모델과 옵션에 따라 달라집니다) |
usage | input_tokens / output_tokens (Chat Completions의 prompt_tokens / completion_tokens와 같은 의미입니다) |
usage.estimated_cost | Letsur가 추가한 필드입니다 |
Chat Completions와 다른 점은 두 가지입니다. 요청은 단일 messages 배열 대신 input을 받습니다. 응답은 구조화된 output[] 블록 배열로 돌려주며, 블록은 메시지·tool 호출·reasoning 등 여러 종류로 나뉩니다.
예시
cURL
curl https://gw.letsur.ai/v1/responses \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"input": "안녕"
}'스트리밍
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":0.000324}}| 이벤트 | 의미 |
|---|---|
response.created | 작업 시작 |
response.output_text.delta | 텍스트 부분 도착 |
response.output_text.done | 한 텍스트 블록 완료 |
response.completed | 전체 작업 완료 + 누적 usage |
response.failed | 실패 |
누적 usage는 response.completed 이벤트에 들어 있습니다. 비용은 이 이벤트를 받은 뒤 읽습니다.
에러 (이 엔드포인트 고유)
| 코드 | HTTP | 의미 |
|---|---|---|
model_not_found | 404 | 카탈로그에 없는 모델입니다 |
responses_not_supported | 400 | 요청한 모델이 Responses 엔드포인트를 지원하지 않습니다 (Chat Completions로 우회합니다) |
context_length_exceeded | 400 | 입력 + 출력이 모델 컨텍스트를 초과했습니다 |
incomplete (응답의 status) | 200 | 작업은 끝났지만 출력이 완전하지 않습니다 (예: 출력 길이 한계 도달). 자세한 이유는 incomplete_details 필드에서 확인합니다 |
공통 에러(인증·한도)는 에러 코드에 있습니다.
한도 / 제약
- 모든 호출에 4단계 한도 체크를 적용합니다. 자세한 내용은 한도 개요를 참고합니다.
- Responses 엔드포인트는 Chat Completions 호환 모델 중 일부만 지원합니다.
관련 문서
Last updated on