--- title: "トークン計算機(チャット v3)" slug: "clovastudio-tokenizerhcxv3" updated: 2026-09-17T09:57:20Z published: 2026-09-17T09:57:20Z 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. # トークン計算機(チャット v3) Classic/VPC環境で利用できます。 Chat Completions V3で HCXモデルに入力した文章のトークン数を計算します。 ## リクエスト リクエスト形式を説明します。リクエスト形式は次の通りです。 | メソッド | URI | | --- | --- | | POST | /v3/api-tools/chat-tokenize/{modelName} | ### リクエストヘッダ CLOVA Studio APIで共通して使用されるヘッダの詳細は、[CLOVA Studioのリクエストヘッダ](/docs/ja/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/ja/clovastudio-tokenizerhcxv3#messages1) | | `tools` | Array | Optional | `Function Calling`の使用可能なツールリスト: [tools](/docs/ja/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/ja/clovastudio-tokenizerhcxv3#content) | | `toolCalls` | Array | Conditional | assistantの呼び出しツール情報 - roleが toolの場合、assistantの[toolCalls](/docs/ja/clovastudio-tokenizerhcxv3#toolCalls)リクエストのように入力 | | `toolCallId` | String | Conditional | ツール ID - roleが toolの場合、必ず入力 - assistantの[toolCalls](/docs/ja/clovastudio-tokenizerhcxv3#toolCalls)リクエストと関連付ける用途 | #### `content` `content`の説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `type` | Enum | Required | 会話メッセージ内容の形式 - `text` \| `image_url` - `text`: テキスト - `image_url`: 画像 URL | | `text` | String | Conditional | 会話メッセージ内容 - テキスト入力 | | `imageUrl` | Object | Conditional | 画像リスト - `type`が`image_url`の場合、`imageUrl`と`dataUri`のうち1つは必ず入力 - ターンごとに画像は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つは必ず入力 - ターンごとに画像は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/ja/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/ja/ai-naver-clovastudio-summary#%EC%9D%91%EB%8B%B5)を参照 | | `result` | Object | - | レスポンス結果 | | `result.messages` | Array | - | トークン数が計算されたリクエスト会話メッセージリスト: [messages](/docs/ja/clovastudio-tokenizerhcxv3#messages2) | | `result.tools` | Object | - | トークン数が計算されたリクエストツールリスト: [ToolCount](/docs/ja/clovastudio-tokenizerhcxv3#ToolCount) | | `result.responseFormat` | Object | - | Structured Outputsのトークン計算結果: [ResponseFormatCount](/docs/ja/clovastudio-tokenizerhcxv3#ResponseFormatCount) | #### `messages` The following describes `messages`. | Field | Type | Required | Description | | --- | --- | --- | --- | | `ChatMessages.role` | Enum | - | 会話メッセージのロール - `system` \| `user` \| `assistant` \| `tool` - `system`: ロールを規定する指示文 - `user`: ユーザーの発話または質問 - `assistant`: モデルの返答 - `tool`: `Function Calling`による処理結果を入力 | | `ChatMessage.content` | Object | - | メッセージ内容のトークン計算結果: [ChatMessage](/docs/ja/clovastudio-tokenizerhcxv3#ChatMessageCount) | #### `ChatMessageCount` `ChatMessageCount`の説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `type` | Enum | Required | 会話メッセージ内容の形式 - `text` \| `image_url` - `text`: テキスト - `image_url`: 画像 URL | | `text` | String | Conditional | 会話メッセージ内容 - テキスト入力 - `type`が`text`の場合、必ず入力 | | `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/ja/clovastudio-troubleshoot-c4xx) - [サーバ共通エラー問題(5xx)](/docs/ja/clovastudio-troubleshoot-c5xx)