---
title: "Chat Completions"
slug: "clovastudio-chatcompletions"
tags: ["CLOVA Studio"]
updated: 2026-09-17T09:35:47Z
published: 2026-09-17T09:35:47Z
canonical: "api.ncloud-docs.com/clovastudio-chatcompletions"
---

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

# Chat Completions

Available in Classic and VPC

This guide describes Chat Completions, which enables you to use the HCX-003 model for generating conversational sentences and the lightweight HCX-DASH-001 model.

## Request

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

| Method | URI |
| --- | --- |
| POST | - /v1/chat-completions/{modelName} - Generate sentences using the model. - /v1/tasks/{taskId}/chat-completions - /v2/tasks/{taskId}/chat-completions - Generate sentences using tuning trained jobs. |

### Request headers

The following describes the 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` | String | Conditional | Model name - When using the model to generate sentences - Example: `HCX-003` |
| `taskId` | String | Conditional | Training ID - When using tuning trained job to generate sentences - See [Create training](/docs/en/clovastudio-posttask). |

### Request body

The response body includes the following data:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `messages` | Array | Required | Conversation messages: [messages](/docs/en/clovastudio-chatcompletions#messages) |
| `temperature` | Double | Optional | Degree of diversity for the generated tokens (higher values generate more diverse sentences) - 0.00 ＜ `temperature` ≤ 1.00 (default: 0.50) - Display to two decimal places. |
| `topK` | Integer | Optional | Sample K high-probability candidates from the pool of generated token candidates. - 0 ≤ `topK` ≤ 128 (default: 0) |
| `topP` | Double | Optional | Sample generated token candidates based on cumulative probability. - 0.00 ＜ `topP` ≤ 1.00 (default: 0.80) - Display to two decimal places. |
| `repeatPenalty` | Double | Optional | Degree of penalty for generating the same token (the higher the setting, the less likely it is to generate the same result repeatedly) - 0.0 ＜ `repeatPenalty` ≤ 10.0 (default: 5.0) |
| `stopBefore` | Array | Optional | Character to abort token generation - [] (default) |
| `maxTokens` | Integer | Optional | Maximum number of generated tokens - 0 ＜ `maxTokens` ≤ 4096 (default: 100) |
| `includeAiFilters` | Boolean | Optional | Whether to display the AI Filter results (degree of the generated results in categories such as profanity, degradation/discrimination/hate, sexual harassment/obscenity, etc.) - `false` (default) \| `true` - `false`: not display - `true`: display |
| `seed` | Integer | Optional | Adjust consistency level of output on model iterations. - 0: Randomize consistency level (default). - 1 ≤ `seed` ≤ 4294967295: `seed` value of result value you want to generate consistently, or a user-specified `seed` value |

Note

When entering some fields, check the following:

- HCX-003
  - The sum of the input tokens and the output tokens cannot exceed 8192 tokens.
  - The input tokens can be up to 7600 tokens.
  - The output tokens (maxTokens) to be requested from the model can be up to 4096 tokens.
- HCX-DASH-001
  - The sum of the input tokens and the output tokens cannot exceed 4096 tokens.
  - The input tokens can be up to 3500 tokens.
  - The output tokens (maxTokens) to be requested from the model can be up to 4096 tokens.

#### `messages`

The following describes `messages`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | Enum | Required | Role of conversation messages - `system` \| `user` \| `assistant` - `system`: directives that define roles - `user`: user utterances/questions - `assistant`: answers to user utterances/questions |
| `content` | String | Required | Content of conversation messages |

### Request example

The request example is as follows:

```
curl --location --request POST 'https://clovastudio.stream.ntruss.com/v1/chat-completions/HCX-003' \
--header 'Authorization: Bearer {API Key}' \
--header 'X-NCP-CLOVASTUDIO-REQUEST-ID: {Request ID}' \
--header 'Content-Type: application/json' \
--header 'Accept: text/event-stream' \
--data '{
  "topK" : 0,
  "includeAiFilters" : true,
  "maxTokens" : 256,
  "temperature" : 0.5,
  "messages" : [ {
    "role" : "system",
    "content" : "test"
  }, {
    "role" : "user",
    "content" : "Let's test it."
  }, {
    "role" : "assistant",
    "content" : "Understood. What would you like to test?"
  } ],
  "stopBefore" : [ ],
  "repeatPenalty" : 5.0,
  "topP" : 0.8
}'
```

## 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.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.stopReason` | Enum | - | Reason for stopping results generation - `length` \| `end_token` \| `stop_before` - `length`: length limit - `end_token`: token count limit - `stop_before`: The model terminated its output on its own - Character specified in `stopBefore` occurred during answer generation |
| `result.inputLength` | Integer | - | Number of input tokens (including special tokens such as END OF TURN based on billing) |
| `result.outputLength` | Integer | - | Number of response tokens |
| `result.seed` | int | - | Input seed value (Return a random value when 0 is entered or not entered) |
| `result.aiFilter` | Array | - | AI Filter result: [aiFilter](/docs/en/clovastudio-chatcompletions#aiFilter) |

#### `aiFilter`

The following describes `aiFilter`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `groupName` | String | - | AI Filter category - `curse` \| `unsafeContents` - `curse`: degradation, discrimination, hate, and profanity - `unsafeContents`: sexual harassment, obscenity |
| `name` | String | - | AI Filter subcategory - `discrimination` \| `insult` \| `sexualHarassment` - `discrimination`: degradation, discrimination, hate - `insult`: profanity - `sexualHarassment`: sexual harassment, obscenity |
| `score` | String | - | AI Filter score - `-1` \| `0` \| `1` \| `2` - `-1`: AI Filter error occurred. - `0`: Conversation messages are more likely to contain sensitive/hazardous language. - `1`: Conversation messages are likely to contain sensitive/hazardous language. - `2`: Conversation messages are unlikely to contain sensitive/hazardous language. |
| `result` | String | - | Whether AI Filter is operating properly - `OK` \| `ERROR` - `OK`: normal operation - `ERROR`: error occurred |

Note

AI Filter can analyze up to 500 characters. However, if the text being analyzed contains many unusual formats, emojis, or special characters, it may not be analyzed correctly.

### Response example

The response example is as follows:

#### Succeeded

The following is a sample response upon a successful call.

```
{
  "status": {
    "code": "20000",
    "message": "OK"
  },
  "result": {
    "message": {
      "role": "assistant",
      "content": "Phrase: Record what happened today, and prepare for tomorrow. A journal will make your life richer.\n"
    },
    "stopReason": "LENGTH",
    "inputLength": 100,
    "outputLength": 10,
    "aiFilter": [
      {
        "groupName": "curse",
        "name": "insult",
        "score": "1"
      },
      {
        "groupName": "curse",
        "name": "discrimination",
        "score": "0"
      },
      {
        "groupName": "unsafeContents",
        "name": "sexualHarassment",
        "score": "2"
      }
    ]
  }
}
```

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

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

#### StreamingChatCompletionsResultEvent

The following describes `StreamingChatCompletionsResultEvent`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | Object | - | Conversation messages |
| `message.role` | Enum | - | Role of conversation messages - `system` \| `user` \| `assistant` - `system`: directives that define roles - `user`: user utterances/questions - `assistant`: answers of the model |
| `message.content` | String | - | Content of conversation messages |
| `stopReason` | Enum | - | Reason for stopping results generation - `length` \| `end_token` \| `stop_before` - `length`: length limit - `end_token`: token count limit - `stop_before`: character specified in `stopBefore` occurred during answer generation |
| `inputLength` | Integer | - | Number of input tokens (including special tokens such as END OF TURN based on billing) |
| `outputLength` | Integer | - | Number of response tokens (including special tokens such as END OF TURN based on billing) |
| `aiFilter` | Array | - | AI Filter result: [aiFilter](/docs/en/clovastudio-chatcompletions#aiFilter) |

#### StreamingChatCompletionsTokenEvent

The following describes `StreamingChatCompletionsTokenEvent`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | String | - | Event ID that identifies the request |
| `message` | Object | - | Conversation messages |
| `message.role` | Enum | - | Role of conversation messages - `system` \| `user` \| `assistant` - `system`: directives that define roles - `user`: user utterances/questions - `assistant`: answers of the model |
| `message.content` | String | - | Content of conversation messages |
| `inputLength` | Integer | - | Number of input tokens (including special tokens such as END OF TURN based on billing) |
| `outputLength` | Integer | - | Number of response tokens (including special tokens such as END OF TURN based on billing) |
| `stopReason` | Enum | - | Reason for stopping results generation - `length` \| `end_token` \| `stop_before` - `length`: length limit - `end_token`: token count limit - `stop_before`: - The model successfully completed generation. - Character specified in `stopBefore` occurred during answer generation. |

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

#### 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: aabdfe-dfgwr-edf-hpqwd-f3asd-g
event: token
data: {"message": {"role": "assistant", "content": “H”}}

id: aabdfe-dfgwr-edf-hpqwd-f2asd-g
event: token
data: {"message": {"role": "assistant", "content": “i”}}

id: aabdfe-dfgwr-edf-hpqwd-f1asd-g
event: result
data: {"message": {"role": "assistant", "content": "Hello"}, "inputLength":20, "outputLength":5, "stopReason":"stop_before" }
```

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