Structured Outputs

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

Structured Outputsをサポートして、目的の JSON Schema形式の出力結果を生成できる v3 Chat Completionsを説明します。

リクエスト

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

リクエストヘッダ

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

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

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

リクエストボディ

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

messages

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

サポートする 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つ以上を満たすこと

リクエスト例

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

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

レスポンス

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

レスポンスヘッダ

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

レスポンスボディ

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

aiFilter

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

レスポンス例

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

成功

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

{
    "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)
• サーバ共通エラー問題(5xx)

レスポンスストリーム

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

レスポンスヘッダ

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

レスポンスボディ

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

StreamingChatCompletionsTokenEvent

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

StreamingChatCompletionsResultEvent

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

ErrorEvent

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

SignalEvent

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

レスポンス例

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

成功

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

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)
• サーバ共通エラー問題(5xx)