--- title: "Function calling" slug: "clovastudio-chatcompletionsv3-fc" updated: 2026-09-17T09:57:20Z published: 2026-09-17T09:57:20Z canonical: "api.ncloud-docs.com/clovastudio-chatcompletionsv3-fc" --- > ## 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. # Function calling Classic/VPC環境で利用できます。 Function callingをサポートして、外部関数や APIを呼び出して動的に情報を取得したり、操作を実行することができる v3 Chat Completionsを説明します。 ## リクエスト リクエスト形式を説明します。リクエスト形式は次の通りです。 | メソッド | URI | | --- | --- | | POST | /v3/chat-completions/{modelName} | 参考 HyperCLOVA X Function callingは、Chat Completions v3、オープン AI互換 APIでのみ使用可能で、チューニングモデルは対応しません。 ### リクエストヘッダ CLOVA Studio APIで共通して使用されるヘッダの詳細は、[CLOVA Studioのリクエストヘッダ](/docs/ja/ai-naver-clovastudio-summary#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94)をご参照ください。 ### リクエストパスパラメータ リクエストパスパラメータの説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `modelName` | Enum | Required | モデル名 - <例> `HCX-005` | ### リクエストボディ リクエストボディの説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `messages` | Array | Required | 会話メッセージ: [messages](/docs/ja/clovastudio-chatcompletionsv3-fc#messages) | | `topP` | Double | Optional | 生成トークン候補群を累積確率に基づいてサンプリング - 0.00 ＜ `topP` ≤ 1.00 (デフォルト: 0.8) - 最終テキストレスポンスを返す際にのみ適用 (会話メッセージの`role`が`tool`の場合) | | `topK` | Integer | Optional | 生成トークン候補群から確率の高いトークン K個を候補に指定してサンプリング - 0 ≤ `topK` ≤ 128 (デフォルト: 0) - 最終テキストレスポンスを返す際にのみ適用 (会話メッセージの`role`が`tool`の場合) | | `maxTokens` | Integer | Optional | 最大トークン生成数 - 1024≤ `maxTokens` ≤ モデルの最大値 - `maxCompletionTokens`と同時に使用不可 | | `maxCompletionTokens` | Integer | Optional | 最大トークン生成数 (推論モデル) - 1024≤ `maxCompletionTokens` ≤ モデルの最大値 - `maxTokens`と同時に使用不可 | | `temperature` | Double | Optional | 生成トークンに対する多様性の程度(設定値が高いほど多様な文章を生成) - 0.00 ≤ `temperature` ≤ 1.00 (デフォルト: 0.5) - 最終テキストレスポンスを返す際にのみ適用 (会話メッセージの`role`が`tool`の場合) | | `repetitionPenalty` | Double | Optional | 同じトークンを生成することに対するペナルティの程度 - 0.0 ＜ `repetitionPenalty` ≤ 2.0 (デフォルト: 1.1) - 設定値が高いほど同じ結果値を繰り返し生成する確率は下がる - 1.0~1.1の範囲内で0.05単位での微調整を推奨 - 最終テキストレスポンスを返す際にのみ適用 (会話メッセージの`role`が`tool`の場合) | | `stop` | Array | Optional | トークン生成停止文字 - [](デフォルト) - 最終テキストレスポンスを返す際にのみ適用 (会話メッセージの`role`が`tool`の場合) | | `thinking` | Object | Optional | 推論モデルの設定情報 | | `thinking.effort` | String | Optional | 推論の有無と思考の深さを設定 - `none` (有効値) - Function callingと同時に使用不可 | | `tools` | Array | Optional | `Function calling`の使用可能なツールリスト: [tools](/docs/ja/clovastudio-chatcompletionsv3-fc#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`モデルが呼び出すツール名 | #### `messages` `messages`の説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `role` | Enum | Required | 会話メッセージのロール - `system` \| `user` \| `assistant` \| `tool` - `system`: ロールを規定する指示文 - `user`: ユーザーの発話または質問 - `assistant`: ユーザーの発話または質問に対する回答 - `tool`: assistant(モデル)が呼び出した関数の実行結果 | | `content` | String | Required | 会話メッセージ内容 - テキスト入力(String) | | `toolCalls` | Array | Conditional | assistantの呼び出しツール情報 `role`が`tool`の場合、assistantの[toolCalls](/docs/ja/clovastudio-chatcompletionsv3-fc#toolCalls)リクエストのように入力 | | `toolCallId` | String | Conditional | ツール ID - `role`が`tool`の場合、必ず入力 - assistantの[toolCalls](/docs/ja/clovastudio-chatcompletionsv3-fc#toolCalls)リクエストと関連付ける用途 | #### `tools` `tools`の説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `type` | String | Required | ツールのタイプ - `function`(有効値) | | `function` | Object | Required | 呼び出し`function`情報 | | `function.name` | String | Required | `function`名 | | `function.description` | String | Required | `function`の説明 | | `function.parameters` | Object | Optional | `function`使用時に渡されるパラメータ - `properties`、`required` - 入力: [動作方法](/docs/ja/clovastudio-chatcompletionsv3-fc#%EB%8F%99%EC%9E%91%EB%B0%A9%EC%8B%9D)を参照 - 形式: [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`使用時に渡されるパラメータ | 参考 一部フィールドの入力時、下記の内容をご確認ください。 - `role`: `system`の[会話メッセージ](/docs/ja/clovastudio-chatcompletionsv3-fc#messages)は、リクエストごとに1つだけ含めることができます。 - Function callingは、推論または画像解析と同時にリクエストできません。 - Function callingは、結果の生成時に使用する最大トークン数(`maxTokens`または`maxCompletionTokens`)を1024以上に設定してください。 ## レスポンス レスポンス形式を説明します。 ### レスポンスヘッダ レスポンスヘッダの説明は次の通りです。 | ヘッダ | 必須の有無 | 説明 | | --- | --- | --- | | `Content-Type` | - | レスポンスデータの形式 - `application/json` | ### レスポンスボディ レスポンスボディの説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `status` | Object | - | [レスポンスの状態](/docs/ja/ai-naver-clovastudio-summary#%EC%9D%91%EB%8B%B5)を参照 | | `result` | Object | - | レスポンス結果 | | `result.created` | Integer | - | レスポンスの日付 - Unix timestamp miliseconds形式 | | `result.usage` | Object | - | トークン使用量 | | `result.usage.completionTokens` | Integer | - | 生成トークン数 | | `result.usage.promptTokens` | Integer | - | 入力(プロンプト)トークン数 | | `result.usage.totalTokens` | Integer | - | トークンの総数 - 生成トークン数+入力トークン数 | | `result.message` | Object | - | 会話メッセージ | | `result.message.role` | Enum | - | 会話メッセージのロール - `system` \| `user` \| `assistant` - `system`: ロールを規定する指示文 - `user`: ユーザーの発話または質問 - `assistant`: モデルの回答 | | `result.message.content` | String | - | 会話メッセージの内容 | | `result.message.toolCalls` | Array | - | [toolCalls](/docs/ja/clovastudio-chatcompletionsv3-fc#toolCalls_response) | | `result.finishReason` | String | - | トークン生成停止の理由(通常、最後のイベントで渡す) - `length` \| `stop`\| `tool_calls` - `length`: 長さ制限 - `stop`: 回答生成中に`stop`に指定した文字が登場 - `tool_calls`: モデルが正常にツール呼び出しを完了 | | `result.seed` | Integer | - | 入力 seed値(0を入力したか、未入力の場合はランダムな値を返す) | #### `toolCalls` `toolCalls`の説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `id` | String | - | ツール識別子 | | `type` | String | - | ツールのタイプ - `function`(有効値) | | `function` | Object | - | 呼び出し`function`情報 | | `function.name` | String | - | `function`名 | | `function.arguments` | Object | - | `function`使用時に渡されるパラメータ | ## レスポンスストリーム 生成されるトークンを1つずつ出力するようにトークンストリーミングを使用できます。トークンストリーミング形式を説明します。 ### レスポンスヘッダ レスポンスヘッダの説明は次の通りです。 | ヘッダ | 必須の有無 | 説明 | | --- | --- | --- | | `Accept` | - | レスポンスデータの形式 - `text/event-stream` | ### レスポンスボディ レスポンスボディの説明は次の通りです。 #### StreamingChatCompletionsTokenEvent `StreamingChatCompletionsTokenEvent`の説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `created` | Integer | - | レスポンスタイムのタイムスタンプ | | `usage` | Object | - | トークン使用量 | | `usage.promptTokens` | Integer | - | 入力(プロンプト)トークン数 | | `usage.completionTokens` | Integer | - | 生成トークン数 | | `message` | Object | - | 会話メッセージ | | `message.role` | Enum | - | 会話メッセージのロール - `user` \| `assistant` - `user`: ユーザーの発話または質問 - `assistant`: モデルの回答 | | `message.content` | String | - | 会話メッセージの内容 | | `message.toolCalls` | Array | - | [toolCalls](/docs/ja/clovastudio-chatcompletionsv3-fc#toolCalls_streaming) | | `finishReason` | String | - | トークン生成停止の理由(通常、最後のイベントで渡す) - `length` \| `stop` - `length`: 長さ制限 - `stop`: 回答生成中に`stop`に指定した文字が登場 | #### `toolCalls` `StreamingChatCompletionsTokenEvent`での`toolCalls`の説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `id` | String | - | ツール識別子 | | `type` | String | - | ツールのタイプ - `function`(有効値) | | `function` | Object | - | 呼び出し`function`情報 | | `function.name` | String | - | `function`名 | | `function.partialJson` | String | - | `function`に渡す JSON引数を構成する文字列の一部 | #### StreamingChatCompletionsResultEvent `StreamingChatCompletionsResultEvent`の説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `created` | Integer | - | レスポンスタイムのタイムスタンプ | | `usage` | Object | - | トークン使用量 | | `usage.promptTokens` | Integer | - | 入力(プロンプト)トークン数 | | `usage.completionTokens` | Integer | - | 生成トークン数 | | `usage.totalTokens` | Integer | - | トークンの総数 - 生成トークン数+入力トークン数 | | `message` | Object | - | 会話メッセージ | | `message.role` | Enum | - | 会話メッセージのロール - `user` \| `assistant` - `user`: ユーザーの発話または質問 - `assistant`: モデルの回答 | | `message.content` | String | - | 会話メッセージの内容 | | `message.toolCalls` | Array | - | [toolCalls](/docs/ja/clovastudio-chatcompletionsv3-fc#toolCalls) | | `finishReason` | String | - | トークン生成停止の理由(通常、最後のイベントで渡す) - `length` \| `stop` - `length`: 長さ制限 - `stop`: 回答生成中に`stop`に指定した文字が登場 - `tool_calls`: モデルが正常にツール呼び出しを完了 | #### ErrorEvent `ErrorEvent`の説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `status` | Object | - | [レスポンスの状態](/docs/ja/ai-naver-clovastudio-summary#%EC%9D%91%EB%8B%B5)を参照 | | `status.code` | Object | - | レスポンスステータスコード - [CLOVA Studioのトラブルシューティング](/docs/ja/clovastudio-troubleshoot)を参照 | | `status.message` | Object | - | レスポンスステータスメッセージ - [CLOVA Studioのトラブルシューティング](/docs/ja/clovastudio-troubleshoot)を参照 | #### SignalEvent `SignalEvent`の説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `data` | String | - | 渡すシグナルデータ情報 | ### レスポンス例 レスポンスのサンプルコードは次の通りです。 #### 成功 呼び出しに成功した場合のレスポンスのサンプルコードは次の通りです。 ``` id:ef40438b-d49a-4fff-9335-a19e5abfcff1 event:token data:{"message":{"role":"assistant","content":"","toolCalls":[{"id":"call_zumbHGLfLwV3xn0Rn2gSPqfz","type":"function","function":{"name":"get_weather"}}]},"finishReason":null,"created":1749810707,"seed":1775609431,"usage":null} id:75cae060-e19b-4a82-9106-81b784dcde51 event:token data:{"message":{"role":"assistant","content":"","toolCalls":[{"type":"function","function":{"partialJson":"{\""}}]},"finishReason":null,"created":1749810707,"seed":1775609431,"usage":null} id:d29c7e43-d8ed-43f1-8265-6e5fa91b4b65 event:token data:{"message":{"role":"assistant","content":"","toolCalls":[{"type":"function","function":{"partialJson":"location"}}]},"finishReason":null,"created":1749810707,"seed":1775609431,"usage":null} id:700f5c00-07b3-4bcc-892d-00913d22ad9f event:token data:{"message":{"role":"assistant","content":"","toolCalls":[{"type":"function","function":{"partialJson":"\":"}}]},"finishReason":null,"created":1749810707,"seed":1775609431,"usage":null} id:0c3e3439-699d-400a-af23-29a09eab28f3 event:token data:{"message":{"role":"assistant","content":"","toolCalls":[{"type":"function","function":{"partialJson":" \""}}]},"finishReason":null,"created":1749810707,"seed":1775609431,"usage":null} id:b7506691-ffb0-4e23-a068-ce50013920de event:token data:{"message":{"role":"assistant","content":"","toolCalls":[{"type":"function","function":{"partialJson":"ソウル"}}]},"finishReason":null,"created":1749810707,"seed":1775609431,"usage":null} id:7c26e5c8-d75e-4e33-8185-1877c9c2c8d7 event:token data:{"message":{"role":"assistant","content":"","toolCalls":[{"type":"function","function":{"partialJson":"\","}}]},"finishReason":null,"created":1749810707,"seed":1775609431,"usage":null} ... id:f32289bd-0b94-4733-9df2-9f1a3eee48a6 event:result data:{"message":{"role":"assistant","content":"","toolCalls":[{"id":"call_zumbHGLfLwV3xn0Rn2gSPqfz","type":"function","function":{"name":"get_weather","arguments":{"location":"ソウル","unit":"celsius","date":"2025-06-13"}}}]},"finishReason":"tool_calls","created":1749810707,"seed":1775609431,"usage":{"promptTokens":9,"completionTokens":47,"totalTokens":56}} ``` #### 失敗 呼び出しに失敗した場合のレスポンスのサンプルコードは次の通りです。 - [クライアント共通エラー問題(4xx)](/docs/ja/clovastudio-troubleshoot-c4xx) - [サーバ共通エラー問題(5xx)](/docs/ja/clovastudio-troubleshoot-c5xx) ## 動作方式 リクエストとレスポンスを含む Function callingの動作方法は次の通りです。 ### Step 1. 入力と関数の定義を渡す クエリ内容を入力し、関数の定義を渡します。リクエストのサンプルコードは次の通りです。 - cURL ``` curl --location --request POST 'https://clovastudio.stream.ntruss.com/v3/chat-completions/{modelName}' \ --header 'Authorization: Bearer ' \ --header 'X-NCP-CLOVASTUDIO-REQUEST-ID: {Request ID}' --header 'Content-Type: application/json' \ --data '{ "messages" : [ { "content" : "今日のソウルの天気を教えて", "role" : "user" } ], "tools" : [ { "function" : { "description" : "天気を教えてくれるツール", "name" : "get_weather", "parameters" : { "properties" : { "location" : { "description" : "ソウル、大田、釜山などの都市名", "type" : "string" }, "unit" : { "enum" : [ "celsius", "fahrenheit" ], "type" : "string" }, "date" : { "description" : "2023-08-01のような日付形式の文字列。天気が知りたい日付", "type" : "string" } }, "required" : [ "location" ], "type" : "object" } } }], "toolChoice" : "auto" }' ``` - Python ``` import requests API_KEY = "YOUR_API_KEY" REQUEST_ID = "YOUR_REQUEST_ID" url = "https://clovastudio.stream.ntruss.com/v3/chat-completions/{modelName}" headers = { "Authorization": f"Bearer {API_KEY}", "X-NCP-CLOVASTUDIO-REQUEST-ID": REQUEST_ID, "Content-Type": "application/json" } data = { "messages": [ { "content": "明日のソウルの天気はどう?", "role": "user" } ], "tools": [ { "type": "function", "function": { "description": "天気を教えてくれるツール", "name": "get_weather", "parameters": { "type": "object", "properties": { "location": { "description": "ソウル、大田、釜山などの都市名", "type": "string" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }, "date": { "description": "2025-03-21のような日付形式の文字列。天気が知りたい日付", "type": "string" } }, "required": ["location"] } } } ], "toolChoice": "auto" } response = requests.post(url, headers=headers, json=data) result = response.json() print(result) ``` ### Step 2. 呼び出す関数と引数を返す 呼び出す関数と引数情報が返されます。レスポンスのサンプルコードは次の通りです。 ``` { "status": { "code": "20000", "message": "OK" }, "result": { "message": { "role": "assistant", "content": "", "toolCalls": [ { "id": "call_s83AKVWrPPI6bCTLl5kFGtyo", "type": "function", "function": { "name": "get_weather", "arguments": { "location": "ソウル", "unit": "celsius", "date": "2025-04-10" } } } ] }, "finishReason": "tool_calls", "created": 1744218663, "seed": 1354242582, "usage": { "promptTokens": 134, "completionTokens": 48, "totalTokens": 315 } } } ``` ### Step 3. レスポンス結果に基づいて実際の関数を呼び出す Step 2.のレスポンス結果に基づいて実際の関数を呼び出します。リクエストのサンプルコードは次の通りです。 - cURL ``` # <例> 次のような APIを呼び出すとします。 # GET https://weather.example.com?location=ソウル&unit=celsius&date=2025-04-10 curl --request GET 'https://weather.example.com?location=ソウル&unit=celsius&date=2025-04-10 ``` - Python ``` """ <例> 次のような関数を構成したとします。 def get_weather(location, unit="celsius", date=None): response = requests.get(f"https://weather.example.com?location={location}&unit={unit}&date={date}") data = response.json() return data """ tool_call = result["result"]["message"]["toolCalls"][0] function_name = tool_call["function"]["name"] arguments = tool_call["function"]["arguments"] if function_name == "get_weather": function_result = get_weather(**arguments) ``` レスポンスのサンプルコードは次の通りです。 ``` { "location": "ソウル", "temperature": "17度", "condition": "晴れ" } ``` ### Step 4. 関数の実行結果を渡す 関数の実行結果を渡します。リクエストのサンプルコードは次の通りです。 - cURL ``` curl --location --request POST 'https://clovastudio.stream.ntruss.com/v3/chat-completions/{modelName}' \ --header 'Authorization: Bearer ' \ --header 'X-NCP-CLOVASTUDIO-REQUEST-ID: {Request ID}' --header 'Content-Type: application/json' \ --data '{ "messages": [ { "role": "user", "content": "明日のソウルの天気はどう?" }, { "role": "assistant", "content": "", "toolCalls": [ { "id": "call_s83AKVWrPPI6bCTLl5kFGtyo", "type": "function", "function": { "name": "get_weather", "arguments": { "location": "ソウル", "unit": "celsius", "date": "2025-04-10" } } } ] }, { "role": "tool", "toolCallId": "call_s83AKVWrPPI6bCTLl5kFGtyo", "content": "{ \"location\": \"ソウル\", \"temperature\": \"17度\", \"condition\": \"晴れ\" }" } ], "seed": 0, "topP": 0.8, "topK": 0, "maxTokens": 1024, "temperature": 0, "repeatPenalty": 1.1, "stopBefore": [] }' ``` - Python ``` url = "https://clovastudio.stream.ntruss.com/v3/chat-completions/{modelName}" headers = { "Authorization": f"Bearer {API_KEY}", "X-NCP-CLOVASTUDIO-REQUEST-ID": REQUEST_ID, "Content-Type": "application/json" } data = { "messages": [ { "role": "user", "content": "明日のソウルの天気はどう?" }, { "role": "assistant", "content": "", "toolCalls": [ { "id": "call_s83AKVWrPPI6bCTLl5kFGtyo", "type": "function", "function": { "name": "get_weather", "arguments": { "location": "ソウル", "unit": "celsius", "date": "2025-04-10" } } } ] }, { "role": "tool", "toolCallId": "call_s83AKVWrPPI6bCTLl5kFGtyo", "content": str(function_result) } ], "seed": 0, "topP": 0.8, "topK": 0, "maxTokens": 1024, "temperature": 0, "repeatPenalty": 1.1, "stopBefore": [] } response = requests.post(url, headers=headers, json=data) result = response.json() print(result) ``` ### Step 5. 最終テキストレスポンスを返す 最終的に返されたレスポンス結果のテキストを確認します。 ``` { "status": { "code": "20000", "message": "OK" }, "result": { "message": { "role": "assistant", "content": "明日のソウルの天気は晴れ、気温は約17度と予想されます。暖かな春の陽気になりそうなので、お出かけ日和になりそうですね!" }, "finishReason": "stop", "created": 1744218776, "seed": 2744409319, "usage": { "promptTokens": 88, "completionTokens": 37, "totalTokens": 125 } } } ```