--- title: "Structured Outputs" slug: "clovastudio-chatcompletionsv3-so" updated: 2026-09-17T09:57:20Z published: 2026-09-17T09:57:20Z canonical: "api.ncloud-docs.com/clovastudio-chatcompletionsv3-so" --- > ## 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. # Structured Outputs Classic/VPC環境で利用できます。 Structured Outputsをサポートして、目的の JSON Schema形式の出力結果を生成できる v3 Chat Completionsを説明します。 ## リクエスト リクエスト形式を説明します。リクエスト形式は次の通りです。 | メソッド | URI | | --- | --- | | POST | /v3/chat-completions/{modelName} | ### リクエストヘッダ CLOVA Studio APIで共通して使用されるヘッダの詳細は、[CLOVA Studioのリクエストヘッダ](/docs/ja/ai-naver-clovastudio-summary#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94)をご参照ください。 ### リクエストパスパラメータ リクエストパスパラメータの説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `modelName` | Enum | Required | モデル名 - <例> `HCX-007` | 参考 Structured Outputsは HCX-007モデルでのみ使用できます。 ### リクエストボディ リクエストボディの説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `messages` | Array | Required | 会話メッセージ: [messages](/docs/ja/clovastudio-chatcompletionsv3-so#messages) | | `topP` | Double | Optional | 生成トークン候補群を累積確率に基づいてサンプリング - 0.00 ＜ `topP` ≤ 1.00 (デフォルト: 0.80) | | `topK` | Integer | Optional | 生成トークン候補群から確率の高いトークン K個を候補に指定してサンプリング - 0 ≤ `topK` ≤ 128 (デフォルト: 0) | | `maxCompletionTokens` | Integer | Optional | 最大トークン生成数 - 0 ＜ `maxCompletionTokens` ≤ 32768 (デフォルト: 512) | | `temperature` | Double | Optional | 生成トークンに対する多様性の程度(設定値が高いほど多様な文章を生成) - 0.00 ≤ `temperature` ≤ 1.00 (デフォルト: 0.50) | | `repetitionPenalty` | Double | Optional | 同じトークンを生成することに対するペナルティの程度 - 0.0 ＜ `repetitionPenalty` ≤ 2.0 (デフォルト: 1.1) - 設定値が高いほど同じ結果値を繰り返し生成する確率は下がる - 1.0~1.1の範囲内で0.05単位での微調整を推奨 | | `stop` | Array | Optional | トークン生成停止文字 - [](デフォルト) | | `seed` | Integer | Optional | モデルの繰り返し実行時、結果値の一貫性レベルを調整 - 0: 一貫性レベルをランダム適用 (デフォルト) - 1 ≤ `seed` ≤ 4294967295: 一貫して作成しようとする結果値の`seed`またはユーザーが指定する`seed`値 | | `thinking` | Object | Optional | 推論モデルの設定情報 | | `thinking.effort` | String | Optional | 推論の有無と思考の深さを設定 - `none` (有効値) - Structured Outputsと同時に使用不可 | | `responseFormat` | Object | Optional | モデルが出力する回答形式 | | `responseFormat.type` | String | Required | 回答形式タイプ - `json` (有効値) | | `responseFormat.schema` | Object | Required | 回答形式のスキーマ - 回答形式タイプに合ったスキーマ - JSON Schema(object) (有効値) - [サポートする JSON Schema](/docs/ja/clovastudio-chatcompletionsv3-so#%EC%A7%80%EC%9B%90%ED%95%98%EB%8A%94JSONSchema)を参照 | | `includeAiFilters` | Boolean | Optional | AIフィルタ(生成された結果値に対する罵倒、蔑み/差別/嫌悪、セクハラ/わいせつなどカテゴリ別に当てはまる程度)結果を表示するか - `true` \| `false` (デフォルト) - `true`: 表示 - `false`: 表示しない | #### `messages` `messages`の説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `role` | Enum | Required | 会話メッセージのロール - `system` \| `user` \| `assistant` \| - `system`: ロールを規定する指示文 - `user`: ユーザーの発話または質問 - `assistant`: ユーザーの発話/質問に対する回答 | | `content` | String | Required | 会話メッセージ内容 - テキスト入力(String) | #### サポートする JSON Schema サポートする JSON Schemaの説明は次の通りです。 - タイプ - `string`, `number`, `boolean`, `integer`, `object`, `array` - 制限キーワード(Validation Keyword) - 文字列 (`string`) - `format`: 定義された形式のいずれかであること - <例> ``` "date-time": "2025-06-30T14:00:00Z", "date": "2025-06-30", "time": "14:30:00", "duration": "P3Y6M4DT12H30M5S", "email": "user@example.com", "hostname": "example.com", "ipv4": "192.***.***.***", "ipv6": "2001:****::1", "uuid": "123e4567-e89b-12d3-a456-426614174000" ``` - 数字 (`number`、`integer`) - `minimum`: 最小値 (以上) - `maximum`: 最大値 (以下) - 配列 (`array`) - `minItems`: 最小アイテム数 - `maxItems`: 最大アイテム数 - `items`: 配列項目スキーマの定義 - オブジェクト (`object`) - `properties`: フィールドスキーマの定義 - `required`: 必須フィールドリスト - Enumと複合スキーマ - `enum`: 既に定義されている値リストのいずれかであること - `anyOf`: 並べられたスキーマのうち1つ以上を満たすこと 参考 一部フィールドの入力時、下記の内容をご確認ください。 - `role`: `system`の[会話メッセージ](/docs/ja/clovastudio-chatcompletionsv3-so#messages)は、リクエストごとに1つだけ含めることができます。 - Structured Outputsと推論、または Function callingは、同時にリクエストできません。 - Structured Outputsは JSON schemaの一部だけサポートしています。 - `pattern`(Validation Keyword)はサポートしません。 ### リクエスト例 リクエストのサンプルコードは次の通りです。 ``` curl --location --request POST 'https://clovastudio.stream.ntruss.com/v3/chat-completions/HCX-007' \ --header 'Authorization: Bearer {CLOVA Studio API Key}' \ --header 'X-NCP-CLOVASTUDIO-REQUEST-ID: {Request ID}' \ --header 'Content-Type: application/json' \ --data '{ "messages": [ { "role": "system", "content": "- あらかじめ定義した JSON Schema形式に合わせて回答する AIアシスタントです。" }, { "role": "user", "content": "今日の最高気温は32度、最低気温は15度、降水確率は30％です。" } ], "topP": 0.8, "topK": 0, "maxCompletionTokens": 100, "temperature": 0.5, "repetitionPenalty": 1.1, "thinking": {"effort": "none"}, "stop": [], "responseFormat": { "type" : "json", "schema": { "type": "object", "properties": { "temp_high_c": { "type": "number", "description": "最高気温(摂氏)" }, "temp_low_c": { "type": "number", "description": "最低気温(摂氏)" }, "precipitation_percent": { "type": "number", "description": "降水確率(%)", "minimum": 0, "maximum": 100 } }, "required": [ "temp_high_c", "temp_low_c", "precipitation_percent" ] } } }' ``` ## レスポンス レスポンス形式を説明します。 ### レスポンスヘッダ レスポンスヘッダの説明は次の通りです。 | ヘッダ | 必須の有無 | 説明 | | --- | --- | --- | | `Content-Type` | - | レスポンスデータの形式 - `application/json` | ### レスポンスボディ レスポンスボディの説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `status` | Object | - | [レスポンスステータス](/docs/ja/ai-naver-clovastudio-summary#%EC%9D%91%EB%8B%B5)を参照 | | `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.finishReason` | String | - | トークン生成停止の理由(通常、最後のイベントで渡す) - `length` \| `stop` - `length`: 長さ制限 - `stop`: 回答生成中に`stop`に指定した文字が登場 - `tool_calls`: モデルが正常にツール呼び出しを完了 | | `result.seed` | Integer | - | 入力 seed値(0を入力したか、未入力の場合はランダムな値を返す) | | `result.aiFilter` | Array | - | AIフィルタの結果: [aiFilter](/docs/ja/clovastudio-chatcompletionsv3-so#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 \"temp_high_c\": 32,\n \"temp_low_c\": 15,\n \"precipitation_percent\": 30\n}" }, "finishReason": "stop", "created": 1754315742, "seed": 965671181, "usage": { "promptTokens": 39, "completionTokens": 31, "totalTokens": 70 }, "aiFilter": [ { "groupName": "curse", "name": "insult", "score": "1", "result": "OK" }, { "groupName": "curse", "name": "discrimination", "score": "1", "result": "OK" }, { "groupName": "unsafeContents", "name": "sexualHarassment", "score": "2", "result": "OK" } ] } } ``` #### 失敗 呼び出しに失敗した場合のレスポンスのサンプルコードは次の通りです。 - [クライアント共通エラー問題(4xx)](/docs/ja/clovastudio-troubleshoot-c4xx) - [サーバ共通エラー問題(5xx)](/docs/ja/clovastudio-troubleshoot-c5xx) ## レスポンスストリーム 生成されるトークンを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 | - | 会話メッセージの内容 | | `finishReason` | String | - | トークン生成停止の理由(通常、最後のイベントで渡す) - `length` \| `stop` - `length`: 長さ制限 - `stop`: 回答生成中に`stop`に指定した文字が登場 | #### 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 | - | 会話メッセージの内容 | | `finishReason` | String | - | トークン生成停止の理由(通常、最後のイベントで渡す) - `length` \| `stop` - `length`: 長さ制限 - `stop`: 回答生成中に`stop`に指定した文字が登場 | | `aiFilter` | Array | - | AIフィルタの結果: [aiFilter](/docs/ja/clovastudio-chatcompletionsv3-so#aiFilter) | #### ErrorEvent `ErrorEvent`の説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `status` | Object | - | [レスポンスステータス](/docs/ja/ai-naver-clovastudio-summary#%EC%9D%91%EB%8B%B5)を参照 | | `status.code` | Object | - | レスポンスステータスコード - [CLOVA Studioのトラブルシューティング](/docs/ja/clovastudio-troubleshoot)を参照 | | `status.message` | Object | - | レスポンスステータスメッセージ - [CLOVA Studioのトラブルシューティング](/docs/ja/clovastudio-troubleshoot)を参照 | #### SignalEvent `SignalEvent`の説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `data` | String | - | 渡すシグナルデータ情報 | ### レスポンス例 レスポンスのサンプルコードは次の通りです。 #### 成功 呼び出しに成功した場合のレスポンスのサンプルコードは次の通りです。 ``` id: aabdfe-dfgwr-edf-hpqwd-f3asd-g event: token data: {"message": {"role": "assistant", "content": "{\n"},"finishReason": null, "created": 1744710905, "seed": 3284419119, "usage": null} id: aabdfe-dfgwr-edf-hpqwd-f2asd-g event: token data: {"message": {"role": "assistant", "content": " "},"finishReason": null, "created": 1744710905, "seed": 3284419119, "usage": null} ... id: aabdfe-dfgwr-edf-hpqwd-f1asd-g event: result data: {"message": {"role": "assistant", "content": "{\n \"temp_high_c\": 32,\n \"temp_low_c\": 15,\n \"precipitation_percent\": 30\n}"}, "finishReason": "stop", "created": 1744710905, "seed": 3284419119, "usage": {"promptTokens": 20, "completionTokens": 5, "totalTokens": 25}} ``` #### 失敗 呼び出しに失敗した場合のレスポンスのサンプルコードは次の通りです。 - [クライアント共通エラー問題(4xx)](/docs/ja/clovastudio-troubleshoot-c4xx) - [サーバ共通エラー問題(5xx)](/docs/ja/clovastudio-troubleshoot-c5xx)