---
title: "Chat Completions"
slug: "clovastudio-chatcompletions"
tags: ["CLOVA Studio"]
updated: 2026-09-17T09:57:20Z
published: 2026-09-17T09:57:20Z
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

Classic/VPC環境で利用できます。

会話型文章を生成する HCX-003モデルと軽量化された HCX-DASH-001モデルを利用できる Chat Completionsを説明します。

## リクエスト

リクエスト形式を説明します。リクエスト形式は次の通りです。

| メソッド | URI |
| --- | --- |
| POST | - /v1/chat-completions/{modelName} - モデルを使用して文を生成 - /v1/tasks/{taskId}/chat-completions - /v2/tasks/{taskId}/chat-completions - チューニング学習した結果を使用して文を生成 |

### リクエストヘッダ

CLOVA Studio APIで共通して使用されるヘッダの詳細は、[CLOVA Studioのリクエストヘッダ](/docs/ja/ai-naver-clovastudio-summary#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94)をご参照ください。

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

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

| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
| `modelName` | String | Conditional | モデル名 - モデルを使用して文を生成する場合 - <例> `HCX-003` |
| `taskId` | String | Conditional | 学習 ID - チューニング学習の結果を使用して文を生成する場合 - [学習作成](/docs/ja/clovastudio-posttask) を参照 |

### リクエストボディ

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

| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
| `messages` | Array | Required | 会話メッセージ: [messages](/docs/ja/clovastudio-chatcompletions#messages) |
| `temperature` | Double | Optional | 生成トークンに対する多様性の程度(設定値が高いほど多様な文を生成) - 0.00 ＜ `temperature` ≤ 1.00 (デフォルト: 0.50) - 小数点第二位まで表記 |
| `topK` | Integer | Optional | 生成トークン候補群から確率の高いトークン K個を候補に指定してサンプリング - 0 ≤ `topK` ≤ 128 (デフォルト: 0) |
| `topP` | Double | Optional | 生成トークン候補群を累積確率に基づいてサンプリング - 0.00 ＜ `topP` ≤ 1.00 (デフォルト: 0.80) - 小数点第二位まで表記 |
| `repeatPenalty` | Double | Optional | 同じトークンを生成することに対するペナルティの程度(設定値が高いほど同じ結果値を繰り返し生成する確率は下がる) - 0.0 ＜ `repeatPenalty` ≤ 10.0 (デフォルト: 5.0) |
| `stopBefore` | Array | Optional | トークン生成停止文字 - [](デフォルト) |
| `maxTokens` | Integer | Optional | 最大トークン生成数 - 0 ＜ `maxTokens` ≤ 4096 (デフォルト: 100) |
| `includeAiFilters` | Boolean | Optional | AIフィルタ(生成された結果値に対する罵倒、蔑み/差別/嫌悪、セクハラ/わいせつなどカテゴリ別に当てはまる程度)結果を表示するかどうか - `false`(デフォルト) \| `true` - `false`: 表示しない - `true`: 表示 |
| `seed` | Integer | Optional | モデルの繰り返し実行時、結果値の一貫性レベルを調整 - 0: 一貫性レベルをランダム適用 (デフォルト) - 1 ≤ `seed` ≤ 4294967295: 一貫して作成しようとする結果値の`seed`またはユーザーが指定する`seed`値 |

参考

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

- HCX-003
  - 入力トークンと出力トークンの合計は8,192トークンを超えてはいけません。
  - 入力トークンの最大値は7,600トークンまでです。
  - モデルにリクエスト可能な出力トークン(maxTokens)は最大4,096トークンまでです。
- HCX-DASH-001
  - 入力トークンと出力トークンの合計は4,096トークンを超えてはいけません。
  - 入力トークンの最大値は3,500トークンまでです。
  - モデルにリクエスト可能な出力トークン(maxTokens)は最大4,096トークンまでです。

#### `messages`

`messages`の説明は次の通りです。

| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
| `role` | Enum | Required | 会話メッセージのロール - `system` \| `user` \| `assistant` - `system`: ロールを規定する指示文 - `user`: ユーザーの発話または質問 - `assistant`: ユーザーの発話/質問に対する回答 |
| `content` | String | Required | 会話メッセージの内容 |

### リクエスト例

リクエストのサンプルコードは次の通りです。

```
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" : "テストをしてみよう。"
  }, {
    "role" : "assistant",
    "content" : "分かりました。何をテストしてみましょうか。"
  } ],
  "stopBefore" : [ ],
  "repeatPenalty" : 5.0,
  "topP" : 0.8
}'
```

## レスポンス

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

### レスポンスヘッダ

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

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

### レスポンスボディ

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

| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
| `status` | Object | - | [レスポンスステータス](/docs/ja/ai-naver-clovastudio-summary#%EC%9D%91%EB%8B%B5)を参照 |
| `result` | Object | - | レスポンス結果 |
| `result.message` | Object | - | 会話メッセージ |
| `result.message.role` | Enum | - | 会話メッセージのロール - `system` \| `user` \| `assistant` - `system`: ロールを規定する指示文 - `user`: ユーザーの発話または質問 - `assistant`: モデルの回答 |
| `result.message.content` | String | - | 会話メッセージの内容 |
| `result.stopReason` | Enum | - | 結果生成停止の理由 - `length` \| `end_token` \| `stop_before` - `length`: 長さ制限 - `end_token`: トークン数制限 - `stop_before`: モデルが自動で出力を終了 - 回答生成中`stopBefore`に指定した文字が登場 |
| `result.inputLength` | Integer | - | 入力トークン数(課金の基準で、end of turnといった特殊なトークンも含む) |
| `result.outputLength` | Integer | - | レスポンストークン数 |
| `result.seed` | int | - | 入力 seed値(0を入力したか、未入力の場合はランダムな値を返す) |
| `result.aiFilter` | Array | - | AIフィルタの結果: [aiFilter](/docs/ja/clovastudio-chatcompletions#aiFilter) |

#### `aiFilter`

`aiFilter`の説明は次の通りです。

| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
| `groupName` | String | - | AIフィルタのカテゴリ - `curse` \| `unsafeContents` - `curse`: 蔑み、差別、嫌悪および罵倒 - `unsafeContents`: セクハラ、わいせつ |
| `name` | String | - | AIフィルタの詳細カテゴリ - `discrimination` \| `insult` \| `sexualHarassment` - `discrimination`: 蔑み、差別、嫌悪 - `insult`: 罵倒 - `sexualHarassment`: セクハラ、わいせつ |
| `score` | String | - | AIフィルタスコア - `-1` \| `0` \| `1` \| `2` - `-1`: AIフィルタにエラー発生 - `0`: 会話メッセージに要注意/危険な表現を含む可能性が高い - `1`: 会話メッセージに要注意/危険な表現を含む可能性がある - `2`: 会話メッセージに要注意/危険な表現を含む可能性が低い |
| `result` | String | - | AIフィルタは正常に動作しているか - `OK` \| `ERROR` - `OK`: 正常に動作 - `ERROR`: エラー発生 |

参考

AI Filterは最大500文字まで分析できます。ただし、分析対象テキストに異常な形式、絵文字、記号などが多い場合、正常に分析されないことがあります。

### レスポンス例

レスポンスのサンプルコードは次の通りです。

#### 成功

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

```
{
  "status": {
    "code": "20000",
    "message": "OK"
  },
  "result": {
    "message": {
      "role": "assistant",
      "content": "文言: 今日一日の出来事を記録して、明日に備えましょう。ダイアリーはあなたの人生をより豊かにしてくれます。\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"
      }
    ]
  }
}
```

#### 失敗

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

- [クライアント共通エラー問題(4xx)](/docs/ja/clovastudio-troubleshoot-c4xx)
- [サーバ共通エラー問題(5xx)](/docs/ja/clovastudio-troubleshoot-c5xx)

## レスポンスストリーム

生成されるトークンを1つずつ出力するようにトークンストリーミングを使用できます。トークンストリーミング形式を説明します。

### レスポンスヘッダ

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

| ヘッダ | 必須の有無 | 説明 |
| --- | --- | --- |
| Accept | - | レスポンスデータの形式 - `text/event-stream` |

### レスポンスボディ

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

#### StreamingChatCompletionsResultEvent

`StreamingChatCompletionsResultEvent`の説明は次の通りです。

| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
| `message` | Object | - | 会話メッセージ |
| `message.role` | Enum | - | 会話メッセージのロール - `system` \| `user` \| `assistant` - `system`: ロールを規定する指示文 - `user`: ユーザーの発話または質問 - `assistant`: モデルの回答 |
| `message.content` | String | - | 会話メッセージの内容 |
| `stopReason` | Enum | - | 結果生成停止の理由 - `length` \| `end_token` \| `stop_before` - `length`: 長さ制限 - `end_token`: トークン数制限 - `stop_before`: 回答生成中`stopBefore`に指定した文字が登場 |
| `inputLength` | Integer | - | 入力トークン数(課金の基準で、end of turnといった特殊なトークンも含む) |
| `outputLength` | Integer | - | レスポンストークン数(課金の基準で、end of turnといった特殊なトークンも含む) |
| `aiFilter` | Array | - | AIフィルタの結果: [aiFilter](/docs/ja/clovastudio-chatcompletions#aiFilter) |

#### StreamingChatCompletionsTokenEvent

`StreamingChatCompletionsTokenEvent`の説明は次の通りです。

| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
| `id` | String | - | リクエストを識別するイベント ID |
| `message` | Object | - | 会話メッセージ |
| `message.role` | Enum | - | 会話メッセージのロール - `system` \| `user` \| `assistant` - `system`: ロールを規定する指示文 - `user`: ユーザーの発話または質問 - `assistant`: モデルの回答 |
| `message.content` | String | - | 会話メッセージの内容 |
| `inputLength` | Integer | - | 入力トークン数(課金の基準で、end of turnといった特殊なトークンも含む) |
| `outputLength` | Integer | - | レスポンストークン数(課金の基準で、end of turnといった特殊なトークンも含む) |
| `stopReason` | Enum | - | 結果生成停止の理由 - `length` \| `end_token` \| `stop_before` - `length`: 長さ制限 - `end_token`: トークン数制限 - `stop_before`: - モデルが正常に生成完了 - 回答生成中`stopBefore`に指定した文字が登場 |

#### ErrorEvent

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

| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
| `status` | Object | - | [レスポンスステータス](/docs/ja/ai-naver-clovastudio-summary#%EC%9D%91%EB%8B%B5)を参照 |

#### SignalEvent

`SignalEvent`の説明は次の通りです。

| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
| `data` | String | - | 渡すシグナルデータ情報 |

### レスポンス例

レスポンスのサンプルコードは次の通りです。

#### 成功

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

```
id: aabdfe-dfgwr-edf-hpqwd-f3asd-g
event: token
data: {"message": {"role": "assistant", "content": “こんに”}}

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

id: aabdfe-dfgwr-edf-hpqwd-f1asd-g
event: result
data: {"message": {"role": "assistant", "content": “こんにちは”}, "inputLength":20, "outputLength":5, "stopReason":"stop_before" }
```

#### 失敗

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

- [クライアント共通エラー問題(4xx)](/docs/ja/clovastudio-troubleshoot-c4xx)
- [サーバ共通エラー問題(5xx)](/docs/ja/clovastudio-troubleshoot-c5xx)