--- title: "テキストと画像" slug: "clovastudio-chatcompletionsv3" updated: 2026-09-17T09:57:20Z published: 2026-09-17T09:57:20Z canonical: "api.ncloud-docs.com/clovastudio-chatcompletionsv3" --- > ## 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. # テキストと画像 Classic/VPC環境で利用できます。 画像を解釈して理解できる HCX-005ビジョンモデルと軽量化された HCX-DASH-002モデルを利用できる v3 Chat Completionsを説明します。 ## リクエスト リクエスト形式を説明します。リクエスト形式は次の通りです。 | メソッド | URI | | --- | --- | | POST | - /v3/chat-completions/{modelName} - モデルを使用して文章を生成 - /v3/tasks/{taskId}/chat-completions - チューニング学習した結果を使用して文章を生成 - 画像の入力、推論、Function calling、Structured Outputsはサポートしていない | ### リクエストヘッダ 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-005` | | `taskId` | String | Conditional | 学習 ID - チューニング学習の結果を使用して文を生成する場合 - [学習の作成](/docs/ja/clovastudio-posttask)を参照 | 参考 - HCX-005と HCX-DASH-002は Chat Completions v3 APIでのみ使用できます。 - 画像の入力は HyperCLOVA Xビジョンモデルの HCX-005でのみ使用可能で、チューニング学習はサポートしません。 ### リクエストボディ リクエストボディの説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `messages` | Array | Required | 会話メッセージ: [messages](/docs/ja/clovastudio-chatcompletionsv3#messages) | | `topP` | Double | Optional | 生成トークン候補群を累積確率に基づいてサンプリング - 0.00 ＜ `topP` ≤ 1.00 (デフォルト: 0.80) | | `topK` | Integer | Optional | 生成トークン候補群から確率の高いトークン K個を候補に指定してサンプリング - 0 ≤ `topK` ≤ 128 (デフォルト: 0) | | `maxTokens` | Integer | Optional | 最大トークン生成数 - 1 ≤ `maxTokens` ≤ モデルの最大値 - `maxCompletionTokens`と同時に使用不可 | | `maxCompletionTokens` | Integer | Optional | 最大トークン生成数 (推論モデル) - 1 ≤ `maxCompletionTokens` ≤ モデルの最大値 - `maxTokens`と同時に使用不可 | | `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`値 | | `includeAiFilters` | Boolean | Optional | AIフィルタ(生成された結果値に対する罵倒、蔑み/差別/嫌悪、セクハラ/わいせつなどカテゴリ別に当てはまる程度)結果を表示するか - `true` \| `false` (デフォルト) - `true`: 表示 - `false`: 表示しない | #### `messages` `messages`の説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `role` | Enum | Required | 会話メッセージのロール - `system` \| `user` \| `assistant` - `system`: ロールを規定する指示文 - `user`: ユーザーの発話または質問 - `assistant`: ユーザーの発話/質問に対する回答 | | `content` | String \| Array | Required | 会話メッセージ内容 - テキスト入力(String) - テキスト、画像 URLで構成して入力(Array): [content](/docs/ja/clovastudio-chatcompletionsv3#content) | #### `content` `content`の説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `type` | Enum | Required | 会話メッセージ内容の形式 - `text` \| `image_url` - `text`: テキスト - `image_url`: 画像 URL | | `text` | String | Conditional | 会話メッセージ内容 - テキスト入力 | | `imageUrl` | Object | Conditional | 画像リスト - `type`が`image_url`の場合、`imageUrl`と`dataUri`のうち1つは必ず入力 - ターンごとに画像は1つまで含めることが可能 - 最適な結果のために`text`と一緒にリクエストすることがお勧め | | `imageUrl.url` | String | Conditional | ファイル拡張子を含む単一画像の公開 URL - 画像サポートスペック - 形式: BMP、PNG、JPG、JPEG、WEBP - サイズ: 0Byte超過で20MB以下 - 比率: アスペクト比が1:5または5:1以下 - 長さ: 横長と縦長のどちらか長い方は2240px以下。短い方は4px以上 | | `dataUri` | Object | Conditional | 画像リスト - `type`が`image_url`の場合、`imageUrl`と`dataUri`のうち1つは必ず入力 - ターンごとに画像は1つまで含めることが可能 - 最適な結果のために`text`と一緒にリクエストすることがお勧め | | `dataUri.data` | String | Conditional | Base64にエンコードされた画像文字列 - 画像サポートスペック - 形式: BMP、PNG、JPG、JPEG、WEBP - サイズ: 0Byte超過で20MB以下 - 比率: アスペクト比が1:5または5:1以下 - 長さ: 横長と縦長のどちらか長い方は2240px以下。短い方は4px以上 | 参考 一部フィールドの入力時、下記の内容をご確認ください。 - `role`: `system`の[会話メッセージ](/docs/ja/clovastudio-chatcompletionsv3#messages)は、リクエストごとに1つだけ含めることができます。 - HCX-005 - 入力トークンと出力トークンの合計は128,000トークンを超えてはいけません。 - 入力トークンの最大値は128,000トークンまでです。 - モデルにリクエスト可能な出力トークン(maxTokens)は最大4,096トークンまでです。 - `messages`: 画像は、ターンごとに1つ、リクエストごとに5つまで含めることができます。 - Request Bodyの総サイズは50MB以下にします。そのため、複数の画像をリクエストに含める場合は、base64形式より image URLの使用をお勧めします。 - HCX-DASH-002 - 入力トークンと出力トークンの合計は32,000トークンを超えてはいけません。 - 入力トークンの最大値は32,000トークンまでです。 - モデルにリクエスト可能な出力トークン(maxTokens)は最大4,096トークンまでです。 ### リクエスト例 リクエストのサンプルコードは次の通りです。 ``` curl --location --request POST 'https://clovastudio.stream.ntruss.com/v3/chat-completions/HCX-005' \ --header 'Authorization: Bearer {CLOVA Studio API Key}' \ --header 'X-NCP-CLOVASTUDIO-REQUEST-ID: {Request ID}' \ --header 'Content-Type: application/json' \ --header 'Accept: text/event-stream' \ --data '{ "messages": [ { "role": "system", "content": [ { "type": "text", "text": "- 丁寧に回答する AIアシスタントです。" } ] }, { "role": "user", "content": [ { "type": "image_url", "imageUrl": { "url": "https://www.******.com/image_a1b1c1.png" } }, { "type": "text", "text": "この写真について説明して" } ] } ], "topP": 0.8, "topK": 0, "maxTokens": 100, "temperature": 0.5, "repetitionPenalty": 1.1, "stop": [] }' ``` ## レスポンス レスポンス形式を説明します。 ### レスポンスヘッダ レスポンスヘッダの説明は次の通りです。 | ヘッダ | 必須の有無 | 説明 | | --- | --- | --- | | `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` \| `tool_calls` - `length`: 長さ制限 - `stop`: 回答生成中に`stop`に指定した文字が登場 - `tool_calls`: モデルが正常にツール呼び出しを完了 | | `result.seed` | Integer | - | 入力 seed値(0を入力したか、未入力の場合はランダムな値を返す) | | `result.aiFilter` | Array | - | AIフィルタの結果: [aiFilter](/docs/ja/clovastudio-chatcompletionsv3#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": { "created": 1791043155000, "usage": { "completionTokens": 80, "promptTokens": 843, "totalTokens": 923 }, "message": { "role": "assistant", "content": "写真には小さな子供が羊にエサを与えている様子が写っています。子供は青い服を着ていて、縞模様の帽子をかぶっています。子供の表情は集中しているように見え、羊は子供が与えるエサを食べようと頭を下げています。背景には別の羊も写っていて、この場所が羊の牧場であることがわかります。" }, "seed": 1561390649, "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` | ### レスポンスボディ レスポンスボディの説明は次の通りです。 #### 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#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": “こんに”},"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": “こんにちは”}, "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)