본문으로 건너뛰기

Responses

텍스트 생성과 도구 호출 결과 처리

input 요청 필드와 output 배열, 응답 상태 및 스트리밍 이벤트를 설명하고, 도구 실행 결과를 후속 요청으로 전달하는 방법을 안내합니다.

페이지 목차
POST
https://gw.letsur.ai/v1/responses
인증Authorization: Bearer <API_KEY>

지원 범위

이 엔드포인트는 Responses 형식으로 텍스트를 생성하고, 모델이 요청한 도구 호출의 실행 결과를 후속 요청으로 받습니다. Responses를 지원하는 모델에서만 쓸 수 있으니, 에셋에서 지원 여부를 확인한 뒤 모델을 선택합니다.

Responses와 Chat Completions는 요청과 응답 형식이 다릅니다. 형식별 차이는 API 형식 선택에 있습니다.

요청 필드

기본값 칸의 -는 기본값이 명시되지 않았다는 뜻입니다.

필드타입요구 여부기본값설명
modelstring필수-모델 코드 (에셋)
inputstring | array필수-단일 문자열 또는 메시지와 도구 결과 등의 입력 항목 배열
instructionsstring선택-시스템 프롬프트 (Chat Completions의 system role)
temperaturenumber선택10 ~ 2
top_pnumber선택1누적 확률을 기준으로 다음 토큰 후보를 선택하는 설정
max_output_tokensinteger선택모델별생성할 출력 토큰 수의 상한. 모델의 출력 한도와 전체 컨텍스트 한도 안에서 설정
streamboolean선택false이벤트 단위 스트리밍 (스트리밍)
textobject선택-출력 형식 설정 (text.format으로 지정). Chat Completions의 response_format과 다른 필드
toolsarray선택-도구 호출 정의
tool_choicestring | 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." } }

주요 필드

필드설명
statuscompleted / incomplete / failed
output구조화된 응답 블록 배열 (메시지 / 도구 호출 / reasoning 등)
output[].typemessage, function_call, reasoning 등. 도구와 모델에 따라 종류가 달라지므로 먼저 확인할 값
usageinput_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에는 다음 순서로 항목을 추가합니다.

  1. 원래 입력과 앞 대화를 유지합니다.
  2. 반환된 output 전체를 추가합니다. 메시지뿐 아니라 reasoning 등 다른 출력 항목도 보존합니다.
  3. 각 함수 실행 결과를 추가합니다.

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.createdresponse.id와 시작 상태를 확인합니다.
response.output_text.deltadelta의 부분 텍스트를 모읍니다.
response.output_text.done텍스트 블록 하나가 끝났습니다. 전체 응답의 종료와 구분합니다.
response.completedresponse.status와 response.output, 제공되는 response.usage를 확인합니다.
response.incompleteresponse.incomplete_details를 확인하고 위 응답 상태 표의 incomplete 행을 따릅니다.
response.failedresponse.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를 낮춥니다.