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でのみ使用可能で、チューニングモデルは対応しません。

リクエストヘッダ

リクエストヘッダの説明は次の通りです。

ヘッダ	必須の有無	説明
`Authorization`	Required	認証用 APIキー<例> `Bearer nv-************`
`X-NCP-CLOVASTUDIO-REQUEST-ID`	Optional	リクエスト ID
`Content-Type`	Required	リクエストデータの形式 `application/json`
`Accept`	Conditional	レスポンスデータの形式 `text/event-stream`

参考

レスポンス結果は基本的に JSON形式で返されますが、Acceptをtext/event-streamに指定するとレスポンス結果をストリーム形式で返します。

リクエストパスパラメータ

リクエストパスパラメータの説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`modelName`	Enum	Required	モデル名 <例> `HCX-005`

リクエストボディ

リクエストボディの説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`messages`	Array	Required	会話メッセージ
`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) 最終テキストレスポンスを返す際にのみ適用 (会話メッセージの`role`が`tool`の場合)
`stop`	Array	Optional	トークン生成停止文字 [](デフォルト) 最終テキストレスポンスを返す際にのみ適用 (会話メッセージの`role`が`tool`の場合)
`thinking`	Object	Optional	推論モデルの設定情報
`thinking.effort`	String	Optional	推論の有無と思考の深さを設定 `none` (有効値) Function callingと同時に使用不可
`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`モデルが呼び出すツール名

`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リクエストのように入力
`toolCallId`	String	Conditional	ツール ID `role`が`tool`の場合、必ず入力 assistantのtoolCallsリクエストと関連付ける用途

`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` 入力: 動作方法を参照形式: JSON Schema referenceを参照

`toolCalls`

toolCallsの説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`id`	String	-	ツール識別子
`type`	String	-	ツールのタイプ `function`(有効値)
`function`	Object	-	呼び出し`function`情報
`function.name`	String	-	`function`名
`function.arguments`	Object	-	`function`使用時に渡されるパラメータ

参考

一部フィールドの入力時、下記の内容をご確認ください。

role: systemの会話メッセージは、リクエストごとに1つだけ含めることができます。
Function callingは、推論または画像解析と同時にリクエストできません。
Function callingは、結果の生成時に使用する最大トークン数(maxTokensまたはmaxCompletionTokens)を1024以上に設定してください。

レスポンス

レスポンス形式を説明します。

レスポンスヘッダ

レスポンスヘッダの説明は次の通りです。

ヘッダ	必須の有無	説明
`Content-Type`	-	レスポンスデータの形式 `application/json`

レスポンスボディ

レスポンスボディの説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`status`	Object	-	レスポンスステータス
`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
`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
`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
`finishReason`	String	-	トークン生成停止の理由(通常、最後のイベントで渡す) `length` \| `stop` `length`: 長さ制限 `stop`: 回答生成中に`stop`に指定した文字が登場 `tool_calls`: モデルが正常にツール呼び出しを完了

ErrorEvent

ErrorEventの説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`status`	Object	-	レスポンスステータス
`status.code`	Object	-	レスポンスステータスコード CLOVA Studioのトラブルシューティングを参照
`status.message`	Object	-	レスポンスステータスメッセージ CLOVA Studioのトラブルシューティングを参照

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}}

失敗

呼び出しに失敗した場合のレスポンスのサンプルコードは次の通りです。

動作方式

リクエストとレスポンスを含む Function callingの動作方法は次の通りです。

Step 1. 入力と関数の定義を渡す

クエリ内容を入力し、関数の定義を渡します。リクエストのサンプルコードは次の通りです。

cURL

curl --location --request POST 'https://clovastudio.stream.ntruss.com/v3/chat-completions/{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" : [ {
    "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 <api-key>' \
--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
        }
    }
}