Function calling

Prev Next

Available in Classic and VPC

This guide describes Chat Completions v3, which supports function calling, allowing you to dynamically get information or perform actions through external functions or API calls.

Request

This section describes the request format. The method and URI are as follows:

Method URI
POST /v3/chat-completions/{modelName}
Note

HyperCLOVA X function calling is only available for Chat Completions v3 and OpenAI compatible APIs, and is not supported for tuning models.

Request headers

The following describes the request headers.

Headers Required Description
Authorization Required API key for authentication Example: Bearer nv-************
X-NCP-CLOVASTUDIO-REQUEST-ID Optional Request ID for the request
Content-Type Required Request data format
  • application/json
Accept Conditional Response data format
  • text/event-stream
Note

Response results are returned in JSON by default, but if you specify Accept as text/event-stream, then the response results are returned as a stream.

Request path parameters

You can use the following path parameters with your request:

Field Type Required Description
modelName Enum 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 Conversation messages
topP Double Optional Sample generation token candidates based on cumulative probability.
  • 0.00 ＜ topP ≤ 1.00 (default: 0.8)
  • Apply only when returning the final text response (if the role of the conversation message is tool).
topK Integer Optional Sample K candidates with high probabilities from the generation token candidates.
  • 0 ≤ topK ≤ 128 (default: 0)
  • Apply only when returning the final text response (if the role of the conversation message is tool).
maxTokens Integer Optional Maximum number of generated tokens
  • 1024 ≤ maxTokens ≤ model maximum value
  • Can't be used concurrently with maxCompletionTokens.
    		•
    maxCompletionTokens Integer Optional Maximum number of generated tokens (inference model)
    • 1024 ≤ maxCompletionTokens ≤ model maximum value
    • Can't be used concurrently with maxTokens.
    temperature Double Optional Diversity of generated tokens (the higher the value, the more diverse the sentences generated)
    • 0.00 ≤ temperature ≤ 1.00 (default: 0.5)
    • Apply only when returning the final text response (if the role of the conversation message is tool).
    repetitionPenalty Double Optional Penalty for generating the same token (the higher the setting value, the lower the probability of repeatedly generating the same result)
    • 0.0 ＜ repetitionPenalty ≤ 2.0 (default: 1.1)
    • Apply only when returning the final text response (if the role of the conversation message is tool).
    stop Array Optional Token generation stop character
    • [] (default)
    • Apply only when returning the final text response (if the role of the conversation message is tool).
    thinking Object Optional Inference model configuration information
    thinking.effort String Optional Set whether to infer and the depth of the thought process
    • none (valid value)
    • Can't be used concurrently with function calling.
    tools Array Optional List of tools available for Function calling: 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

    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: results of the function called by the assistant (model)
    content String Required Conversation message content
    • Enter text (string).
    toolCalls Array Conditional Assistant call tool information
  • If the role is a tool, enter as the assistant's toolCalls request.
    		•
    toolCallId String Conditional Tool ID
    • Required if role is tool
    • Used to connect to the assistant's toolCalls request

    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

    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
    Note

    When entering some fields, check the following:

    • role: You can only include one Conversation message that is system per request.
    • Function calling can't be requested at the same time as inference or image interpretation.
    • For function calling, set the maximum number of tokens (maxTokens or maxCompletionTokens) used to generate the result to 1024 or more.

    Response

    This section describes the response format.

    Response headers

    The following describes the response headers.

    Headers Required Description
    Content-Type - Response data format
    • application/json

    Response body

    The response body includes the following data:

    Field Type Required Description
    status Object - Response status
    result Object - Response result
    result.created Integer - Response date and time
    • Unix timestamp milliseconds format
    result.usage Object - Token usage
    result.usage.completionTokens Integer - Generated token count
    result.usage.promptTokens Integer - Number of input (prompt) tokens
    result.usage.totalTokens Integer - Total number of tokens
    • Number of generated tokens + number of input tokens
    result.message Object - Conversation messages
    result.message.role Enum - Role of conversation messages
    • system | user | assistant
      • system: directives that define roles
      • user: user utterances/questions
      • assistant: answers of the model
    result.message.content String - Content of conversation messages
    result.message.toolCalls Array - toolCalls
    result.finishReason String - Reason for stopping token generation (generally passed to the last event)
    • length | stop| tool_calls
      • length: length limit
      • stop: character specified in stop occurred during answer generation
      • tool_calls: Model successfully completed tool call.
    result.seed Integer - Input seed value (Return a random value when 0 is entered or not entered)

    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

    Response stream

    You can use token streaming to output the tokens as they are generated, one by one. The following describes the token streaming format.

    Response headers

    The following describes the response headers.

    Headers Required Description
    Accept - Response data format
    • text/event-stream

    Response body

    The response body includes the following data:

    StreamingChatCompletionsTokenEvent

    The following describes StreamingChatCompletionsTokenEvent.

    Field Type Required Description
    created Integer - Response timestamp
    usage Object - Token usage
    usage.promptTokens Integer - Number of input (prompt) tokens
    usage.completionTokens Integer - Generated token count
    message Object - Conversation messages
    message.role Enum - Conversation message role
    • user | assistant
      • user: user's utterance or question
      • assistant: model's answer
    message.content String - Content of conversation messages
    message.toolCalls Array - toolCalls
    finishReason String - Reason for stopping token generation (typically passed to the last event)
    • length | stop
      • length: length limit
      • stop: character specified in stop occurred during answer generation.

    toolCalls

    The following describes toolCalls in StreamingChatCompletionsTokenEvent.

    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.partialJson String - Part of the string that makes up the JSON arguments to pass to function

    StreamingChatCompletionsResultEvent

    The following describes StreamingChatCompletionsResultEvent.

    Field Type Required Description
    created Integer - Response timestamp
    usage Object - Token usage
    usage.promptTokens Integer - Number of input (prompt) tokens
    usage.completionTokens Integer - Generated token count
    usage.totalTokens Integer - Total number of tokens
    • Number of generated tokens + number of input tokens
    message Object - Conversation messages
    message.role Enum - Conversation message role
    • user | assistant
      • user: user's utterance or question
      • assistant: model's answer
    message.content String - Content of conversation messages
    message.toolCalls Array - toolCalls
    finishReason String - Reason for stopping token generation (generally passed to the last event)
    • length | stop
      • length: length limit
      • stop: character specified in stop occurred during answer generation.
      • tool_calls: Model successfully completed tool call.

    ErrorEvent

    The following describes ErrorEvent.

    Field Type Required Description
    status Object - Response status
    status.code Object - Response status code
    status.message Object - Response status message

    SignalEvent

    The following describes SignalEvent.

    Field Type Required Description
    data String - Signal data information to pass

    Response example

    The response example is as follows:

    Succeeded

    The following is a sample response upon a successful call.

    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":"Seoul"}}]},"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":"Seoul","unit":"celsius","date":"2025-06-13"}}}]},"finishReason":"tool_calls","created":1749810707,"seed":1775609431,"usage":{"promptTokens":9,"completionTokens":47,"totalTokens":56}}

    Failure

    The following is a sample response upon a failed call.

    Operation method

    The operation of function calling, including requests and responses, is as follows:

    Step 1. Input and pass function definition

    Enter the query content and pass the function definition. The request example is as follows:

    • 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" : "How is the weather in Seoul today?",
    "role" : "user"
  } ],
  "tools" : [ {
    "function" : {
      "description" : "Tool that can tell you the weather",
      "name" : "get_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"
      }
    }
  }],
  "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": "What will the weather be like in Seoul tomorrow?",
            "role": "user"
        }
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "description": "Tool that can tell you the weather",
                "name": "get_weather",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "description": "City names such as Seoul, Daejeon, and Busan",
                            "type": "string"
                        },
                        "unit": {
                            "type": "string",
                            "enum": ["celsius", "fahrenheit"]
                        },
                        "date": {
                            "description": "Date string in the format such as 2025-03-21. Date you want to know the weather for",
                            "type": "string"
                        }
                    },
                    "required": ["location"]
                }
            }
        }
    ],
    "toolChoice": "auto"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)

    Step 2. Return function and arguments to be called

    The function and argument information to be called are returned. The response example is as follows:

    {
    "status": {
        "code": "20000",
        "message": "OK"
    },
    "result": {
        "message": {
            "role": "assistant",
            "content": "",
            "toolCalls": [
                {
                    "id": "call_s83AKVWrPPI6bCTLl5kFGtyo",
                    "type": "function",
                    "function": {
                        "name": "get_weather",
                        "arguments": {
                            "location": "Seoul",
                            "unit": "celsius",
                            "date": "2025-04-10"
                        }
                    }
                }
            ]
        },
        "finishReason": "tool_calls",
        "created": 1744218663,
        "seed": 1354242582,
        "usage": {
            "promptTokens": 134,
            "completionTokens": 48,
            "totalTokens": 315
        }
    }
}

    Step 3. Call actual function based on response result

    Call the actual function based on the response result of Step 2. The request example is as follows:

    • cURL
      # Example: Assume that the following API is called.
# GET https://weather.example.com?location=Seoul&unit=celsius&date=2025-04-10

curl --request GET 'https://weather.example.com?location=Seoul&unit=celsius&date=2025-04-10'
    • Python
      """
Example: Assume that the following function is configured.
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)

    The response example is as follows:

    { "location": "Seoul", "temperature": "17 degrees", "condition": "Sunny" }

    Step 4. Pass function execution results

    Pass the result of the function execution. The request example is as follows:

    • 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": "What will the weather be like in Seoul tomorrow?"
      },
      {
        "role": "assistant",
        "content": "",
        "toolCalls": [
          {
            "id": "call_s83AKVWrPPI6bCTLl5kFGtyo",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": {
                "location": "Seoul",
                "unit": "celsius",
                "date": "2025-04-10"
              }
            }
          }
        ]
      },
      {
        "role": "tool",
        "toolCallId": "call_s83AKVWrPPI6bCTLl5kFGtyo",
        "content": "{ \"location\": \"Seoul\", \"temperature\": \"17 degrees\", \"condition\": \"Sunny\" }"
      }
    ],
    "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": "What will the weather be like in Seoul tomorrow?"
        },
        {
            "role": "assistant",
            "content": "",
            "toolCalls": [
                {
                    "id": "call_s83AKVWrPPI6bCTLl5kFGtyo",
                    "type": "function",
                    "function": {
                        "name": "get_weather",
                        "arguments": {
                            "location": "Seoul",
                            "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. Return final text response

    Check the text of the final returned response result.

    {
    "status": {
        "code": "20000",
        "message": "OK"
    },
    "result": {
        "message": {
            "role": "assistant",
            "content": "Tomorrow's weather in Seoul is expected to be clear, with a temperature of 17 degrees. It looks like it will be a warm spring day, so it should be a good day to go out!"
        },
        "finishReason": "stop",
        "created": 1744218776,
        "seed": 2744409319,
        "usage": {
            "promptTokens": 88,
            "completionTokens": 37,
            "totalTokens": 125
        }
    }
}