Classic/VPC環境で利用できます。
画像を解釈して理解できる HCX-005ビジョンモデルと軽量化された HCX-DASH-002モデルを利用できる v3 Chat Completionsを説明します。
リクエスト
リクエスト形式を説明します。リクエスト形式は次の通りです。
メソッド | URI |
---|---|
POST |
|
リクエストヘッダ
リクエストヘッダの説明は次の通りです。
ヘッダ | 必須の有無 | 説明 |
---|---|---|
Authorization |
Required | 認証用 APIキー<例> Bearer nv-************ |
X-NCP-CLOVASTUDIO-REQUEST-ID |
Optional | リクエスト ID |
Content-Type |
Required | リクエストデータの形式
|
Accept |
Conditional | レスポンスデータの形式
|
レスポンス結果は基本的に JSON形式で返されますが、Accept
をtext/event-stream
に指定するとレスポンス結果をストリーム形式で返します。
リクエストパスパラメータ
リクエストパスパラメータの説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
modelName |
Enum | Required | モデル名
|
- HCX-005と HCX-DASH-002は Chat Completions v3 APIでのみ使用できます。
- 画像の入力は HyperCLOVA Xビジョンモデルの HCX-005でのみ使用可能で、チューニング学習はサポートしません。
リクエストボディ
リクエストボディの説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
messages |
Array | Required | 会話メッセージ |
topP |
Double | Optional | 生成トークン候補群を累積確率に基づいてサンプリング
|
topK |
Integer | Optional | 生成トークン候補群から確率の高いトークン K個を候補に指定してサンプリング
|
maxTokens |
Integer | Optional | 最大トークン生成数maxTokens ≤ モデルの最大値 maxCompletionTokens と同時に使用不可 |
maxCompletionTokens |
Integer | Optional | 最大トークン生成数 (推論モデル)
|
temperature |
Double | Optional | 生成トークンに対する多様性の程度(設定値が高いほど多様な文章を生成)
|
repetitionPenalty |
Double | Optional | 同じトークンを生成することに対するペナルティの程度(設定値が高いほど同じ結果値を繰り返し生成する確率は下がる)
|
stop |
Array | Optional | トークン生成停止文字
|
seed |
Integer | Optional | モデルの繰り返し実行時、結果値の一貫性レベルを調整
|
includeAiFilters |
Boolean | Optional | AIフィルタ(生成された結果値に対する罵倒、蔑み/差別/嫌悪、セクハラ/わいせつなどカテゴリ別に当てはまる程度)結果を表示するかどうか
|
messages
messages
の説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
role |
Enum | Required | 会話メッセージのロール
|
content |
String | Array | Required | 会話メッセージ内容
|
content
content
の説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
type |
Enum | Required | 会話メッセージ内容の形式
|
text |
String | Conditional | 会話メッセージ内容
|
imageUrl |
Object | Conditional | 画像リスト
|
imageUrl.url |
String | Conditional | ファイル拡張子を含む単一画像の公開 URL
|
dataUri |
Object | Conditional | 画像リスト
|
dataUri.data |
String | Conditional | Base64にエンコードされた画像文字列
|
一部フィールドの入力時、下記の内容をご確認ください。
role
:system
の会話メッセージは、リクエストごとに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 |
- | レスポンスデータの形式
|
レスポンスボディ
レスポンスボディの説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
status |
Object | - | レスポンスステータス |
result |
Object | - | レスポンス結果 |
result.created |
Integer | - | レスポンスの日付
|
result.usage |
Object | - | トークン使用量 |
result.usage.completionTokens |
Integer | - | 生成トークン数 |
result.usage.promptTokens |
Integer | - | 入力(プロンプト)トークン数 |
result.usage.totalTokens |
Integer | - | トークンの総数
|
result.message |
Object | - | 会話メッセージ |
result.message.role |
Enum | - | 会話メッセージのロール
|
result.message.content |
String | - | 会話メッセージの内容 |
result.finishReason |
String | - | トークン生成停止の理由(通常、最後のイベントで渡す)
|
result.seed |
Integer | - | 入力 seed値(0を入力したか、未入力の場合はランダムな値を返す) |
result.aiFilter |
Array | - | AIフィルタの結果 |
aiFilter
aiFilter
の説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
groupName |
String | - | AIフィルタのカテゴリ
|
name |
String | - | AIフィルタの詳細カテゴリ
|
score |
String | - | AIフィルタスコア
|
result |
String | - | AIフィルタは正常に動作しているか
|
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"
}
]
}
}
失敗
呼び出しに失敗した場合のレスポンスのサンプルコードは次の通りです。
レスポンスストリーム
生成されるトークンを1つずつ出力するようにトークンストリーミングを使用できます。トークンストリーミング形式を説明します。
レスポンスヘッダ
レスポンスヘッダの説明は次の通りです。
ヘッダ | 必須の有無 | 説明 |
---|---|---|
Accept |
- | レスポンスデータの形式
|
レスポンスボディ
レスポンスボディの説明は次の通りです。
StreamingChatCompletionsTokenEvent
StreamingChatCompletionsTokenEvent
の説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
created |
Integer | - | レスポンス時間のタイムスタンプ |
usage |
Object | - | トークン使用量 |
usage.promptTokens |
Integer | - | 入力(プロンプト)トークン数 |
usage.completionTokens |
Integer | - | 生成トークン数 |
message |
Object | - | 会話メッセージ |
message.role |
Enum | - | 会話メッセージのロール
|
message.content |
String | - | 会話メッセージの内容 |
finishReason |
String | - | トークン生成停止の理由(通常、最後のイベントで渡す)
|
StreamingChatCompletionsResultEvent
StreamingChatCompletionsResultEvent
の説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
created |
Integer | - | レスポンス時間のタイムスタンプ |
usage |
Object | - | トークン使用量 |
usage.promptTokens |
Integer | - | 入力(プロンプト)トークン数 |
usage.completionTokens |
Integer | - | 生成トークン数 |
usage.totalTokens |
Integer | - | トークンの総数
|
message |
Object | - | 会話メッセージ |
message.role |
Enum | - | 会話メッセージのロール
|
message.content |
String | - | 会話メッセージの内容 |
finishReason |
String | - | トークン生成停止の理由(通常、最後のイベントで渡す)
|
aiFilter |
Array | - | AIフィルタの結果 |
ErrorEvent
ErrorEvent
の説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
status |
Object | - | レスポンスステータス |
status.code |
Object | - | レスポンスステータスコード |
status.message |
Object | - | レスポンスステータスメッセージ |
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}}
失敗
呼び出しに失敗した場合のレスポンスのサンプルコードは次の通りです。