Classic/VPC 환경에서 이용 가능합니다.
Chat Completions v3를 통해 HCX 모델에 입력한 문장의 토큰 수를 계산합니다.
요청
요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.
메서드 | URI |
---|---|
POST | /v3/api-tools/chat-tokenize/{modelName} |
요청 헤더
요청 헤더에 대한 설명은 다음과 같습니다.
헤더 | 필수 여부 | 설명 |
---|---|---|
Authorization |
Required | 인증을 위한 API 키 (예: Bearer nv-*********** ) |
X-NCP-CLOVASTUDIO-REQUEST-ID |
Optional | 요청 ID |
Content-Type |
Required | 요청 데이터의 형식
|
요청 경로 파라미터
요청 경로 파라미터에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
modelName |
String | Required | 모델 이름 |
요청 바디
요청 바디에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
messages |
Array | Required | 토큰 수를 계산할 대화 메시지 목록: ChatMessage |
tools |
Array | Optional | Function Calling 사용 가능 도구 목록: tools |
toolChoice |
String | Object | Optional | Function Calling 도구 호출 동작 방식
|
toolChoice.type |
String | Optional | Function Calling 모델이 호출할 도구 유형 |
toolChoice.function |
Object | Optional | Function Calling 모델이 호출할 도구
|
toolChoice.function.name |
String | Optional | Function Calling 모델이 호출할 도구 이름 |
ChatMessage
ChatMessage
에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
role |
Enum | Required | 대화 메시지 역할
|
content |
String | Array | Required | 대화 메시지 내용
|
toolCalls |
Array | Conditional | assistant의 호출 도구 정보
|
toolCallId |
String | Conditional | 도구 아이디
|
content
content
에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
type |
Enum | Required | 대화 메시지 내용의 형식
|
text |
String | Conditional | 대화 메시지 내용
|
imageUrl |
Object | Conditional | 이미지 목록
|
imageUrl.url |
String | Conditional | 파일 확장자를 포함한 단일 이미지의 공개 URL
|
dataUri |
Object | Conditional | 이미지 목록
|
dataUri.data |
String | Conditional | Base64로 인코딩된 이미지 문자열
|
tools
tools
에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
type |
String | Required | 도구 유형
|
function |
Object | Required | 호출 function 정보 |
function.name |
String | Required | function 이름 |
function.description |
String | Required | function 설명 |
function.parameters |
Object | Required | function 사용 시 전달되는 매개변수
|
toolCalls
toolCalls
에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
id |
String | - | 도구 식별자 |
type |
String | - | 도구 유형
|
function |
Object | - | 호출 function 정보 |
function.name |
String | - | function 이름 |
function.arguments |
Object | - | function 사용시 전달되는 매개변수 |
요청 예시
요청 예시는 다음과 같습니다.
이미지로 질의하는 경우
이미지로 질의하는 경우의 요청 예시는 다음과 같습니다.
curl --location --request POST 'https://clovastudio.stream.gov-ntruss.com/v3/api-tools/chat-tokenize/{modelName}' \
--header 'Authorization: Bearer {API Key}' \
--header 'X-NCP-CLOVASTUDIO-REQUEST-ID: {Request ID}' \
--header 'Content-Type: application/json' \
--data '{
"messages": [
{
"messages": [
{
"role": "system",
"content": "- 친절하게 답변하는 AI 어시스턴트입니다."
},
{
"role": "user",
"content": [
{
"type": "image_url",
"imageUrl": [
{
"url": "https://www.******.com/image_a1b1c1.png"
}
]
},
{
"type": "text",
"text": "이 사진에 대해서 설명해줘"
}
]
},
{
"role": "assistant",
"content": "사진에는 어린 아이가 양에게 먹이를 주는 모습이 담겨 있습니다."
}
]
}'
텍스트로 질의하는 경우
텍스트로 질의하는 경우의 요청 예시는 다음과 같습니다.
curl --location --request POST 'https://clovastudio.stream.gov-ntruss.com/v3/api-tools/chat-tokenize/{modelName}' \
--header 'Authorization: Bearer {API Key}' \
--header 'X-NCP-CLOVASTUDIO-REQUEST-ID: {Request ID}' \
--header 'Content-Type: application/json' \
--data '{
"messages":[
{
"content":"내일 서울 날씨 어때?",
"role":"user"
}
],
"tools":[
{
"type":"function",
"function":{
"description":"날씨를 알려줄 수 있는 도구",
"name":"weather",
"parameters":{
"properties":{
"location":{
"description":"서울, 대전, 부산 등의 도시 이름",
"type":"string"
},
"unit":{
"enum":[
"celsius",
"fahrenheit"
],
"type":"string"
},
"date":{
"description":"2023-08-01 같은 형태의 날짜 문자열. 날씨를 알고 싶은 날짜",
"type":"string"
}
},
"required":[
"location"
],
"type":"object"
}
}
},
{
"type":"function",
"function":{
"description":"여행지를 추천해 줄 수 있는 도구",
"name":"travel",
"parameters":{
"properties":{
"location":{
"description":"The city and state, e.g. San Francisco, CA",
"type":"string"
},
"date":{
"description":"\"2023-08-01~2023-09-01\" 같은 형태의 날짜 쌍 문자열. 여행 날짜 범위",
"type":"string"
}
},
"required":[
"location"
],
"type":"object"
}
}
}
],
"toolChoice":"auto"
}'
응답
응답 형식을 설명합니다.
응답 바디
응답 바디에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
messages |
Array | - | 토큰 수가 계산된 요청 대화 메시지 목록: ChatMessage |
ChatMessages.role |
Enum | - | 대화 메시지의 역할
|
ChatMessage.content |
Array | - | 메시지 내용 토큰 계산 결과: ChatMessageCount |
tools |
Array | - | 토큰 수가 계산된 요청 도구 목록: ToolCount |
ChatMessageCount
ChatMessageCount
에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
type |
Enum | Required | 대화 메시지 내용의 형식
|
text |
String | Conditional | 대화 메시지 내용
|
imageUrl |
Object | Conditional | 대화 메시지 내용
|
imageUrl.url |
String | Conditional | 파일 확장자를 포함한 단일 이미지의 공개 URL
|
dataUri |
Object | Conditional | 대화 메시지 내용
|
dataUri.data |
String | Conditional | Base64로 인코딩된 이미지 문자열
|
count |
Integer | Required | 대화 메시지 내용 별 토큰 수 계산 결과 |
ToolCount
ToolCount
에 대한 설명은 다음과 같습니다.
필드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
count |
Integer | Required | 도구 목록의 토큰 수 계산 결과 |
응답 예시
응답 예시는 다음과 같습니다.
성공
호출이 성공한 경우의 응답 예시는 다음과 같습니다.
{
"status": {
"code": "20000",
"message": "OK"
},
"result": {
"messages": [
{
"role": "system",
"content": {
"type": "text",
"text": "- 친절하게 답변하는 AI 어시스턴트입니다.",
"count": 16
}
},
{
"role": "user",
"content": [
{
"type": "image_url",
"imageUrl": {
"url": "https://www.******.com/image_a1b1c1.png"
},
"count": 1478
},
{
"type": "text",
"text": "이 사진에 대해서 설명해줘",
"count": 12
}
]
},
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "사진에는 어린 아이가 양에게 먹이를 주는 모습이 담겨 있습니다.",
"count": 20
}
]
}
]
}
}
{
"status": {
"code": "20000",
"message": "OK"
},
"result": {
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "내일 서울 날씨 어때?",
"count": 12
}
]
}
],
"tools": {
"count": 230
}
}
}
실패
호출이 실패한 경우의 구문 예시는 다음과 같습니다.