---
title: "Function calling"
slug: "clovastudio-chatcompletionsv3-fc"
updated: 2026-09-17T09:35:47Z
published: 2026-09-17T09:35:47Z
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

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

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` | 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 message: [messages](/docs/en/clovastudio-chatcompletionsv3-fc#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 - 0.0 ＜ `repetitionPenalty` ≤ 2.0 (default: 1.1) - The higher the setting value, the lower the probability of repeatedly generating the same result. - We recommend fine-tuning in increments of 0.05 between 1.0 and 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](/docs/en/clovastudio-chatcompletionsv3-fc#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 informationIf the `role` is a `tool`, enter as the assistant's [toolCalls](/docs/en/clovastudio-chatcompletionsv3-fc#toolCalls) request. |
| `toolCallId` | String | Conditional | Tool ID - Required if `role` is `tool` - Used to connect to the assistant's [toolCalls](/docs/en/clovastudio-chatcompletionsv3-fc#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 | Optional | Parameter passed when using `function` - `properties`, `required` - Entry: See [Operation method](/docs/en/clovastudio-chatcompletionsv3-fc#%EB%8F%99%EC%9E%91%EB%B0%A9%EC%8B%9D). - 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` |

              Note

              

When entering some fields, check the following:

- `role`: You can only include one [Conversation message](/docs/en/clovastudio-chatcompletionsv3-fc#messages) 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 | - | See [Response status](/docs/en/ai-naver-clovastudio-summary#%EC%9D%91%EB%8B%B5). |
| `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](/docs/en/clovastudio-chatcompletionsv3-fc#toolCalls_response) |
| `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](/docs/en/clovastudio-chatcompletionsv3-fc#toolCalls_streaming) |
| `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](/docs/en/clovastudio-chatcompletionsv3-fc#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 | - | See [Response status](/docs/en/ai-naver-clovastudio-summary#%EC%9D%91%EB%8B%B5). |
| `status.code` | Object | - | Response status code - See [CLOVA Studio troubleshooting](/docs/en/clovastudio-troubleshoot). |
| `status.message` | Object | - | Response status message - See [CLOVA Studio troubleshooting](/docs/en/clovastudio-troubleshoot). |

#### 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.

- [Common client error troubleshooting (4xx)](/docs/en/clovastudio-troubleshoot-c4xx)
- [Common server error troubleshooting (5xx)](/docs/en/clovastudio-troubleshoot-c5xx)

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