--- title: "토큰 계산기(챗 v3)" slug: "clovastudio-tokenizerhcxv3" updated: 2026-04-23T08:55:44Z published: 2026-04-23T09:02:20Z --- > ## Documentation Index > Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # 토큰 계산기(챗 v3) Classic/VPC 환경에서 이용 가능합니다. Chat Completions V3를 통해 HCX 모델에 입력한 문장의 토큰 수를 계산합니다. ## 요청 요청 형식을 설명합니다. 요청 형식은 다음과 같습니다. | 메서드 | URI | | --- | --- | | POST | /v3/api-tools/chat-tokenize/{modelName} | ### 요청 헤더 CLOVA Studio API에서 공통으로 사용하는 헤더에 대한 정보는 [CLOVA Studio 요청 헤더](/docs/ai-naver-clovastudio-summary#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94)를 참조해 주십시오. ### 요청 경로 파라미터 요청 경로 파라미터에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `modelName` | String | Required | 모델 이름 - <예시> HCX-005 | ### 요청 바디 요청 바디에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `messages` | Array | Required | 토큰 수를 계산할 대화 메시지 목록: [messages](/docs/clovastudio-tokenizerhcxv3#messages1) | | `tools` | Array | Optional | `Function Calling` 사용 가능 도구 목록: [tools](/docs/clovastudio-tokenizerhcxv3#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` 모델이 호출할 도구 이름 | | `responseFormat` | Object | Optional | 모델이 출력하는 답변 형식 | | `responseFormat.type` | String | Optional | 답변 형식 타입 - `json` (유효 값) | | `responseFormat.schema` | Object | Optional | 답변 형식 스키마 - 답변 형식 타입에 맞는 스키마 - JSON Schema(object) (유효 값) | #### `messages` `messages`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `role` | Enum | Required | 대화 메시지 역할 - `system` \| `user` \| `assistant` \| `tool` - `system`: 역할을 규정하는 지시문 - `user`: 사용자의 발화 또는 질문 - `assistant`: 사용자의 발화 또는 질문에 대한 답변 - `tool`: `Function Calling`에 따른 처리 결과 입력 | | `content` | String \| Array | Required | 대화 메시지 내용 - 텍스트 입력(String) - 텍스트, 이미지 URL로 구성하여 입력(Array): [content](/docs/clovastudio-tokenizerhcxv3#content) | | `toolCalls` | Array | Conditional | assistant의 호출 도구 정보 - role이 tool인 경우 assistant의 [toolCalls](/docs/clovastudio-tokenizerhcxv3#toolCalls) 요청과 같이 입력 | | `toolCallId` | String | Conditional | 도구 아이디 - role이 tool인 경우, 필수 입력 - assistant의 [toolCalls](/docs/clovastudio-tokenizerhcxv3#toolCalls) 요청과 연결하는 용도 | #### `content` `content`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `type` | Enum | Required | 대화 메시지 내용의 형식 - `text` \| `image_url` - `text` : 텍스트 - `image_url` : 이미지 URL | | `text` | String | Conditional | 대화 메시지 내용 - 텍스트 입력 - `type`이 `text`인 경우, 필수 입력 | | `imageUrl` | Object | Conditional | 이미지 목록 - `type`이 `image_url`인 경우, `imageUrl`과 `dataUri` 중 필수 입력 - 턴당 이미지 1개 포함 가능 - 최적의 결과를 위해 `text`와 함께 요청 권장 | | `imageUrl.url` | String | Conditional | 파일 확장자를 포함한 단일 이미지의 공개 URL - 이미지 지원 사양 - 형식: BMP, PNG, JPG, JPEG, WEBP - 크기: 0Byte 초과 20MB 이하 - 비율: 가로, 세로가 1:5 또는 5:1 이하 - 길이: 가로, 세로 중 긴 쪽은 2240px이하. 짧은 쪽은 4px 이상 | | `dataUri` | Object | Conditional | 이미지 목록 - `type`이 `image_url`인 경우, `imageUrl`과 `dataUri` 중 필수 입력 - 턴당 이미지 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` 사용 시 전달되는 매개변수 - properties, required - 입력: [요청 예시](/docs/clovastudio-tokenizerhcxv3#%EC%9A%94%EC%B2%AD%EC%98%88%EC%8B%9C) 참조 - 형식: [JSON Schema reference](https://json-schema.org/understanding-json-schema/reference) 참조 | #### `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": [ { "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" }' ``` #### Structured Outputs로 질의하는 경우 Structured Outputs로 질의하는 경우의 요청 예시는 다음과 같습니다. ``` 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": [ { "role": "system", "content": "- 미리 정의한 JSON Schema 형식에 맞춰 답변하는 AI 어시스턴트입니다." }, { "role": "user", "content": "오늘의 최고 기온은 32도, 최저 기온은 15도, 강수 확률은 30%입니다." } ], "responseFormat": { "type" : "json", "schema": { "type": "object", "properties": { "temp_high_c": { "type": "number", "description": "최고 기온(섭씨)" }, "temp_low_c": { "type": "number", "description": "최저 기온(섭씨)" }, "precipitation_percent": { "type": "number", "description": "강수 확률(%)", "minimum": 0, "maximum": 100 } }, "required": [ "temp_high_c", "temp_low_c", "precipitation_percent" ] } } }' ``` ## 응답 응답 형식을 설명합니다. ### 응답 바디 응답 바디에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `status` | Object | - | [응답 상태](/docs/ai-naver-clovastudio-summary#%EC%9D%91%EB%8B%B5) 참조 | | `result` | Object | - | 응답 결과 | | `result.messages` | Array | - | 토큰 수가 계산된 요청 대화 메시지 목록: [messages](/docs/clovastudio-tokenizerhcxv3#messages2) | | `result.tools` | Object | - | 토큰 수가 계산된 요청 도구 목록: [ToolCount](/docs/clovastudio-tokenizerhcxv3#ToolCount) | | `result.responseFormat` | Object | - | Structured Outputs 토큰 계산 결과: [ResponseFormatCount](/docs/clovastudio-tokenizerhcxv3#ResponseFormatCount) | #### `messages` `messages`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `role` | Enum | - | 대화 메시지의 역할 - `system` \| `user` \| `assistant` \| `tool` - `system`: 역할을 규정하는 지시문 - `user`: 사용자의 발화 또는 질문 - `assistant`: 모델의 답변 - `tool`: `Function Calling`에 따른 처리 결과 입력 | | `content` | Object | - | 메시지 내용 토큰 계산 결과: [ChatMessageCount](/docs/clovastudio-tokenizerhcxv3#ChatMessageCount) | #### `ChatMessageCount` `ChatMessageCount`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `type` | Enum | Required | 대화 메시지 내용의 형식 - `text` \| `image_url` - `text` : 텍스트 - `image_url` : 이미지 URL | | `text` | String | Conditional | 대화 메시지 내용 - 텍스트 입력 | | `imageUrl` | Object | Conditional | 대화 메시지 내용 - 이미지 URL 입력 - 턴당 이미지 1개 포함 가능 - 최적의 결과를 위해 `text`와 함께 요청 권장 | | `imageUrl.url` | String | Conditional | 파일 확장자를 포함한 단일 이미지의 공개 URL - 이미지 지원 사양 - 확장자: BMP, PNG, JPG, JPEG, WEBP - 크기: 20MB 미만 - 가로:세로 비율 1:5 또는 5:1 이하 - 장축(가로와 세로 중 긴 쪽) 길이: 2240px 이하 | | `dataUri` | Object | Conditional | 대화 메시지 내용 - 이미지 URL 입력 - 턴당 이미지 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 | 도구 목록의 토큰 수 계산 결과 | #### `ResponseFormatCount` `ResponseFormatCount`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `count` | Integer | Required | Structured Outputs의 토큰 수 계산 결과 | ### 응답 예시 응답 예시는 다음과 같습니다. #### 성공 호출이 성공한 경우의 응답 예시는 다음과 같습니다. ``` { "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 } } } ``` ``` { "status": { "code": "20000", "message": "OK" }, "result": { "messages": [ { "role": "system", "content": [ { "type": "text", "text": "- 미리 정의한 JSON Schema 형식에 맞춰 답변하는 AI 어시스턴트입니다.", "count": 18 } ] }, { "role": "user", "content": [ { "type": "text", "text": "오늘의 최고 기온은 32도, 최저 기온은 15도, 강수 확률은 30%입니다.", "count": 27 } ] } ], "responseFormat": { "count": 86 } } } ``` #### 실패 호출이 실패한 경우의 응답 예시는 다음과 같습니다. - [클라이언트 공통 오류 문제(4xx)](/docs/clovastudio-troubleshoot-c4xx) - [서버 공통 오류 문제(5xx)](/docs/clovastudio-troubleshoot-c5xx)