Responses
텍스트 생성과 도구 호출 결과 처리
input 요청 필드와 output 배열, 응답 상태 및 스트리밍 이벤트를 설명하고, 도구 실행 결과를 후속 요청으로 전달하는 방법을 안내합니다.
페이지 목차
https://gw.letsur.ai/v1/responsesAuthorization: Bearer <API_KEY>지원 범위
이 엔드포인트는 Responses 형식으로 텍스트를 생성하고, 모델이 요청한 도구 호출의 실행 결과를 후속 요청으로 받습니다. Responses를 지원하는 모델에서만 쓸 수 있으니, 에셋에서 지원 여부를 확인한 뒤 모델을 선택합니다.
Responses와 Chat Completions는 요청과 응답 형식이 다릅니다. 형식별 차이는 API 형식 선택에 있습니다.
요청 필드
기본값 칸의 -는 기본값이 명시되지 않았다는 뜻입니다.
| 필드 | 타입 | 요구 여부 | 기본값 | 설명 |
|---|---|---|---|---|
model | string | 필수 | - | 모델 코드 (에셋) |
input | string | array | 필수 | - | 단일 문자열 또는 메시지와 도구 결과 등의 입력 항목 배열 |
instructions | string | 선택 | - | 시스템 프롬프트 (Chat Completions의 system role) |
temperature | number | 선택 | 1 | 0 ~ 2 |
top_p | number | 선택 | 1 | 누적 확률을 기준으로 다음 토큰 후보를 선택하는 설정 |
max_output_tokens | integer | 선택 | 모델별 | 생성할 출력 토큰 수의 상한. 모델의 출력 한도와 전체 컨텍스트 한도 안에서 설정 |
stream | boolean | 선택 | false | 이벤트 단위 스트리밍 (스트리밍) |
text | object | 선택 | - | 출력 형식 설정 (text.format으로 지정). Chat Completions의 response_format과 다른 필드 |
tools | array | 선택 | - | 도구 호출 정의 |
tool_choice | string | object | 선택 | auto | 도구 선택 정책 |
위 표의 파라미터와 도구 호출은 이 엔드포인트로 요청할 수 있지만, 지원 여부와 세부 제한은 요청의 model이 가리키는 모델마다 다릅니다. 지원 여부는 에셋 화면의 표시값에서 확인합니다. 모델이 지원하지 않는 파라미터를 포함한 요청은 실패할 수 있습니다.
input 형식
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, function_call, reasoning 등. 도구와 모델에 따라 종류가 달라지므로 먼저 확인할 값 |
usage | input_tokens / output_tokens (Chat Completions의 prompt_tokens / completion_tokens와 같은 의미) |
estimated_cost | 비스트리밍 응답 최상위에 있는 호출별 비용 객체. 영문 disclaimer는 응답 문자열 그대로 반환. 값의 의미와 null 처리 기준은 요청별 비용을 따름 |
응답 상태에 따른 다음 행동
incomplete는 HTTP 200으로 반환될 수 있는 응답 상태입니다. HTTP 200만으로 응답 내용을 성공한 최종 결과로 처리하지 않습니다. 최상위 status 값에 따라 다음 행동을 정합니다.
| 값 | 뜻과 다음 행동 |
|---|---|
completed | 응답 생성이 끝났습니다. output[]의 블록 종류를 확인합니다. 도구 요청만 있으면 함수 도구 처리를 따릅니다. |
incomplete | 응답 생성은 끝났지만 출력이 완전하지 않습니다. incomplete_details에서 이유를 확인합니다. 출력이 길이 한도에 도달했다면 모델 컨텍스트 범위 안에서 max_output_tokens를 늘리거나 기대하는 출력 범위를 줄여 다시 요청할 수 있습니다. |
failed | 응답 생성에 실패했습니다. 응답의 error에서 원인을 확인하고 요청을 수정하거나 지원을 요청합니다. |
incomplete 응답의 비용 기록 방법은 요청별 비용에 있습니다. 다시 보내는 요청은 별도 호출이라 추가 비용이 생길 수 있습니다. 다시 보낼지는 오류와 복구의 기준으로 판단합니다.
요청과 응답 예시
아래 예제는 실행 환경의 LETSUR_API_KEY 환경 변수를 읽습니다. 키 설정과 첫 실행 방법은 첫 API 호출에 있습니다.
SDK 예제에서는 자동 재시도를 끕니다. timeout이나 응답 유실 뒤의 재전송 여부는 오류와 복구의 기준에 따라 판단합니다.
cURL
curl https://gw.letsur.ai/v1/responses \
-H "Authorization: Bearer $LETSUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<MODEL_CODE>",
"input": "안녕"
}'Python 예제는 상태를 확인한 뒤 완료된 응답의 텍스트를 출력합니다. cURL로 실행했다면 응답 JSON의 최상위 status를 먼저 보고 응답 상태에 따른 다음 행동을 따르세요. completed라도 도구 요청만 있으면 최종 답변이 아니므로 함수 도구 처리가 필요합니다. 이 기본 예제는 도구를 실행하거나 요청을 자동으로 다시 보내지 않습니다.
함수 도구 정의와 결과 반환
선택한 모델이 함수 도구를 지원하는지 먼저 확인하세요. 함수 도구를 정의할 때는 tools[]의 각 객체에 type: "function", name, parameters 필드를 바로 넣습니다. Chat Completions처럼 function 객체로 감싸지 않습니다. parameters에는 JSON Schema를 씁니다.
후속 요청의 input에는 다음 순서로 항목을 추가합니다.
- 원래 입력과 앞 대화를 유지합니다.
- 반환된
output전체를 추가합니다. 메시지뿐 아니라 reasoning 등 다른 출력 항목도 보존합니다. - 각 함수 실행 결과를 추가합니다.
model, tools와 필요한 instructions도 다시 보냅니다. 서버가 앞 문맥을 복원한다고 가정하지 않습니다.
아래 예제는 두 수를 더하는 함수를 애플리케이션에서 실행합니다. LETSUR_API_KEY와 함수 도구를 지원하는 실제 모델 코드를 준비합니다.
이 예제에서도 SDK의 자동 재시도를 끕니다. timeout이나 응답 유실 뒤의 재전송 여부는 오류와 복구의 기준에 따라 판단합니다.
import json
import os
from openai import OpenAI
client = OpenAI(api_key=os.environ["LETSUR_API_KEY"], base_url="https://gw.letsur.ai/v1", max_retries=0)
model = "<MODEL_CODE>"
instructions = "합계 계산에는 add_numbers를 사용하고 그 결과를 답하세요."
tools = [{
"type": "function",
"name": "add_numbers",
"description": "두 수의 합계를 계산합니다.",
"parameters": {
"type": "object",
"properties": {"a": {"type": "number"}, "b": {"type": "number"}},
"required": ["a", "b"],
"additionalProperties": False,
},
}]
history = [{"role": "user", "content": "2와 3의 합계를 알려 줘"}]
response = client.responses.create(
model=model, input=history, tools=tools, instructions=instructions,
)
if response.status != "completed":
raise RuntimeError(f"응답 상태를 먼저 확인하세요: {response.status}")
history.extend(response.output) # reasoning을 포함한 반환 항목 전체 보존
calls = [item for item in response.output if item.type == "function_call"]
for call in calls:
if call.name != "add_numbers":
raise ValueError(f"등록하지 않은 함수입니다: {call.name}")
args = json.loads(call.arguments)
result = args["a"] + args["b"]
history.append({
"type": "function_call_output",
"call_id": call.call_id,
"output": json.dumps({"sum": result}),
})
if calls:
response = client.responses.create(
model=model, input=history, tools=tools, instructions=instructions,
)
print(response.status)
for item in response.output:
print(item.type)
if response.status == "completed" and item.type == "message":
for content in item.content:
if content.type == "output_text":
print(content.text)함수 결과를 돌려줄 때는 다음을 지킵니다.
- 애플리케이션이
arguments에서 인수를 읽어 요청된 함수를 실행합니다. 모델이 함수 호출을 요청했다는 이유만으로 함수가 실행됐다고 처리하지 않습니다. - 각 결과의
call_id에는 짝이 되는function_call.call_id와 같은 값을 지정합니다. 호출이 여러 개면 호출마다 결과를 추가합니다. - Responses 요청에 Chat Completions의
messages나tool_call_id형식을 섞지 않습니다. - 결과를 보낸 뒤에는 다음 응답의 상태와 출력 종류를 다시 확인합니다. 모델이 또 도구 실행을 요청하면 같은 방식으로 처리합니다.
- 텍스트는
output[]가운데 메시지 블록의content[]에서 읽습니다.
정의와 흐름을 더 보려면 Responses 함수 도구 형식 을 참고하세요.
스트리밍 이벤트
stream: true로 요청하면 응답이 Server-Sent Events(SSE) 이벤트 단위로 도착합니다.
다음은 구조를 보여 주는 축약 예시입니다. 이벤트의 type을 확인하고, 응답 객체는 response 안에서 읽습니다.
event: response.created
data: {"type":"response.created","response":{"id":"resp_...","status":"in_progress"}}
event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"안"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"녕"}
...
event: response.completed
data: {"type":"response.completed","response":{"id":"resp_...","status":"completed","usage":{"input_tokens":12,"output_tokens":48,"total_tokens":60}}}| 이벤트 | 읽을 값과 다음 행동 |
|---|---|
response.created | response.id와 시작 상태를 확인합니다. |
response.output_text.delta | delta의 부분 텍스트를 모읍니다. |
response.output_text.done | 텍스트 블록 하나가 끝났습니다. 전체 응답의 종료와 구분합니다. |
response.completed | response.status와 response.output, 제공되는 response.usage를 확인합니다. |
response.incomplete | response.incomplete_details를 확인하고 위 응답 상태 표의 incomplete 행을 따릅니다. |
response.failed | response.error를 확인해 실패 원인에 따라 대응합니다. |
사용량은 종료 이벤트의 response.usage에 있습니다. 비스트리밍 응답에서는 estimated_cost가 응답 최상위에 있지만, 스트리밍에서도 같은 위치에 있다고 가정하지 않습니다.
스트림을 받는 중에는 다음 상황을 구분해 처리합니다.
| 상황 | 처리 |
|---|---|
| 비용을 확인할 수 없음 | 요청별 비용의 기준에 따라 비용을 0으로 기록하지 않습니다. |
| 텍스트 조각을 받음 | 텍스트 조각을 받았다는 이유만으로 전체 응답이 완료됐다고 처리하지 않습니다. |
| 종료 이벤트를 받기 전에 연결이 끊김 | 받은 출력은 부분 응답으로 남깁니다. |
오류와 복구
timeout이나 응답 유실 뒤 같은 요청을 다시 보내면 별도 호출로 처리됩니다. 다시 보내기 전에 동기 호출의 재시도와 비용 확인에 따라 원래 호출과 새 호출을 구분하세요.
이 엔드포인트에서 주로 확인할 오류와 대응은 다음과 같습니다. 인증과 월 사용 한도 같은 공통 오류는 오류 코드와 한도에서 확인합니다.
| 오류 | 의미와 대응 |
|---|---|
model_not_found (404) | 에셋 목록에 없는 모델입니다. 대응: 에셋에서 모델 코드와 Responses 지원 여부를 다시 확인합니다. |
responses_not_supported (400) | 선택한 모델이 Responses 엔드포인트를 지원하지 않습니다. 대응: 에셋에서 Responses를 지원하는 모델을 선택합니다. |
context_length_exceeded (400) | 요청이 모델 컨텍스트 한도를 초과했습니다. 대응: 입력을 줄이거나 max_output_tokens를 낮춥니다. |