Structured Outputs

Available in Classic and VPC

This section describes Chat Completions v3 with support for structured outputs, which allows you to generate output results in the desired JSON schema format.

Request

This section describes the request format. The method and URI are as follows:

Request headers

The following describes the request headers.

Request path parameters

You can use the following path parameters with your request:

Request body

You can include the following data in the body of your request:

messages

The following describes messages.

content

The following describes content.

Supported JSON schema

The following describes the supported JSON schemas.

• Type
  • string, number, boolean, integer, object, array
• Validation keyword
  • String (string)
    • format: Must be one of the defined formats.
    • Example:

      "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 (number, integer)
    • minimum: minimum value (equal to or greater)
    • maximum: maximum value (equal to or less)
  • Array (array)
    • minItems: minimum number of items
    • maxItems: maximum number of items
    • items: array item schema definition
  • Object (object)
    • properties: field schema definition
    • required: required field list
  • Enum and compound schemas
    • enum: Must be one of the predefined list of values.
    • anyOf: Must satisfy at least one of the listed schemas.

Request example

The request example is as follows:

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' \
--header 'Accept: text/event-stream' \
--data '{
    "messages": [
      {
        "role": "system",
        "content": "- This is a friendly AI assistant."
      },
      {
        "role": "user",
        "content":  "text": "Today's high is 32 degrees, the low is 15 degrees, and there is a 30% chance of precipitation."
      }
    ],
    "topP": 0.8,
    "topK": 0,
    "maxTokens": 100,
    "temperature": 0.5,
    "repetitionPenalty": 1.1,
    "stop": [],
    "responseFormat": {
      "type" : "json",
      "schema": {
        "type": "object",
        "properties": {
          "temp_high_c": {
            "type": "number",
            "description": "Highest temperature (Celsius)"
          },
          "temp_low_c": {
            "type": "number",
            "description": "Lowest temperature (Celsius)"
          },
          "precipitation_percent": {
            "type": "number",
            "description": "Precipitation probability (%)",
            "minimum": 0,
            "maximum": 100
          }
        },
        "required": [
          "temp_high_c",
          "temp_low_c",
          "precipitation_percent"
        ]
      }
    }
  }'

Response

This section describes the response format.

Response headers

The following describes the response headers.

Response body

The response body includes the following data:

aiFilter

The following describes aiFilter.

Response example

The response example is as follows:

Succeeded

The following is a sample response upon a successful call.

{
    "status": {
        "code": "20000",
        "message": "OK"
    },
    "result": {
        "created": 1791043155000,
        "usage": {
            "completionTokens": 80,
            "promptTokens": 843,
            "totalTokens": 923
        },        
        "message": {
            "role": "assistant",
            "content": "{\n  \"temp_high_c\": 32,\n  \"temp_low_c\": 15,\n  \"precipitation_percent\": 30\n}"
        },
        "seed": 1561390649,
        "aiFilter": [
         {
          "groupName": "curse",
          "name": "insult",
          "score": "1"
         },
         {
          "groupName": "curse",
          "name": "discrimination",
          "score": "0"
         },
         {
          "groupName": "unsafeContents",
          "name": "sexualHarassment",
          "score": "2"
         }
        ]
    }
}

Failure

The following is a sample response upon a failed call.

• Common client error troubleshooting (4xx)
• Common server error troubleshooting (5xx)

Response stream

You can use token streaming to output the tokens as they are generated, one by one. The following describes the token streaming format.

Response headers

The following describes the response headers.

Response body

The response body includes the following data:

StreamingChatCompletionsTokenEvent

The following describes StreamingChatCompletionsTokenEvent.

StreamingChatCompletionsResultEvent

The following describes StreamingChatCompletionsResultEvent.

ErrorEvent

The following describes ErrorEvent.

SignalEvent

The following describes SignalEvent.

Response example

The response example is as follows:

Succeeded

The following is a sample response upon a successful call.

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

Failure

The following is a sample response upon a failed call.

• Common client error troubleshooting (4xx)
• Common server error troubleshooting (5xx)