토큰 계산기(챗 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.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 - 대화 메시지의 역할
    • 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
            }
        }
    }
    

    실패

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