POST
/
v1
/
chat
/
completions
curl --request POST \
  --url https://hcx-gov-think.clovastudio.go.kr/v1/chat/completions \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "hcx-gov-think",
  "messages": [
    {
      "role": "user",
      "content": "What is the capital of France?"
    }
  ],
  "max_tokens": 2048,
  "temperature": 1
}'
{
  "id": "chatcmpl-123abc",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "hcx-gov-think",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris.",
        "tool_calls": []
      },
      "logprobs": null,
      "finish_reason": "stop",
      "stop_reason": null
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "total_tokens": 25,
    "completion_tokens": 10,
    "prompt_tokens_details": null
  },
  "prompt_logprobs": null
}

​
API URL

현재 단일 모델과 연결되어 있는 아래 URL 로 요청 가능합니다. 
https://hcx-gov-think.clovastudio.go.kr

Body

application/json
​
model
string
required

사용할 모델명 (현재 단일 모델과 연결됨)

Example:

"hcx-gov-think"

​
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

추론 모델 설정 정보. AI 모델이 응답을 생성하기 전에 내부적으로 사고 과정(reasoning/thinking)을 거칠지 제어합니다.

추론 과정: 추론 모델은 최종 답변을 바로 생성하지 않고, 사용자 질의를 분석하고 필요한 논리적 사고 과정을 거쳐 추론 내용을 생성한 뒤 이를 바탕으로 최종 답변을 생성합니다.

설정 권장:

  • force_reasoning: true: 복잡한 문제, 논리적 추론이 필요한 질문에 권장
  • skip_reasoning: true: 간단한 질문, 빠른 응답이 필요한 경우에 권장
  • 둘 다 설정 안 함: 모델이 자동으로 추론 여부 결정 (권장)

우선순위: force_reasoning: true + skip_reasoning: true → force_reasoning이 우선 적용됨

​
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 캐시 전송 파라미터