Skip to content

Responses

모델 응답을 받는 고차원 인터페이스입니다. RAG, 웹 검색, MCP, 심층 조사등 내장 도구를 활용하여 모델의 능력을 확장할 수 있습니다. 또한 함수 호출을 이용하여 외부 시스템과 데이터에 접근할 수 있습니다.

POST /v3/api/responses

Request Body

messages array Required
현재까지의 대화를 구성하는 메시지 목록입니다.

Click to expand
System message 사용자 메시지와 관련없이 모델이 따라야 하는 지침입니다.

role string Required
메시지 작성자의 역할, 이 경우에는 “system”입니다.
content string
시스템 메시지 내용입니다.
User message 최종 사용자가 보낸 메시지로, 프롬프트나 추가 컨텍스트 정보를 포함합니다.

role string Required
메시지 작성자의 역할, 이 경우에는 “user”입니다.
content string
사용자 메시지 내용입니다.
Assistant message 사용자 메시지에 대한 응답으로 모델이 보낸 메시지입니다.

role string Required
메시지 작성자의 역할, 이 경우에는 “assistant”입니다.
content string
Assistant가 생성한 메시지 내용입니다.

model string Required
요청에 따라 답변을 생성할 LLM의 ID입니다. 모델 목록 API를 통해 사용 가능한 모델들을 확인할 수 있습니다.

metadata map Optional or null
호출 시 전달할 수 있는 최대 16개의 키-값 쌍 집합입니다. 커스텀 정보를 전달하여 대화이력에 저장하고 쿼리할 때 유용합니다.

reasoning object or null Optional Defaults to null
⚠️추론 모드를 지원하는 모델에서만 동작합니다.
추론 시 사용할 노력의 정도를 제한합니다. 추론 노력을 줄이면 응답 속도가 빨라지고 응답에서 추론에 사용되는 토큰이 줄어듭니다. 지정하지 않을 경우 추론 모드로 동작하지 않습니다.

Click to expand budget_tokens integer
추론 시 모델이 생성하는 토큰의 최대치, Null 일 때는 최대치로 생성하며, effort 값이 Null 일 때만 사용할 수 있습니다.
effort string
추론 시 모델이 어느 정도의 노력을 할 지를 의미, "low", "medium", "high 값을 사용할 수 있으며, Null 일 때는 budget_tokens 값을 사용합니다.

stream boolean or null Optional Defaults to false
True로 설정할 경우 모델 응답 데이터가 서버 전송 이벤트를 통해 생성되는 대로 클라이언트로 스트리밍되며 done 이벤트로 스트림이 종료됩니다.
자세한 내용은 Streaming events 항목을 참조하세요.

tools array Optional
모델이 호출할 수 있는 도구들의 목록입니다.

Click to expand type string Required
도구 타입, "function", "mcp", "rag", "trace", "web_search"가 지원됩니다.
function object
Function 속성
mcp object
MCP 속성
rag object
RAG 속성
trace boolean Defaults to false
True로 설정 시 상세한 로그를 남깁니다.
web_search
응답을 생성할 때 참조할 콘텐츠들을 웹에서 검색합니다.

user string Optional
요청 사용자의 아이디입니다. 사용자 별 로깅이 필요할 경우 채워서 보냅니다.

Tools

function

호출할 수 있는 함수입니다. 모델은 이 함수를 호출할 필요가 있는 지, 호출 시 전달할 매개변수를 결정해 줍니다. 자세한 내용은 함수 호출을 참고하세요.

name string Required
호출할 함수의 이름입니다.

description string Optional
모델이 함수를 언제, 어떻게 호출할지 선택하는 데 사용하는 함수의 기능에 대한 설명입니다.

parameters object Optional
함수가 받는 매개변수는 JSON 스키마 객체로 표현됩니다.

strict boolean or null Optional Defaults to false
함수 호출 생성 시 엄격한 스키마 준수를 활성화할지 여부입니다. true로 설정 하는 것을 권장합니다.

mcp

원격 MCP(Model Context Protocol) 서버를 통해 사용할 수 있는 도구들입니다. 자세한 내용은 MCP 가이드을 참고하세요.

server_label string Required
호출할 도구들을 제공하는 MCP 서버의 레이블입니다.

server_url string Required
MCP 서버의 URL입니다.

allowed_tools array Optional
사용할 수 있는 도구명들의 배열입니다.

headers object or null Optional
MCP 서버로 전송할 HTTP 헤더들입니다. 주로 인증 목적으로 사용됩니다.

require_approval string Optional Defaults to never
도구 실행 시 사용자 승인을 받을 지 여부입니다. always, never 중 선택합니다.
⚠️현재 never만 지원합니다.

rag

응답을 생성하기 위해 필요한 콘텐츠들을 벡터 스토어 볼륨에서 검색합니다.

vols string Required
참조 문서를 검색할 볼륨명
여러 볼륨을 검색할 경우 쉼표(,)로 각 볼륨명을 연결합니다.

⚠️ 사용자 개인 볼륨은 {userid} 형식으로 볼륨명을 지정할 수 있습니다.

uuid string Optional
참조할 첨부 문서의 uuid
여러 파일들을 참조할 경우 쉼표(,)로 uuid를 연결합니다.

⚠️ 첨부 파일 참조 시에는 반드시 vols 파라미터에 {userid} 형식으로 사용자 개인 볼륨명을 지정해야 합니다.

embedding string Optional
임베딩 모델

Response

스트리밍 여부에 따라 AIMessage 객체(stream=false), 혹은 스트리밍된 이벤트 시퀀스(stream=true)를 전송합니다.

AIMessage

additional_kwargs object
메시지와 관련된 추가 페이로드용 데이터로 예약된 필드입니다.
추론 메시지가 생성될 경우 혹은 rag 도구 사용 시 이 필드에 저장됩니다.

Click to expand chunks array or null
rag 도구 사용 시 모델이 답변을 생성할 때 참조한 컨텍스트 chunk 목록입니다.
reasoning_content string or null
모델이 생성중인 추론 메시지 내용

content string
모델에 의해 생성된 응답 메시지입니다.

id string
메시지에 대한 고유 ID입니다.

response_metadata object
응답 메시지에 대한 부가적인 정보입니다.

Click to expand finish_reason string
모델이 토큰 생성을 종료한 원인으로 stop, length 중 하나입니다. 모델이 자연스러운 중지 지점이나 제공된 중지 시퀀스에 도달하면 stop, 요청에 지정된 최대 토큰 수에 도달하면 length가 반환됩니다.
model string
메시지를 생성한 모델의 ID입니다.

type string
메시지 타입입니다. 기본값은 ai 입니다.

usage_metadata object
토큰 개수와 같은 생성된 메시지에 대한 사용 통계입니다.

Click to expand input_tokens integer
입력 토큰의 개수
output_tokens integer
생성된 토큰의 개수
total_tokens integer
전체 토큰의 개수 (입력 토큰의 개수 + 생성된 토큰의 개수)
input_tokens_detail object
입력 토큰 부가 정보
output_tokens_detail object
출력 토큰 부가 정보

예제

Request
curl https://.../v3/api/responses \
    -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $KONANLLM_API_KEY" \
    -d '{
        "model": "Konan-LLM-ENT-11",
        "messages": [
            {
                "role": "system",
                "content": "너는 친절한 챗봇이야."
            },
            {
                "role": "user",
                "content": "안녕"
            }
        ]
    }'
Response
{
    "content": "안녕하세요! 오늘은 어떤 도움이 필요하신가요?",
    "additional_kwargs": {},
    "response_metadata": {
        "finish_reason": "stop",
        "model": "Konan-LLM-ENT-11"
    },
    "type": "ai",
    "name": null,
    "id": "run--48c2c343-2be4-4dfd-a31e-1f0eb9c460fe-0",
    "example": false,
    "tool_calls": [],
    "invalid_tool_calls": [],
    "usage_metadata": {
        "input_tokens": 22,
        "output_tokens": 12,
        "total_tokens": 34,
        "input_token_details": {},
        "output_token_details": {}
    },
    "time": 1760505791
}

Chunks

rag 도구 사용 시 모델이 답변을 생성할 때 참조한 컨텍스트 chunk 목록입니다.

cid string
청크의 고유 ID

content string
청크 내용 문자열

page integer or null
청크가 포함된 페이지 번호

title string or null
청크가 포함된 단락의 제목

url string
청크에 대한 URL

uuid string
청크가 포함된 원본 문서의 고유 ID