토큰 계산기(챗 v3)

Prev Next

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 요청 데이터의 형식
  • application/json

요청 경로 파라미터

요청 경로 파라미터에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
modelName String Required 모델 이름
  • <예시> HCX-005

요청 바디

요청 바디에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
messages Array Required 토큰 수를 계산할 대화 메시지 목록: ChatMessage
tools Array Optional Function Calling 사용 가능 도구 목록: tools
toolChoice String | Object Optional Function Calling 도구 호출 동작 방식
  • auto : 모델이 도구 자동 호출 (String)
  • none : 모델이 도구 호출 없이 일반 답변 생성(String)
  • 모델이 특정 도구 강제 호출(Object)
toolChoice.type String Optional Function Calling 모델이 호출할 도구 유형
toolChoice.function Object Optional Function Calling 모델이 호출할 도구
  • function(유효값)
toolChoice.function.name String Optional Function Calling 모델이 호출할 도구 이름

ChatMessage

ChatMessage에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
role Enum Required 대화 메시지 역할
  • system | user | assistant | tool
    • system: 역할을 규정하는 지시문
    • user: 사용자의 발화 또는 질문
    • assistant: 사용자의 발화 또는 질문에 대한 답변
    • tool: Function Calling에 따른 처리 결과 입력
content String | Array Required 대화 메시지 내용
toolCalls Array Conditional assistant의 호출 도구 정보
  • role이 tool인 경우 assistant의 toolCalls 요청과 같이 입력
toolCallId String Conditional 도구 아이디
  • role이 tool인 경우, 필수 입력
  • assistant의 toolCalls 요청과 연결하는 용도

content

content에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
type Enum Required 대화 메시지 내용의 형식
  • text | image_url
    • text : 텍스트
    • image_url : 이미지 URL
text String Conditional 대화 메시지 내용
  • 텍스트 입력
    • typetext인 경우, 필수 입력
imageUrl Object Conditional 이미지 목록
  • typeimage_url인 경우, imageUrldataUri 중 필수 입력
  • 턴당 이미지 1개 포함 가능
  • 최적의 결과를 위해 text와 함께 요청 권장
imageUrl.url String Conditional 파일 확장자를 포함한 단일 이미지의 공개 URL
  • 이미지 지원 사양
    • 형식: BMP, PNG, JPG, JPEG, WEBP
    • 크기: 0Byte 초과 20MB 이하
    • 비율: 가로, 세로가 1:5 또는 5:1 이하
    • 길이: 가로, 세로 중 긴 쪽은 2240px이하. 짧은 쪽은 4px 이상
dataUri Object Conditional 이미지 목록
  • typeimage_url인 경우, imageUrldataUri 중 필수 입력
  • 턴당 이미지 1개 포함 가능
  • 최적의 결과를 위해 text와 함께 요청 권장
dataUri.data String Conditional Base64로 인코딩된 이미지 문자열
  • 이미지 지원 사양
    • 형식: BMP, PNG, JPG, JPEG, WEBP
    • 크기: 0Byte 초과 20MB 이하
    • 비율: 가로, 세로가 1:5 또는 5:1 이하
    • 길이: 가로, 세로 중 긴 쪽은 2240px이하. 짧은 쪽은 4px 이상

tools

tools에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
type String Required 도구 유형
  • function(유효값)
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(유효값)
function Object - 호출 function 정보
function.name String - function 이름
function.arguments Object - function 사용시 전달되는 매개변수

요청 예시

요청 예시는 다음과 같습니다.

이미지로 질의하는 경우

이미지로 질의하는 경우의 요청 예시는 다음과 같습니다.

curl --location --request POST 'https://clovastudio.stream.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.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 - 대화 메시지의 역할
  • system | user | assistant | tool
    • system: 역할을 규정하는 지시문
    • user: 사용자의 발화 또는 질문
    • assistant: 모델의 답변
    • tool: Function Calling에 따른 처리 결과 입력
ChatMessage.content Array - 메시지 내용 토큰 계산 결과: ChatMessageCount
tools Array - 토큰 수가 계산된 요청 도구 목록: ToolCount

ChatMessageCount

ChatMessageCount에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
type Enum Required 대화 메시지 내용의 형식
  • text | image_url
    • text : 텍스트
    • image_url : 이미지 URL
text String Conditional 대화 메시지 내용
  • 텍스트 입력
    • typetext인 경우 입력 필수
imageUrl Object Conditional 대화 메시지 내용
  • 이미지 URL 입력
    • typeimage_url인 경우 'imageUrl'과 'dataUri' 둘 중 하나는 입력 필수
  • 턴당 이미지 1개 포함 가능
  • 최적의 결과를 위해 text와 함께 요청 권장
imageUrl.url String Conditional 파일 확장자를 포함한 단일 이미지의 공개 URL
  • 이미지 지원 사양
    • 확장자: BMP, PNG, JPG, JPEG, WEBP
    • 크기: 20MB 미만
    • 가로:세로 비율 1:5 또는 5:1 이하
      • 장축(가로와 세로 중 긴 쪽) 길이: 2240px 이하
dataUri Object Conditional 대화 메시지 내용
  • 이미지 URL 입력
    • typeimage_url인 경우 'imageUrl'과 'dataUri' 둘 중 하나는 입력 필수
  • 턴당 이미지 1개 포함 가능
  • 최적의 결과를 위해 text와 함께 요청 권장
dataUri.data String Conditional Base64로 인코딩된 이미지 문자열
  • 이미지 지원 사양
    • 확장자: BMP, PNG, JPG, JPEG, WEBP
    • 크기: 20MB 이하
    • 가로:세로 비율 1:5 또는 5:1 이하
      • 장축(가로와 세로 중 긴 쪽) 길이: 2240px 이하, 짧은 쪽은 4px 이상
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
        }
    }
}

실패

호출이 실패한 경우의 응답 예시는 다음과 같습니다.