개요
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-THINK | HCX-GOV-THINK | 추론형 | — | 기본 활성화 | force_reasoning / skip_reasoning |
| HCX-GOV | HCX-GOV | 범용 | — | 기본 비활성화 | force_reasoning / skip_reasoning |
| HCX-GOV-VLM | HCX-GOV-VLM | 멀티모달 | 이미지 | 선택 가능 | force_reasoning / skip_reasoning |
| LLM42 | LLM42 | 범용 다국어 | 이미지 | — | 140개 언어 지원, 추가 파라미터 불필요 |
| HCX-GOV-THINK-V1-32B | HCX-GOV-THINK-V1-32B | 추론형 | — | thinking: true 설정 시 | XML 포맷 Tool Call 내부 사용 |
| LLM42-Translate | LLM42-Translate | 번역 전용 | — | — | source_lang_code, target_lang_code 필수 |
| openai/gpt-oss-120b | openai/gpt-oss-120b | 대규모 범용 | — | reasoning_effort 조절 | low / medium / high |
공통 파라미터
필수 파라미터: model, messages
필수 파라미터: model, messages
생성 제어 파라미터: temperature, top_p, max_tokens
생성 제어 파라미터: temperature, top_p, max_tokens
스트리밍: stream
스트리밍: stream
stream: true로 설정하면 Server-Sent Events (SSE) 형식으로 응답이 실시간 전송됩니다.각 청크는 delta 형태로 전달됩니다:Tool Calling: tools, tool_choice
Tool Calling: tools, tool_choice
tool_calls 배열에 파싱된 결과가 반환됩니다.tool_choice로 도구 선택 방식을 제어할 수 있습니다: auto (자동), none (사용 안 함), 또는 특정 함수 지정.기타 파라미터
기타 파라미터
| 파라미터 | 타입 | 기본값 | 설명 |
|---|---|---|---|
stop | string | array | — | 지정한 문자열이 생성되면 토큰 생성을 중단합니다. |
frequency_penalty | number | 0.0 | 빈도 페널티 (-2.0 ~ 2.0) |
presence_penalty | number | 0.0 | 존재 페널티 (-2.0 ~ 2.0) |
user | string | — | 사용자 식별자 (선택사항) |
skip_special_tokens | boolean | false | 특수 토큰 건너뛰기 여부 |
모델별 상세 가이드
- HCX-GOV-THINK / HCX-GOV
- HCX-GOV-VLM
- LLM42
- HCX-GOV-THINK-V1-32B
- LLM42-Translate
- openai/gpt-oss-120b
- HCX-GOV-THINK: 기본적으로 추론(Reasoning)이 활성화되어 있습니다. 복잡한 문제 해결, 논리적 분석, 코드 디버깅에 적합합니다.
- HCX-GOV: 기본적으로 추론이 비활성화되어 있습니다. 빠른 응답이 필요한 일반 대화, 문서 작성, 간단한 질의에 적합합니다.
chat_template_kwargs로 추론 동작을 명시적으로 제어할 수 있습니다.chat_template_kwargs
| 파라미터 | 타입 | 설명 |
|---|---|---|
force_reasoning | boolean | 추론을 강제로 활성화합니다. reasoning_content 필드에 사고 과정이 반환됩니다. |
skip_reasoning | boolean | 추론을 강제로 비활성화합니다. 즉시 content만 반환됩니다. |
코드 예시: HCX-GOV-THINK (기본 — 추론 활성화)
코드 예시: HCX-GOV (기본 — 빠른 응답)
usage.completion_tokens는 reasoning_content와 content의 토큰 수를 합산한 값입니다. 추론 모드 사용 시 토큰 소비량이 크게 증가할 수 있습니다.스트리밍
stream: true로 설정하면 응답이 실시간으로 스트리밍됩니다. 추론 모델에서는 reasoning_content 델타가 먼저 전송된 후 content 델타가 전송됩니다.
멀티 턴 대화
이전 대화 내역을messages 배열에 포함하여 문맥 있는 멀티 턴 대화를 구성합니다.
응답 형식
| 필드 | 타입 | 설명 |
|---|---|---|
id | string | 요청 고유 식별자 |
object | string | "chat.completion" |
created | integer | Unix 타임스탬프 |
model | string | 사용된 모델명 |
choices[].message.role | string | 항상 "assistant" |
choices[].message.content | string | 최종 답변. Tool call만 있을 경우 빈 문자열 |
choices[].message.reasoning_content | string | null | 추론 과정. 추론 모델에서 추론 활성화 시에만 반환 |
choices[].message.tool_calls | array | 파싱된 Tool Call 목록 |
choices[].finish_reason | string | "stop", "length", "tool_calls" 등 |
usage.prompt_tokens | integer | 입력 토큰 수 |
usage.completion_tokens | integer | 생성 토큰 수 (추론 + 답변 합산) |
usage.total_tokens | integer | 전체 토큰 수 |
Function Calling (함수 호출)
표준 OpenAI 도구 정의 형식을 사용합니다. 모델이 도구 호출을 결정하면 응답의tool_calls 배열에 파싱된 결과가 반환됩니다.
Authorizations
발급받은 API 키를 Bearer 토큰 형식으로 전달합니다.
예시: Authorization: Bearer <API_KEY>
Body
사용할 모델명
LLM42, HCX-GOV, HCX-GOV-THINK, HCX-GOV-VLM, HCX-GOV-THINK-V1-32B, LLM42-Translate, openai/gpt-oss-120b "LLM42"
대화 메시지 배열. 각 메시지는 role과 content를 포함해야 합니다.
Role 종류:
system: 대화의 맥락 정보나 모델의 페르소나, 답변 형식 등의 조건을 지정합니다.user: 사용자가 모델에게 전달하는 지시나 질문을 작성합니다.assistant: 모델이 생성한 응답을 작성합니다. 멀티 턴 대화 시, 이전 대화 내역을 포함할 때 사용합니다.
멀티 턴 대화 시 주의:
- 이전 응답의
reasoning_content는 제외하고content만 포함해야 합니다.
1생성 토큰에 대한 다양성 정도를 조절합니다. 설정값이 높을수록 다양한 문장을 생성합니다.
- 낮은 값(0에 가까움): 일관되고 예측 가능한 응답
- 높은 값(2에 가까움): 창의적이고 다양한 응답
0 <= x <= 20.7
생성 토큰 후보군을 누적 확률을 기반으로 샘플링합니다. 누적 확률이 top_p에 도달할 때까지의 토큰들을 후보로 사용합니다.
- 낮은 값: 더 확실한 토큰만 선택 (보수적)
- 높은 값: 더 많은 토큰 후보 고려 (다양성)
0 <= x <= 10.9
빈도 페널티
-2 <= x <= 20
존재 페널티
-2 <= x <= 20
생성 중단 시퀀스. 지정한 문자열이 생성되면 토큰 생성을 중단합니다.
문자열 또는 문자열 배열로 지정할 수 있습니다.
[
"<|im_end|><|endofturn|>",
"<|im_end|><|stop|>"
]스트리밍 응답 여부. true로 설정하면 Server-Sent Events (SSE) 형식으로 응답이 전송되며, 각 청크는 delta 형태로 실시간으로 전달됩니다.
권장:
- 추론 모드 사용 시: 응답 생성에 시간이 소요되므로 스트리밍 사용을 권장합니다.
- 긴 출력이 예상되는 경우: 사용자 경험 개선을 위해 스트리밍 사용을 권장합니다.
false
사용자 식별자 (선택사항)
"user-123"
모델별 추가 파라미터. 각 모델의 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: 추가 파라미터 불필요
최대 생성 토큰 수 (추론 내용과 최종 답변 토큰 수를 모두 포함합니다).
권장 사항:
- 추론 모드 사용 시: 충분한 토큰 수를 설정해야 합니다. 설정값이 충분히 크지 않으면 모델이 추론 과정 중 토큰 제한에 도달하여 최종 답변을 생성하지 못할 수 있습니다.
- 추론 모드별 권장값:
- 추론 미사용: 512 이상
- 짧은 추론: 5120 이상
- 중간 추론: 10240 이상
- 긴 추론: 20480 이상
범위: 1 ≤ max_tokens ≤ 32768
1 <= x <= 327682048
사용 가능한 도구(함수) 목록. 모델이 관련성이 있다고 판단하면 적절한 도구를 호출할 수 있습니다.
응답 설명:
- 파싱된 tool call들은 응답의
tool_calls필드로 반환됩니다. - tool call 외에 모델이 생성한 추가 내용이 있으면
content필드에 반환되고, 없으면 빈 문자열로 반환됩니다.
도구 선택 방식. 특정 함수를 지정하거나(function), 자동 선택(auto), 또는 도구 사용 안 함(none)을 설정할 수 있습니다.
특수 토큰 건너뛰기 여부
false
Response
Successful Response
Chat Completion 요청의 고유 식별자
"chatcmpl-123abc"
객체 타입
"chat.completion"
생성 시간 (Unix 타임스탬프)
1677652288
사용된 모델명
"HCX-GOV-THINK"
생성된 선택지 배열
토큰 사용량 정보
서비스 티어 정보
시스템 지문 (시스템 구성 식별자)
KV 캐시 전송 파라미터