Classic/VPC 환경에서 이용 가능합니다.
이미지를 해석하고 이해할 수 있는 HCX-005 비전 모델과 경량화된 HCX-DASH-002 모델을 이용할 수 있는 v3 Chat Completions에 대해 설명합니다.
요청
요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.
메서드 | URI |
---|---|
POST | /v3/chat-completions/{modelName} |
요청 헤더
요청 헤더에 대한 설명은 다음과 같습니다.
헤더 | 필수 여부 | 설명 |
---|---|---|
Authorization |
Required | 인증을 위한 API 키 <예시> Bearer nv-************ |
X-NCP-CLOVASTUDIO-REQUEST-ID |
Optional | 요청에 대한 아이디 |
Content-Type |
Required | 요청 데이터의 형식
|
Accept |
Conditional | 응답 데이터의 형식
|
- 응답 결과는 기본적으로 JSON 형태로 반환되지만,
Accept
를text/event-stream
으로 지정 시 응답 결과를 스트림 형태로 반환합니다.
요청 경로 파라미터
요청 경로 파라미터에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
modelName |
Enum | Required | 모델 이름
|
- HCX-005와 HCX-DASH-002는 Chat Completions v3 API에서만 사용할 수 있습니다.
- 이미지 입력은 HyperCLOVA X 비전 모델인 HCX-005에서만 사용할 수 있습니다.
요청 바디
요청 바디에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
messages |
Array | Required | 대화 메시지 |
topP |
Double | Optional | 생성 토큰 후보군을 누적 확률을 기반으로 샘플링
|
topK |
Integer | Optional | 생성 토큰 후보군에서 확률이 높은 K개를 후보로 지정하여 샘플링topK ≤ 128 (기본값: 0) |
maxTokens |
Integer | Optional | 최대 생성 토큰 수maxTokens ≤ 4096 (기본값: 100) |
temperature |
Double | Optional | 생성 토큰에 대한 다양성 정도(설정값이 높을수록 다양한 문장 생성)
|
repetitionPenalty |
Double | Optional | 같은 토큰을 생성하는 것에 대한 패널티 정도(설정값이 높을수록 같은 결괏값을 반복 생성할 확률 감소)repetitionPenalty ≤ 2.0 (기본값: 1.1) |
stop |
Array | Optional | 토큰 생성 중단 문자 |
seed |
Integer | Optional | 모델 반복 실행 시 결괏값의 일관성 수준 조정
|
includeAiFilters |
Boolean | Optional | AI 필터(생성된 결괏값에 대해 욕설, 비하/차별/혐오, 성희롱/음란 등 카테고리별로 해당하는 정도) 결과 표시 여부
|
messages
messages
에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
role |
Enum | Required | 대화 메시지 역할
|
content |
String | Array | Required | 대화 메시지 내용
|
content
content
에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
type |
Enum | Required | 대화 메시지 내용의 형식
|
text |
String | Conditional | 대화 메시지 내용
|
imageUrl |
Object | Conditional | 이미지 목록
|
imageUrl.url |
String | Conditional | 파일 확장자를 포함한 단일 이미지의 공개 URL
|
dataUri |
Object | Conditional | 이미지 목록
|
dataUri.data |
String | Conditional | Base64로 인코딩된 이미지 문자열
|
일부 필드 입력 시 다음 내용을 확인해 주십시오.
- HCX-005
- 입력 토큰과 출력 토큰의 합은 128,000 토큰을 초과할 수 없습니다.
- 입력 토큰은 최대 128,000 토큰까지 가능합니다.
- 모델에 요청할 출력 토큰(maxTokens)은 최대 4,096 토큰까지 가능합니다.
messages
: 턴 당 이미지는 1개 포함 가능하고, 요청당 이미지는 최대 5개 포함할 수 있습니다.- 전체 Request Body 크기는 50MB 이하여야 합니다. 따라서 여러 개의 이미지를 요청에 포함하는 경우 base64 형식보다 image URL 사용을 권장합니다.
- HCX-DASH-002
- 입력 토큰과 출력 토큰의 합은 32,000 토큰을 초과할 수 없습니다.
- 입력 토큰은 최대 32,000 토큰까지 가능합니다.
- 모델에 요청할 출력 토큰(maxTokens)은 최대 4,096 토큰까지 가능합니다.
- 이미지 입력과 Function calling 요청을 동시에 할 수 없습니다.
요청 예시
요청 예시는 다음과 같습니다.
curl --location --request POST 'https://clovastudio.stream.gov-ntruss.com/testapp/v3/chat-completions/{modelName}' \
--header 'Authorization: Bearer <API-KEY>' \
--header 'X-NCP-CLOVASTUDIO-REQUEST-ID: <X-NCP-CLOVASTUDIO-REQUEST-ID>' \
--header 'Content-Type: application/json' \
--header 'Accept: text/event-stream' \
--data '{
"messages": [
{
"role": "system",
"content": [
{
"type": "text",
"text": "- 친절하게 답변하는 AI 어시스턴트입니다."
}
]
},
{
"role": "user",
"content": [
{
"type": "image_url",
"imageUrl": {
"url": "https://www.******.com/image_a1b1c1.png"
}
},
{
"type": "text",
"text": "이 사진에 대해서 설명해줘"
}
]
}
],
"temperature": 0.5,
"topK": 0,
"topP": 0.8,
"repetitionPenalty": 1.1,
"stop": [],
"maxTokens": 100,
"includeAiFilters": false
}'
응답
응답 형식을 설명합니다.
응답 헤더
응답 헤더에 대한 설명은 다음과 같습니다.
헤더 | 필수 여부 | 설명 |
---|---|---|
Content-Type | - | 응답 데이터의 형식
|
응답 바디
응답 바디에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
status |
Object | - | 응답 상태 |
result |
Object | - | 응답 결과 |
result.created |
Integer | - | 응답 날짜 (Unix timestamp 형식) |
result.usage |
Object | - | 토큰 수 정보 |
result.usage.promptTokens |
Integer | - | 입력 토큰 수 |
result.usage.completionTokens |
Integer | - | 생성 토큰 수 |
result.usage.totalTokens |
Integer | - | 전체 토큰 수(promptTokens +completionTokens |
result.message |
Object | - | 대화 메시지 |
result.message.role |
Enum | - | 대화 메시지 역할
|
result.message.content |
String | - | 대화 메시지 내용 |
result.finishReason |
String | - | 결괏값 생성 중단 이유
|
result.seed |
Integer | - | 입력 seed 값(0 입력 또는 미입력 시 랜덤 값 반환) |
result.aiFilter |
Array | - | AI 필터 결과 |
aiFilter
aiFilter
에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
groupName |
String | - | AI 필터 카테고리
|
name |
String | - | AI 필터 세부 카테고리
|
score |
String | - | AI 필터 점수
|
result |
String | - | AI 필터 정상 작동 여부
|
AI Filter는 최대 500자까지 분석할 수 있습니다. 단, 분석 대상 텍스트에 비정상적인 형식, 이모티콘, 특수 문자 등이 많은 경우, 정상적으로 분석되지 않을 수 있습니다.
응답 예시
응답 예시는 다음과 같습니다.
성공
호출이 성공한 경우의 응답 예시는 다음과 같습니다.
{
"status": {
"code": "20000",
"message": "OK"
},
"result": {
"created": 1791043155000,
"usage": {
"completionTokens": 80,
"promptTokens": 843,
"totalTokens": 923
},
"message": {
"role": "assistant",
"content": "사진에는 어린 아이가 양에게 먹이를 주는 모습이 담겨 있습니다. 아이는 파란색 옷을 입고 있으며, 줄문의 모자를 쓰고 있습니다. 아이의 표정은 집중하고 있는 듯 보이며, 양은 아이가 주는 먹이를 먹으려고 머리를 숙이고 있습니다. 배경에는 다른 양들도 보이며, 이 장소가 양 목장임을 짐작할 수 있습니다."
},
"seed": 1561390649,
"aiFilter": [
{
"groupName": "curse",
"name": "insult",
"score": "1"
},
{
"groupName": "curse",
"name": "discrimination",
"score": "0"
},
{
"groupName": "unsafeContents",
"name": "sexualHarassment",
"score": "2"
}
]
}
}
실패
호출이 실패한 경우의 응답 예시는 다음과 같습니다.
응답 스트림
생성되는 토큰을 하나씩 출력하도록 토큰 스트리밍을 사용할 수 있습니다. 토큰 스트리밍 형식을 설명합니다.
응답 헤더
응답 헤더에 대한 설명은 다음과 같습니다.
헤더 | 필수 여부 | 설명 |
---|---|---|
Accept | - | 응답 데이터의 형식
|
응답 바디
응답 바디에 대한 설명은 다음과 같습니다.
StreamingChatCompletionsTokenEvent
StreamingChatCompletionsResultEvent
에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
id |
String | - | 요청을 식별하는 이벤트 아이디 |
message |
Object | - | 대화 메시지 |
message.role |
Enum | - | 대화 메시지 역할
|
message.content |
String | - | 대화 메시지 내용 |
finishReason |
String | - | 결괏값 생성 중단 이유
|
created |
Integer | - | 응답 날짜 (Unix timestamp 형식) |
seed |
Integer | - | 입력 seed 값(0 입력 또는 미입력 시 랜덤 값 반환) |
usage |
Object | - | 토큰 수 정보 |
StreamingChatCompletionsResultEvent
StreamingChatCompletionsResultEvent
에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
id |
String | - | 요청을 식별하는 이벤트 아이디 |
message |
Object | - | 대화 메시지 |
message.role |
Enum | - | 대화 메시지 역할
|
message.content |
String | - | 대화 메시지 내용 |
finishReason |
String | - | 결괏값 생성 중단 이유
|
created |
Integer | - | 응답 날짜 (Unix timestamp 형식) |
seed |
Integer | - | 입력 seed 값(0 입력 또는 미입력 시 랜덤 값 반환) |
usage |
Object | - | 토큰 수 정보 |
usage.promptTokens |
Integer | - | 입력 토큰 수 |
usage.completionTokens |
Integer | - | 생성 토큰 수 |
result.usage.totalTokens |
Integer | - | 전체 토큰 수(promptTokens +completionTokens |
aiFilter |
Array | - | AI 필터 결과 |
ErrorEvent
ErrorEvent
에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
status |
Object | - | 응답 상태 |
SignalEvent
SignalEvent
에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
data |
String | - | 전달할 시그널 데이터 정보 |
응답 예시
응답 예시는 다음과 같습니다.
성공
호출이 성공한 경우의 예시는 다음과 같습니다.
id: 484f9a63-8231-441b-b2dc-683ed135dd03
event: signal
data:
{
"data": "[DONE]"
}
id: 8138bd06-9d29-43fb-9a91-72bc12bd31a1
event: result
data:
{
"message": {
"role": "assistant",
"content": "문구: 생각을 기록하고, 꿈을 그리다. 내 삶의 이야기, 다이어리가 함께합니다."
},
"finishReason": "stop",
"created": 1734016821,
"seed": 1342914828,
"usage": {
"promptTokens": 98,
"completionTokens": 212,
"totalTokens": 310
}
}
id: 9517637c-17aa-4a4a-a076-3fde680a953e
event: token
data:
{
"message": {
"role": "assistant",
"content": "."
},
"finishReason": null,
"created": 1734016821,
"seed": 1342914828,
"usage": null
}
id: 1dd8d882-4b8c-4435-abc5-f58bdbbc17a8
event: token
data:
{
"message": {
"role": "assistant",
"content": "합니다"
},
"finishReason": null,
"created": 1734016821,
"seed": 1342914828,
"usage": null
}
…
실패
호출이 실패한 경우의 응답 예시는 다음과 같습니다.