テキストと画像

Prev Next

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はサポートしない

リクエストヘッダ

リクエストヘッダの説明は次の通りです。

ヘッダ 必須の有無 説明
Authorization Required 認証用 APIキー<例> Bearer nv-************
X-NCP-CLOVASTUDIO-REQUEST-ID Optional リクエスト ID
Content-Type Required リクエストデータの形式
  • application/json
Accept Conditional レスポンスデータの形式
  • text/event-stream
参考

レスポンス結果は基本的に JSON形式で返されますが、Accepttext/event-streamに指定するとレスポンス結果をストリーム形式で返します。

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

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

フィールド タイプ 必須の有無 説明
modelName Enum Required モデル名
  • <例> HCX-005
参考
  • HCX-005と HCX-DASH-002は Chat Completions v3 APIでのみ使用できます。
  • 画像の入力は HyperCLOVA Xビジョンモデルの HCX-005でのみ使用可能で、チューニング学習はサポートしません。

リクエストボディ

リクエストボディの説明は次の通りです。

フィールド タイプ 必須の有無 説明
messages Array Required 会話メッセージ
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)
    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 会話メッセージ内容

    content

    contentの説明は次の通りです。

    フィールド タイプ 必須の有無 説明
    type Enum Required 会話メッセージ内容の形式
    • text | image_url
      • text: テキスト
      • image_url: 画像 URL
    text String Conditional 会話メッセージ内容
    • テキスト入力
      • typetextの場合、必ず入力
    imageUrl Object Conditional 画像リスト
    • typeimage_urlの場合、imageUrldataUriのうち1つは必ず入力
    • ターンごとに画像は1つまで含めることが可能
    • 最適な結果のためにtextと一緒にリクエストすることがお勧め
    imageUrl.url String Conditional ファイル拡張子を含む単一画像の公開 URL
    • 画像サポートスペック
      • 形式: BMP、PNG、JPG、JPEG、WEBP
      • サイズ: 0Byte超過で20MB以下
      • 比率: アスペクト比が1:5または5:1以下
      • 長さ: 横長と縦長のどちらか長い方は2240px以下。短い方は4px以上
    dataUri Object Conditional 画像リスト
    • typeimage_urlの場合、imageUrldataUriのうち1つは必ず入力
    • ターンごとに画像は1つまで含めることが可能
    • 最適な結果のためにtextと一緒にリクエストすることがお勧め
    dataUri.data String Conditional Base64にエンコードされた画像文字列
    • 画像サポートスペック
      • 形式: BMP、PNG、JPG、JPEG、WEBP
      • サイズ: 0Byte超過で20MB以下
      • 比率: アスペクト比が1:5または5:1以下
      • 長さ: 横長と縦長のどちらか長い方は2240px以下。短い方は4px以上
    参考

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

    • 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 - レスポンスデータの形式
    • application/json

    レスポンスボディ

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

    フィールド タイプ 必須の有無 説明
    status Object - レスポンスステータス
    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

    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"
             }
            ]
        }
    }
    

    失敗

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

    レスポンスストリーム

    生成されるトークンを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フィルタの結果

    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}}
    

    失敗

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