Chat completions
프롬프트가 주어지면 모델은 완성된 결과 텍스트를 반환합니다.
POST /v3/chat/completions
⚠️ 저수준의 Chat completions API를 사용하기 보다 고수준의 Responses API를 사용하는 것을 권장합니다.
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를 통해 사용 가능한 모델들을 확인할 수 있습니다.
frequency_penalty float or null Optional Defaults to 0
-2.0에서 2.0 사이의 숫자값으로 모델이 생성하는 문장에 패널티를 부여합니다. 0일 경우에는 패널티를 부여하지 않습니다. 0 보다 크면 반복 출현하는 문장이 줄어들고, 0 보다 작으면 반복 출현하는 문장이 많아집니다.
max_completion_tokens integer or null Optional
호출 시 모델이 생성하는 토큰 개수의 최대치입니다. Null 일 경우에는 finish_reason 값의 변화가 생길 때까지 생성합니다.
metadata map Optional or null
호출 시 전달할 수 있는 최대 16개의 키-값 쌍 집합입니다. 커스텀 정보를 전달하여 대화이력에 저장하고 쿼리할 때 유용합니다.
output_parser string or null Optional Defaults to null
모델 출력 형식을 변환합니다. responses 로 지정 시 Responses API와 동일한 형식으로 출력을 변환합니다. 지정하지 않을 경우 기본 응답 형식으로 결과를 출력합니다.
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 값을 사용합니다.
repetition_penalty float or null Optional Defaults to 1
0.0에서 2.0 사이의 숫자값으로 모델이 생성하는 토큰에 패널티를 부여합니다. 1일 경우에는 패널티를 부여하지 않습니다. 1 보다 크면 반복 출현하는 토큰이 줄어들고, 1 보다 작으면 반복 출현하는 토큰이 많아집니다.
response_format object Optional
모델이 출력해야 하는 형식을 지정하는 객체입니다.
{ "type": "text" } 디폴트 응답 형식입니다. 텍스트 형식으로 출력합니다.
{ "type": "json_schema", "json_schema": {...} }로 설정하면 구조화된 출력이 활성화되어 모델이 제공된 JSON 스키마와 일치하도록 합니다. 자세한 내용은 구조화된 출력을 확인하세요.
{ "type": "json_object" }로 설정하면 이전 JSON 모드가 활성화되어 모델이 생성하는 메시지가 유효한 JSON인지 확인합니다.
seed integer or null Optional
동일한 시드와 매개변수를 사용하는 반복된 요청이 동일한 결과를 반환하도록 최선을 다합니다. 시드값을 지정하지 않거나 -1을 지정하면 매 요청 시 다른 결과가 반환됩니다.
stop string / array / null Optional Defaults to null
모델이 이 배열의 토큰 시퀀스를 생성하면 더 이상 추가적인 토큰을 생성하지 않습니다.
stream boolean or null Optional Defaults to false
True로 설정할 경우 모델 응답 데이터가 서버 전송 이벤트를 통해 생성되는 대로 클라이언트로 스트리밍되며 data: [DONE] 메시지로 스트림이 종료됩니다.
temperature float or null Optional Defaults to 0.3
0에서 2 사이의 숫자값으로 출력의 무작위성을 결정합니다. 온도가 높을수록 출력이 더 무작위로 만들어지고, 낮을수록 더 결정적이게 됩니다. 보다 결정적이고 덜 창의적인 응답이 필요할 경우에는 낮은 온도를, 더 다양하고 창의적인 결과를 원할 경우 높은 온도를 설정합니다. 온도 0은 결정적이고 항상 가장 높은 확률의 응답을 선택합니다. 일반적으로 무작위성 조정을 위해 이 값이나 top_p 값을 변경할 수 있지만, 둘 다 변경하는 것은 권장하지 않습니다.
tools array Optional
모델이 호출할 수 있는 도구들의 목록입니다.
top_p float or null Optional Defaults to 0.75
다음 토큰을 확률이 높은 토큰들 중 누적 확률이 top_p가 될 때까지의 토큰들 중에서 선택합니다. 예를 들어 토큰 A, B, C의 확률이 0.3, 0.2, 0.1이고 top_p가 0.5일 경우 모델은 A 혹은 B(누적 확률은 0.3 + 0.2 = 0.5 = top_p) 중에서 다음 토큰을 선택하고 C는 고려하지 않습니다.
응답의 무작위성을 높이기 위해서는 더 큰 값을 지정하고, 무작위성을 낮추기 위해서는 더 작은 값을 사용합니다.
user string Optional
요청 사용자의 아이디입니다. 사용자 별 로깅이 필요할 경우 채워서 보냅니다.
Tools
function
호출할 수 있는 함수입니다. 모델은 이 함수를 호출할 필요가 있는 지, 호출 시 전달할 매개변수를 결정해 줍니다. 자세한 내용은 함수 호출을 참고하세요.
name string Required
호출할 함수의 이름입니다.
description string Optional
모델이 함수를 언제, 어떻게 호출할지 선택하는 데 사용하는 함수의 기능에 대한 설명입니다.
parameters object Optional
함수가 받는 매개변수는 JSON 스키마 객체로 표현됩니다.
strict boolean or null Optional Defaults to false
함수 호출 생성 시 엄격한 스키마 준수를 활성화할지 여부입니다. true로 설정 하는 것을 권장합니다.
Response
스트리밍 여부에 따라 chat completion 객체(stream=false), 혹은 스트리밍된 chat completion chunk 객체(stream=true) 시퀀스를 반환합니다.
Chat Completion 객체
API의 완료 응답 시 전달되는 객체입니다.
choices array
입력 프롬프트에 대해 생성된 결과 목록입니다.
Click to expand
finish_reason string모델이 토큰 생성을 종료한 원인으로 stop, length 중 하나입니다. 모델이 자연스러운 중지 지점이나 제공된 중지 시퀀스에 도달하면 stop, 요청에 지정된 최대 토큰 수에 도달하면 length가 반환됩니다.
index integer
배열 내에서의 순서입니다.
message object
모델에 의해 생성된 응답 메시지입니다.
Click to expand
content string모델이 생성한 메시지 내용
reasoning_content string or null
모델이 생성한 추론 메시지 내용
role string
메시지 생성자의 역할
created integer
완성 결과가 생성된 시점의 유닉스 타임스탬프(초)입니다.
id string
완성 결과에 대한 고유 ID입니다.
model string
완성을 위해 사용된 모델입니다.
object string
항상 “chat.completion”인 객체 유형입니다.
usage object
Completion 요청에 대한 사용 통계입니다.
Click to expand
completion_tokens integer생성된 토큰의 개수
prompt_tokens integer
입력 토큰의 개수
reasoning_tokens integer or null
추론 토큰의 개수
total_tokens integer
전체 토큰의 개수 (입력 토큰의 개수 + 생성된 토큰의 개수)
예제
Request
curl https://.../v3/chat/completions \
-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
{
id: "cmpl-ec8823b28c03ac66363a85b1",
"object": "chat.completion",
"created": 1744433372,
"model": "Konan-LLM-ENT-11",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "안녕하세요! 어떻게 도와드릴까요?"
},
"finish_reason": "stop"
},
],
"usage": {
"prompt_tokens": 22,
"completion_tokens": 9,
"total_tokens": 31
}
}
Chat Completion Chunk 객체
모델이 반환한 채팅 완료 응답의 스트리밍된 청크를 나타냅니다.
choices array
입력 프롬프트에 대해 생성된 결과 목록입니다.
Click to expand
delta object모델이 스트리밍 중인 응답 메시지의 변경분
Click to expand
content string모델이 생성중인 메시지 내용
reasoning_content string or null
모델이 생성중인 추론 메시지 내용
role string
메시지 생성자의 역할
finish_reason string
stop, length, error, null 중 하나입니다. 스트리밍 중에는 null이 반환됩니다. 스트리밍 중 오류가 발생한 경우에는 error가 반환되며, 오류 코드 및 메시지는 delta/content를 통해 반환됩니다.
index integer
배열 내에서의 순서입니다.
created integer
완성 결과가 생성된 시점의 유닉스 타임스탬프(초)입니다. 각 청크는 동일한 타임스탬프를 공유합니다.
id string
완성 결과에 대한 고유 ID입니다. 각 청크는 동일한 ID를 공유합니다.
model string
완성을 위해 사용된 모델입니다.
object string
항상 “chat.completion.chunk”인 객체 유형입니다.
usage object
Completion 요청에 대한 사용 통계입니다.
예제
data: {"id": "cmpl-ec8823b28c03ac66363a85b1", "choices": [{"delta": {"content": "안녕", "role": "assistant"}, "finish_reason": null, "index": 0, "logprobs": null}], "created": 1744433372, "model": "Konan-LLM-ENT-11", "object": "chat.completion.chunk", "usage": null}
...
data: {"id": "cmpl-ec8823b28c03ac66363a85b1", "choices": [{"delta": {"content": " 어떻게 도와드릴까요?", "role": "assistant"}, "finish_reason": "stop", "index": 0}], "created": 1744433372, "model": "Konan-LLM-ENT-11", "object": "chat.completion.chunk", "usage": {"completion_tokens": 9, "prompt_tokens": 22, "total_tokens": 31}}
data: [DONE]