--- title: "Token calculator (chat v3)" slug: "clovastudio-tokenizerhcxv3" updated: 2026-09-17T09:35:47Z published: 2026-09-17T09:35:47Z canonical: "api.ncloud-docs.com/clovastudio-tokenizerhcxv3" --- > ## 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. # Token calculator (chat v3) Available in Classic and VPC Calculate number of tokens in sentences entered in the HCX model via Chat Completions V3. ## Request This section describes the request format. The method and URI are as follows: | Method | URI | | --- | --- | | POST | /v3/api-tools/chat-tokenize/{modelName} | ### Request headers For information about the headers common to all CLOVA Studio APIs, see [CLOVA Studio request headers](/docs/en/ai-naver-clovastudio-summary#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94). ### Request path parameters You can use the following path parameters with your request: | Field | Type | Required | Description | | --- | --- | --- | --- | | `modelName` | String | Required | Model name - Example: HCX-005 | ### Request body You can include the following data in the body of your request: | Field | Type | Required | Description | | --- | --- | --- | --- | | `messages` | Array | Required | List of conversation messages to count tokens: [messages](/docs/en/clovastudio-tokenizerhcxv3#messages1) | | `tools` | Array | Optional | List of tools available for `Function Calling`: [tools](/docs/en/clovastudio-tokenizerhcxv3#tools) | | `toolChoice` | String \| Object | Optional | `Function Calling` tool call behavior - `auto` : Model automatically calls tool (string). - `none` : Model generates normal answer without calling tool (string). - Model forces specific tool call (object). | | `toolChoice.type` | String | Optional | Tool type to be called by the `Function Calling` model | | `toolChoice.function` | Object | Optional | Tool to be called by the `Function Calling` model - `function` (valid value) | | `toolChoice.function.name` | String | Optional | Tool name to be called by the `Function Calling` model | | `responseFormat` | Object | Optional | Response format the model outputs | | `responseFormat.type` | String | Optional | Response format type - `json` (valid value) | | `responseFormat.schema` | Object | Optional | Response format schema - Schema that fits the response format type - JSON schema (object) (valid value) | #### `messages` The following describes `messages`. | Field | Type | Required | Description | | --- | --- | --- | --- | | `role` | Enum | Required | Role of conversation messages - `system` \| `user` \| `assistant` \| `tool` - `system`: Directives that define roles - `user`: User utterances/questions - `assistant`: Answers to user utterances/questions - `tool`: Enter the processing results according to `Function Calling`. | | `content` | String \| Array | Required | Conversation message content - Enter text (string). - Enter by composing text and image URLs (array): [content](/docs/en/clovastudio-tokenizerhcxv3#content) | | `toolCalls` | Array | Conditional | Assistant call tool information - If the role is a tool, enter as the assistant's [toolCalls](/docs/en/clovastudio-tokenizerhcxv3#toolCalls) request. | | `toolCallId` | String | Conditional | Tool ID - Required if role is tool - Used to connect to the assistant's [toolCalls](/docs/en/clovastudio-tokenizerhcxv3#toolCalls) request | #### `content` The following describes `content`. | Field | Type | Required | Description | | --- | --- | --- | --- | | `type` | Enum | Required | Format of conversation message content - `text` \| `image_url` - `text` : Text - `image_url` : Image URL | | `text` | String | Conditional | Conversation message content - Enter text. - Required if `type` is `text`. | | `imageUrl` | Object | Conditional | Image list - If `type` is `image_url`, `imageUrl` or `dataUri` must be entered. - One image per turn can be included. - Recommended to request with `text` for best results. | | `imageUrl.url` | String | Conditional | Public URL of a single image, including file extension - Supported image specifications. - Format: BMP, PNG, JPG, JPEG, WEBP - Size: Between 0 byte and 20 MB - Ratio: Horizontal and vertical dimensions of 1:5 or 5:1 or less - Length: The longer side (horizontal or vertical) must be 2240 px or less. The shorter side must be 4 px or more. | | `dataUri` | Object | Conditional | Image list - If `type` is `image_url`, `imageUrl` or `dataUri` must be entered. - One image per turn can be included. - Recommended to request with `text` for best results. | | `dataUri.data` | String | Conditional | Base64-encoded image string - Supported image specifications. - Format: BMP, PNG, JPG, JPEG, WEBP - Size: Between 0 byte and 20 MB - Ratio: Horizontal and vertical dimensions of 1:5 or 5:1 or less - Length: The longer side (horizontal or vertical) must be 2240 px or less. The shorter side must be 4 px or more. | #### `tools` The following describes `tools`. | Field | Type | Required | Description | | --- | --- | --- | --- | | `type` | String | Required | Tool type - `function` (valid value) | | `function` | Object | Required | Call `function` information | | `function.name` | String | Required | `function` name | | `function.description` | String | Required | `function` description | | `function.parameters` | Object | Required | Parameter passed when using `function` - properties, required - Entry: See [Request example](/docs/en/clovastudio-tokenizerhcxv3#%EC%9A%94%EC%B2%AD%EC%98%88%EC%8B%9C). - Format: See [JSON Schema reference](https://json-schema.org/understanding-json-schema/reference). | #### `toolCalls` The following describes `toolCalls`. | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | String | - | Tool identifier | | `type` | String | - | Tool type - `function` (valid value) | | `function` | Object | - | Call `function` information | | `function.name` | String | - | `function` name | | `function.arguments` | Object | - | Parameter passed when using `function` | ### Request example The request example is as follows: #### When querying with image The following is a sample request when querying by image. ``` 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": "- This is a friendly AI assistant." }, { "role": "user", "content": [ { "type": "image_url", "imageUrl": [ { "url": "https://www.******.com/image_a1b1c1.png" } ] }, { "type": "text", "text": "Please describe this photo." } ] }, { "role": "assistant", "content": "The photo shows a young child feeding a sheep." } ] }' ``` #### When querying with text The following is a sample request when querying by text. ``` 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": "What will the weather be like in Seoul tomorrow?", "role":"user" } ], "tools":[ { "type":"function", "function":{ "description": "Tool that can provide weather information", "name":"weather", "parameters":{ "properties":{ "location":{ "description": "City names such as Seoul, Daejeon, and Busan", "type":"string" }, "unit":{ "enum":[ "celsius", "fahrenheit" ], "type":"string" }, "date":{ "description": "Date string in the format such as 2023-08-01. Date you want to know the weather for", "type":"string" } }, "required":[ "location" ], "type":"object" } } }, { "type":"function", "function":{ "description": "Tool that recommends travel destinations", "name":"travel", "parameters":{ "properties":{ "location":{ "description":"The city and state, e.g. San Francisco, CA", "type":"string" }, "date":{ "description": "Date string in the format such as \"2023-08-01~2023-09-01\". Travel date range", "type":"string" } }, "required":[ "location" ], "type":"object" } } } ], "toolChoice":"auto" }' ``` #### When querying with Structured Outputs The following is a sample request when querying with 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": "- An AI assistant that responds to a predefined JSON schema format." }, { "role": "user", "content": "Today's high is 32 degrees, the low is 15 degrees, and there is a 30% chance of precipitation." } ], "responseFormat": { "type" : "json", "schema": { "type": "object", "properties": { "temp_high_c": { "type": "number", "description": "Highest temperature (Celsius)" }, "temp_low_c": { "type": "number", "description": "Lowest temperature (Celsius)" }, "precipitation_percent": { "type": "number", "description": "Precipitation probability (%)", "minimum": 0, "maximum": 100 } }, "required": [ "temp_high_c", "temp_low_c", "precipitation_percent" ] } } }' ``` ## Response This section describes the response format. ### Response body The response body includes the following data: | Field | Type | Required | Description | | --- | --- | --- | --- | | `status` | Object | - | See [Response status](/docs/en/ai-naver-clovastudio-summary#%EC%9D%91%EB%8B%B5). | | `result` | Object | - | Response result | | `result.messages` | Array | - | List of request conversation messages with counted tokens: [messages](/docs/en/clovastudio-tokenizerhcxv3#messages2) | | `result.tools` | Object | - | List of request conversation messages with counted tokens: [ToolCount](/docs/en/clovastudio-tokenizerhcxv3#ToolCount) | | `result.responseFormat` | Object | - | Structured Outputs token calculation result: [ResponseFormatCount](/docs/en/clovastudio-tokenizerhcxv3#ResponseFormatCount) | #### `messages` The following describes `messages`. | Field | Type | Required | Description | | --- | --- | --- | --- | | `role` | Enum | - | Role of conversation messages - `system` \| `user` \| `assistant` \| `tool` - `system`: Directives that define roles - `user`: User utterances/questions - `assistant`: Answers of the model - `tool`: Enter the processing results according to `Function Calling` | | `content` | Object | - | Message content token calculation result: [ChatMessageCount](/docs/en/clovastudio-tokenizerhcxv3#ChatMessageCount) | #### `ChatMessageCount` The following describes `ChatMessageCount`. | Field | Type | Required | Description | | --- | --- | --- | --- | | `type` | Enum | Required | Format of conversation message content - `text` \| `image_url` - `text` : Text - `image_url` : Image URL | | `text` | String | Conditional | Conversation message content - Enter text. | | `imageUrl` | Object | Conditional | Conversation message content - Enter the image URL. - If `type` is `image_url`, either 'imageUrl' or 'dataUri' must be entered. - One image can be included per turn. - For optimal results, we recommend requesting it with `text`. | | `imageUrl.url` | String | Conditional | Public URL of a single image, including file extension - Supported image specifications - Extension: BMP, PNG, JPG, JPEG, WEBP - Size: Under 20 MB - Horizontal:vertical ratio of 1:5 or 5:1 or less - Long axis (longer of the horizontal and vertical sides) length: 2240 px or less | | `dataUri` | Object | Conditional | Conversation message content - Enter the image URL. - If `type` is `image_url`, either 'imageUrl' or 'dataUri' must be entered. - One image can be included per turn. - For optimal results, we recommend requesting it with `text`. | | `dataUri.data` | String | Conditional | Base64-encoded image string - Supported image specifications - Extension: BMP, PNG, JPG, JPEG, WEBP - Size: Up to 20 MB - Horizontal:vertical ratio of 1:5 or 5:1 or less - Long axis (longer of the horizontal and vertical sides) length: 2240 px or less, shorter side must be 4 px or more | | `count` | Integer | Required | Token count calculation results by conversation message content | #### `ToolCount` The following describes `ToolCount`. | Field | Type | Required | Description | | --- | --- | --- | --- | | `count` | Integer | Required | Tool list token count calculation result | #### `ResponseFormatCount` The following describes `ResponseFormatCount`. | Field | Type | Required | Description | | --- | --- | --- | --- | | `count` | Integer | Required | Result of token count calculation in Structured Outputs | ### Response example The response example is as follows: #### Succeeded The following is a sample response upon a successful call. ``` { "status": { "code": "20000", "message": "OK" }, "result": { "messages": [ { "role": "system", "content": { "type": "text", "text": "- This is a friendly AI assistant.", "count": 16 } }, { "role": "user", "content": [ { "type": "image_url", "imageUrl": { "url": "https://www.******.com/image_a1b1c1.png" }, "count": 1478 }, { "type": "text", "text": "Please describe this photo.", "count": 12 } ] }, { "role": "assistant", "content": [ { "type": "text", "text": "The photo shows a young child feeding a sheep.", "count": 20 } ] } ] } } ``` ``` { "status": { "code": "20000", "message": "OK" }, "result": { "messages": [ { "role": "user", "content": [ { "type": "text", "text": "What will the weather be like in Seoul tomorrow?", "count": 12 } ] } ], "tools": { "count": 230 } } } ``` ``` { "status": { "code": "20000", "message": "OK" }, "result": { "messages": [ { "role": "system", "content": [ { "type": "text", "text": "- An AI assistant that responds to a predefined JSON schema format.", "count": 18 } ] }, { "role": "user", "content": [ { "type": "text", "text": "Today's high is 32 degrees, the low is 15 degrees, and there is a 30% chance of precipitation.", "count": 27 } ] } ], "responseFormat": { "count": 86 } } } ``` #### Failure The following is a sample response upon a failed call. - [Common client error troubleshooting (4xx)](/docs/en/clovastudio-troubleshoot-c4xx) - [Common server error troubleshooting (5xx)](/docs/en/clovastudio-troubleshoot-c5xx)