POST
/
api
/
v1
/
chat
/
completions
curl --request POST \
--url https://api.clovastudio.go.kr/api/v1/chat/completions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "LLM42",
"messages": [
{
"role": "system",
"content": "당신은 친절한 AI 어시스턴트입니다."
},
{
"role": "user",
"content": "대한민국의 수도는 어디인가요?"
}
],
"max_tokens": 1024,
"temperature": 0.7
}'
{
"id": "chatcmpl-123abc",
"object": "chat.completion",
"created": 1677652288,
"model": "LLM42",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "대한민국의 수도는 서울특별시입니다.",
"tool_calls": []
},
"logprobs": null,
"finish_reason": "stop",
"stop_reason": null
}
],
"usage": {
"prompt_tokens": 30,
"total_tokens": 45,
"completion_tokens": 15,
"prompt_tokens_details": null
},
"prompt_logprobs": null
}

개요

Chat Completions API는 대화 메시지를 기반으로 AI 모델의 응답을 생성하는 엔드포인트입니다. OpenAI Chat Completions API와 호환되는 규격을 따르며, 기존 OpenAI 기반 애플리케이션을 쉽게 전환하거나 OpenAI SDK를 그대로 사용할 수 있습니다.
  • 엔드포인트: POST https://api.clovastudio.go.kr/api/v1/chat/completions
  • 인증: Authorization: Bearer YOUR_API_KEY 헤더 사용
chat_template_kwargs는 각 모델의 특수 기능을 제어하는 핵심 파라미터입니다. 추론(Reasoning) 모드 활성화, 번역 언어 코드 지정 등 모델별로 다른 동작을 설정할 수 있습니다.

지원 모델

모델명Model ID유형멀티모달추론(Reasoning)특이사항
HCX-GOV-THINKHCX-GOV-THINK추론형기본 활성화force_reasoning / skip_reasoning
HCX-GOVHCX-GOV범용기본 비활성화force_reasoning / skip_reasoning
HCX-GOV-VLMHCX-GOV-VLM멀티모달이미지선택 가능force_reasoning / skip_reasoning
LLM42LLM42범용 다국어이미지140개 언어 지원, 추가 파라미터 불필요
HCX-GOV-THINK-V1-32BHCX-GOV-THINK-V1-32B추론형thinking: true 설정 시XML 포맷 Tool Call 내부 사용
LLM42-TranslateLLM42-Translate번역 전용source_lang_code, target_lang_code 필수
openai/gpt-oss-120bopenai/gpt-oss-120b대규모 범용reasoning_effort 조절low / medium / high
모델별 상세 특징과 사용 사례는 언어 모델 종류 페이지를 참고하세요.

공통 파라미터

model

사용할 모델의 ID입니다. 위 비교표의 Model ID 값을 그대로 입력합니다.
"model": "HCX-GOV-THINK"

messages

대화 메시지 배열입니다. 각 메시지는 rolecontent를 포함합니다.
Role설명
systemAI 어시스턴트의 역할, 행동 방식, 응답 조건을 정의합니다.
user사용자가 모델에게 보내는 질문이나 요청입니다.
assistant모델이 이전에 생성한 응답입니다. 멀티 턴 대화 시 이전 대화 이력을 포함할 때 사용합니다.
"messages": [
  {"role": "system", "content": "당신은 친절한 AI 어시스턴트입니다."},
  {"role": "user", "content": "안녕하세요!"}
]

temperature

생성 토큰의 다양성을 조절합니다. 범위: 0.0 ~ 2.0 (기본값: 1.0)
  • 낮은 값 (0에 가까움): 일관되고 예측 가능한 응답
  • 높은 값 (2에 가까움): 창의적이고 다양한 응답

top_p

누적 확률 기반 샘플링입니다. 범위: 0.0 ~ 1.0 (기본값: 1.0)

max_tokens

최대 생성 토큰 수입니다. 범위: 1 ~ 32768
추론 모드 사용 시 권장 max_tokens:
  • 추론 미사용: 512 이상
  • 짧은 추론: 5,120 이상
  • 중간 추론: 10,240 이상
  • 깊은 추론: 20,480 이상
max_tokens가 부족하면 모델이 추론 과정 중 토큰 제한에 도달하여 최종 답변을 생성하지 못할 수 있습니다.
stream: true로 설정하면 Server-Sent Events (SSE) 형식으로 응답이 실시간 전송됩니다.각 청크는 delta 형태로 전달됩니다:
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"LLM42","choices":[{"index":0,"delta":{"role":"assistant","content":"안녕"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"LLM42","choices":[{"index":0,"delta":{"content":"하세요"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"LLM42","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
추론 모델 사용 시 응답 생성에 시간이 소요되므로 스트리밍 사용을 권장합니다.
OpenAI 함수 호출 규격과 동일한 JSON Schema 형식으로 도구를 정의합니다.
"tools": [
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "현재 날씨를 조회합니다.",
      "parameters": {
        "type": "object",
        "required": ["location"],
        "properties": {
          "location": {"type": "string", "description": "도시명"}
        }
      }
    }
  }
]
모델이 도구를 호출하기로 결정하면 응답의 tool_calls 배열에 파싱된 결과가 반환됩니다.tool_choice로 도구 선택 방식을 제어할 수 있습니다: auto (자동), none (사용 안 함), 또는 특정 함수 지정.
파라미터타입기본값설명
stopstring | array지정한 문자열이 생성되면 토큰 생성을 중단합니다.
frequency_penaltynumber0.0빈도 페널티 (-2.0 ~ 2.0)
presence_penaltynumber0.0존재 페널티 (-2.0 ~ 2.0)
userstring사용자 식별자 (선택사항)
skip_special_tokensbooleanfalse특수 토큰 건너뛰기 여부

모델별 상세 가이드

  • HCX-GOV-THINK / HCX-GOV
  • HCX-GOV-VLM
  • LLM42
  • HCX-GOV-THINK-V1-32B
  • LLM42-Translate
  • openai/gpt-oss-120b
HCX-007 기반의 HyperCLOVA X 언어 모델입니다.
  • HCX-GOV-THINK: 기본적으로 추론(Reasoning)이 활성화되어 있습니다. 복잡한 문제 해결, 논리적 분석, 코드 디버깅에 적합합니다.
  • HCX-GOV: 기본적으로 추론이 비활성화되어 있습니다. 빠른 응답이 필요한 일반 대화, 문서 작성, 간단한 질의에 적합합니다.
두 모델 모두 chat_template_kwargs로 추론 동작을 명시적으로 제어할 수 있습니다.

chat_template_kwargs

파라미터타입설명
force_reasoningboolean추론을 강제로 활성화합니다. reasoning_content 필드에 사고 과정이 반환됩니다.
skip_reasoningboolean추론을 강제로 비활성화합니다. 즉시 content만 반환됩니다.
force_reasoningskip_reasoning을 동시에 true로 설정하지 마십시오.
멀티 턴 대화 시 주의: 이전 응답의 reasoning_content는 다음 턴의 messages포함하지 마십시오. content 필드만 포함해야 합니다.

코드 예시: HCX-GOV-THINK (기본 — 추론 활성화)

from openai import OpenAI

client = OpenAI(
    base_url="https://api.clovastudio.go.kr/api/v1",
    api_key="YOUR_API_KEY",
)

response = client.chat.completions.create(
    model="HCX-GOV-THINK",
    messages=[
        {
            "role": "user",
            "content": "Think for maximum 1024 token.\nWhat is the capital of France?"
        }
    ],
    max_tokens=2048,
    temperature=0,
    stop=["<|im_end|><|endofturn|>", "<|im_end|><|stop|>"],
    extra_body={"skip_special_tokens": False, "chat_template_kwargs": {"force_reasoning": True}}
)

print("추론 과정:", response.choices[0].message.reasoning_content)
print("최종 답변:", response.choices[0].message.content)

코드 예시: HCX-GOV (기본 — 빠른 응답)

response = client.chat.completions.create(
    model="HCX-GOV",
    messages=[
        {"role": "user", "content": "What is the capital of France?"}
    ],
  max_tokens=2048,
  temperature=0,
  stop=["<|im_end|><|endofturn|>", "<|im_end|><|stop|>"],
  extra_body={"skip_special_tokens": False, "chat_template_kwargs": {"skip_reasoning": True}}
)
print(response.choices[0].message.content)
usage.completion_tokensreasoning_contentcontent의 토큰 수를 합산한 값입니다. 추론 모드 사용 시 토큰 소비량이 크게 증가할 수 있습니다.

스트리밍

stream: true로 설정하면 응답이 실시간으로 스트리밍됩니다. 추론 모델에서는 reasoning_content 델타가 먼저 전송된 후 content 델타가 전송됩니다.
from openai import OpenAI

client = OpenAI(
    base_url="https://api.clovastudio.go.kr/api/v1",
    api_key="YOUR_API_KEY",
)

stream = client.chat.completions.create(
    model="HCX-GOV-THINK",
    messages=[{"role": "user", "content": "안녕하세요!"}],
    max_tokens=2048,
    stop=["<|im_end|><|endofturn|>", "<|im_end|><|stop|>"],
    stream=True,
    extra_body={"skip_special_tokens": False},
)

reasoning_content = ""
content = ""

for chunk in stream:
    delta = chunk.choices[0].delta
    if hasattr(delta, "reasoning_content") and delta.reasoning_content:
        reasoning_content += delta.reasoning_content
    if delta.content:
        content += delta.content
        print(delta.content, end="", flush=True)
추론 모델에서 스트리밍 시 reasoning_content 델타가 먼저 전송되고, 이후 content 델타가 전송됩니다. 두 필드를 구분하여 처리하십시오.

멀티 턴 대화

이전 대화 내역을 messages 배열에 포함하여 문맥 있는 멀티 턴 대화를 구성합니다.
response1 = client.chat.completions.create(
    model="HCX-GOV-THINK",
    messages=[
        {"role": "user", "content": "안녕하세요!"}
    ],
    max_tokens=4096,
    stop=["<|im_end|><|endofturn|>", "<|im_end|><|stop|>"],
    extra_body={"skip_special_tokens": False},
)

messages = [
    {"role": "user", "content": "안녕하세요!"},
    {"role": "assistant", "content": response1.choices[0].message.content},
    {"role": "user", "content": "오늘 날씨가 어때요?"}
]

response2 = client.chat.completions.create(
    model="HCX-GOV-THINK",
    messages=messages,
    max_tokens=4096,
    stop=["<|im_end|><|endofturn|>", "<|im_end|><|stop|>"],
    extra_body={"skip_special_tokens": False},
)

응답 형식

필드타입설명
idstring요청 고유 식별자
objectstring"chat.completion"
createdintegerUnix 타임스탬프
modelstring사용된 모델명
choices[].message.rolestring항상 "assistant"
choices[].message.contentstring최종 답변. Tool call만 있을 경우 빈 문자열
choices[].message.reasoning_contentstring | null추론 과정. 추론 모델에서 추론 활성화 시에만 반환
choices[].message.tool_callsarray파싱된 Tool Call 목록
choices[].finish_reasonstring"stop", "length", "tool_calls"
usage.prompt_tokensinteger입력 토큰 수
usage.completion_tokensinteger생성 토큰 수 (추론 + 답변 합산)
usage.total_tokensinteger전체 토큰 수

Function Calling (함수 호출)

표준 OpenAI 도구 정의 형식을 사용합니다. 모델이 도구 호출을 결정하면 응답의 tool_calls 배열에 파싱된 결과가 반환됩니다.
import json
from openai import OpenAI

client = OpenAI(
    base_url="https://api.clovastudio.go.kr/api/v1",
    api_key="YOUR_API_KEY",
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_document_info",
            "description": "문서 관리 시스템에서 문서 정보를 조회합니다.",
            "parameters": {
                "type": "object",
                "required": ["document_id"],
                "properties": {
                    "document_id": {
                        "type": "string",
                        "description": "조회할 문서의 고유 ID"
                    }
                }
            }
        }
    }
]

response = client.chat.completions.create(
    model="HCX-GOV-THINK",
    messages=[
        {"role": "system", "content": "도구가 필요할 때는 tool_calls만 반환하세요."},
        {"role": "user", "content": "문서 ID 'DOC-2024-001'의 정보를 알려주세요."}
    ],
    tools=tools,
    max_tokens=512,
)

tool_call = response.choices[0].message.tool_calls[0]
function_name = tool_call.function.name
arguments = json.loads(tool_call.function.arguments)

tool_result = {"title": "2024년도 예산안", "status": "승인", "date": "2024-01-15"}

messages = [
    {"role": "system", "content": "도구가 필요할 때는 tool_calls만 반환하세요."},
    {"role": "user", "content": "문서 ID 'DOC-2024-001'의 정보를 알려주세요."},
    {
        "role": "assistant",
        "content": "",
        "tool_calls": [
            {
                "id": tool_call.id,
                "type": "function",
                "function": {
                    "name": tool_call.function.name,
                    "arguments": tool_call.function.arguments
                }
            }
        ]
    },
    {
        "role": "tool",
        "tool_call_id": tool_call.id,
        "content": json.dumps(tool_result, ensure_ascii=False)
    }
]

final_response = client.chat.completions.create(
    model="HCX-GOV-THINK",
    messages=messages,
    tools=tools,
    max_tokens=1024,
)
print(final_response.choices[0].message.content)

Authorizations

Authorization
string
header
required

발급받은 API 키를 Bearer 토큰 형식으로 전달합니다.

예시: Authorization: Bearer <API_KEY>

Body

application/json
model
enum<string>
default:LLM42
required

사용할 모델명

Available options:
LLM42,
HCX-GOV,
HCX-GOV-THINK,
HCX-GOV-VLM,
HCX-GOV-THINK-V1-32B,
LLM42-Translate,
openai/gpt-oss-120b
Example:

"LLM42"

messages
object[]
required

대화 메시지 배열. 각 메시지는 role과 content를 포함해야 합니다.

Role 종류:

  • system: 대화의 맥락 정보나 모델의 페르소나, 답변 형식 등의 조건을 지정합니다.
  • user: 사용자가 모델에게 전달하는 지시나 질문을 작성합니다.
  • assistant: 모델이 생성한 응답을 작성합니다. 멀티 턴 대화 시, 이전 대화 내역을 포함할 때 사용합니다.

멀티 턴 대화 시 주의:

  • 이전 응답의 reasoning_content는 제외하고 content만 포함해야 합니다.
Minimum length: 1
temperature
number
default:1

생성 토큰에 대한 다양성 정도를 조절합니다. 설정값이 높을수록 다양한 문장을 생성합니다.

  • 낮은 값(0에 가까움): 일관되고 예측 가능한 응답
  • 높은 값(2에 가까움): 창의적이고 다양한 응답
Required range: 0 <= x <= 2
Example:

0.7

top_p
number
default:1

생성 토큰 후보군을 누적 확률을 기반으로 샘플링합니다. 누적 확률이 top_p에 도달할 때까지의 토큰들을 후보로 사용합니다.

  • 낮은 값: 더 확실한 토큰만 선택 (보수적)
  • 높은 값: 더 많은 토큰 후보 고려 (다양성)
Required range: 0 <= x <= 1
Example:

0.9

frequency_penalty
number
default:0

빈도 페널티

Required range: -2 <= x <= 2
Example:

0

presence_penalty
number
default:0

존재 페널티

Required range: -2 <= x <= 2
Example:

0

stop

생성 중단 시퀀스. 지정한 문자열이 생성되면 토큰 생성을 중단합니다.

문자열 또는 문자열 배열로 지정할 수 있습니다.

Example:
[
"<|im_end|><|endofturn|>",
"<|im_end|><|stop|>"
]
stream
boolean
default:false

스트리밍 응답 여부. true로 설정하면 Server-Sent Events (SSE) 형식으로 응답이 전송되며, 각 청크는 delta 형태로 실시간으로 전달됩니다.

권장:

  • 추론 모드 사용 시: 응답 생성에 시간이 소요되므로 스트리밍 사용을 권장합니다.
  • 긴 출력이 예상되는 경우: 사용자 경험 개선을 위해 스트리밍 사용을 권장합니다.
Example:

false

user
string

사용자 식별자 (선택사항)

Example:

"user-123"

chat_template_kwargs
object

모델별 추가 파라미터. 각 모델의 Chat Template에 전달되는 키-값 쌍입니다.

모델별 지원 파라미터:

  • HCX-GOV-THINK-V1-32B: thinking (boolean) — 추론(thinking) 모드 활성화 여부, thinking_token_budget (integer) — 추론 블록에 사용할 최대 토큰 수
  • HCX-GOV-THINK / HCX-GOV / HCX-GOV-VLM: force_reasoning (boolean) — 추론 강제 활성화, skip_reasoning (boolean) — 추론 강제 비활성화
  • LLM42-Translate: source_lang_code (string, 필수), target_lang_code (string, 필수) — 원본/대상 언어 코드
  • openai/gpt-oss-120b: reasoning_effort (string) — 추론 강도 (low/medium/high)
  • LLM42: 추가 파라미터 불필요
max_tokens
integer

최대 생성 토큰 수 (추론 내용과 최종 답변 토큰 수를 모두 포함합니다).

권장 사항:

  • 추론 모드 사용 시: 충분한 토큰 수를 설정해야 합니다. 설정값이 충분히 크지 않으면 모델이 추론 과정 중 토큰 제한에 도달하여 최종 답변을 생성하지 못할 수 있습니다.
  • 추론 모드별 권장값:
    • 추론 미사용: 512 이상
    • 짧은 추론: 5120 이상
    • 중간 추론: 10240 이상
    • 긴 추론: 20480 이상

범위: 1 ≤ max_tokens ≤ 32768

Required range: 1 <= x <= 32768
Example:

2048

tools
object[]

사용 가능한 도구(함수) 목록. 모델이 관련성이 있다고 판단하면 적절한 도구를 호출할 수 있습니다.

응답 설명:

  • 파싱된 tool call들은 응답의 tool_calls 필드로 반환됩니다.
  • tool call 외에 모델이 생성한 추가 내용이 있으면 content 필드에 반환되고, 없으면 빈 문자열로 반환됩니다.
tool_choice
object

도구 선택 방식. 특정 함수를 지정하거나(function), 자동 선택(auto), 또는 도구 사용 안 함(none)을 설정할 수 있습니다.

skip_special_tokens
boolean
default:false

특수 토큰 건너뛰기 여부

Example:

false

Response

Successful Response

id
string

Chat Completion 요청의 고유 식별자

Example:

"chatcmpl-123abc"

object
string

객체 타입

Example:

"chat.completion"

created
integer

생성 시간 (Unix 타임스탬프)

Example:

1677652288

model
string

사용된 모델명

Example:

"HCX-GOV-THINK"

choices
object[]

생성된 선택지 배열

usage
object

토큰 사용량 정보

prompt_logprobs
object | null
service_tier
string | null

서비스 티어 정보

system_fingerprint
string | null

시스템 지문 (시스템 구성 식별자)

kv_transfer_params
object | null

KV 캐시 전송 파라미터