---
title: "Structured Outputs"
slug: "clovastudio-chatcompletionsv3-so"
updated: 2026-09-17T09:35:47Z
published: 2026-09-17T09:35:47Z
canonical: "api.ncloud-docs.com/clovastudio-chatcompletionsv3-so"
---

> ## 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.

# 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:

| Method | URI |
| --- | --- |
| POST | /v3/chat-completions/{modelName} |

### Request headers

For information about the headers common to all CLOVA Studio APIs, see [CLOVA Studio request headers](/docs/en/ai-naver-clovastudio-summary#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94).

### Request path parameters

You can use the following path parameters with your request:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `modelName` | Enum | Required | Model name - Example: `HCX-007` |

Note

Structured outputs are only available on the HCX-007 model.

### Request body

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `messages` | Array | Required | Conversation messages: [messages](/docs/en/clovastudio-chatcompletionsv3-so#messages) |
| `topP` | Double | Optional | Sample generated token candidates based on cumulative probability. - 0.00 ＜ `topP` ≤ 1.00 (default: 0.80) |
| `topK` | Integer | Optional | Sample K high-probability candidates from the pool of generated token candidates. - 0 ≤ `topK` ≤ 128 (default: 0) |
| `maxCompletionTokens` | Integer | Optional | Maximum number of generated tokens - 0 ＜ `maxCompletionTokens` ≤ 32768 (default: 512) |
| `temperature` | Double | Optional | Degree of diversity for the generated tokens (higher values generate more diverse sentences) - 0.00 ≤ `temperature` ≤ 1.00 (default: 0.50) |
| `repetitionPenalty` | Double | Optional | Degree of penalty for generating the same token - 0.0 ＜ `repetitionPenalty` ≤ 2.0 (default: 1.1) - The higher the setting, the less likely it is to generate the same result repeatedly. - We recommend fine-tuning in increments of 0.05 between 1.0 and 1.1. |
| `stop` | Array | Optional | Character to abort token generation - [] (default) |
| `seed` | Integer | Optional | Adjust consistency level of output on model iterations. - 0: Randomize consistency level (default). - 1 ≤ `seed` ≤ 4294967295: `seed` value of result value you want to generate consistently, or a user-specified `seed` value |
| `thinking` | Object | Optional | Inference model configuration information |
| `thinking.effort` | String | Optional | Set whether to infer and the depth of the thought process. - `none` (valid value) - Can't be used concurrently with structured outputs. |
| `responseFormat` | Object | Optional | Response format the model outputs |
| `responseFormat.type` | String | Required | Response format type - `json` (valid value) |
| `responseFormat.schema` | Object | Required | Response format schema - Schema that fits the response format type. - JSON schema (object) (valid value) - See [Supported JSON schema](/docs/en/clovastudio-chatcompletionsv3-so#%EC%A7%80%EC%9B%90%ED%95%98%EB%8A%94JSONSchema). |
| `includeAiFilters` | Boolean | Optional | Whether to display the AI filter results (degree of the generated results in categories such as profanity, degradation/discrimination/hate, sexual harassment/obscenity, etc.) - `true` \| `false` (default) - `true`: Display - `false`: Not display |

#### `messages`

The following describes `messages`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | Enum | Required | Role of conversation messages - `system` \| `user` \| `assistant` \| - `system`: Directives that define roles - `user`: User utterances/questions - `assistant`: Answers to user utterances/questions |
| `content` | String | Required | Conversation message content - Enter text (string). |

#### 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.

Note

When entering some fields, check the following:

- `role`: You can only include one [Conversation message](/docs/en/clovastudio-chatcompletionsv3-so#messages) that is `system` per request.
- Structured outputs can't be requested at the same time as inference or function calling.
- Structured Outputs only support some of the JSON schemas.
  - `pattern` (validation keyword) is not supported.

### 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' \
--data '{
    "messages": [
      {
        "role": "system",
        "content": "- An AI assistant that responds to a predefined JSON schema format."
      },
      {
        "role": "user",
        "content":  "Today's high is 32 degrees, the low is 15 degrees, and there is a 30% chance of precipitation."
      }
    ],
    "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": "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.

| Headers | Required | Description |
| --- | --- | --- |
| `Content-Type` | - | Response data format - `application/json` |

### Response body

The response body includes the following data:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | Object | - | See [Response status](/docs/en/ai-naver-clovastudio-summary#%EC%9D%91%EB%8B%B5). |
| `result` | Object | - | Response result |
| `result.created` | Integer | - | Response date and time - Unix timestamp milliseconds format |
| `result.usage` | Object | - | Token usage |
| `result.usage.completionTokens` | Integer | - | Generated token count |
| `result.usage.promptTokens` | Integer | - | Number of input (prompt) tokens |
| `result.usage.totalTokens` | Integer | - | Total number of tokens - Number of generated tokens + number of input tokens |
| `result.message` | Object | - | Conversation messages |
| `result.message.role` | Enum | - | Role of conversation messages - `system` \| `user` \| `assistant` - `system`: Directives that define roles - `user`: User utterances/questions - `assistant`: Answers of the model |
| `result.message.content` | String | - | Content of conversation messages |
| `result.finishReason` | String | - | Reason for stopping token generation (generally passed to the last event) - `length` \| `stop` - `length`: Length limit - `stop`: Character specified in `stop` occurred during answer generation. - `tool_calls`: Model successfully completed tool call. |
| `result.seed` | Integer | - | Input seed value (Return a random value when 0 is entered or not entered) |
| `result.aiFilter` | Array | - | AI Filter result: [aiFilter](/docs/en/clovastudio-chatcompletionsv3-so#aiFilter) |

#### `aiFilter`

The following describes `aiFilter`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `groupName` | String | - | AI Filter category - `curse` \| `unsafeContents` - `curse`: Degradation, discrimination, hate, and profanity - `unsafeContents`: Sexual harassment, obscenity |
| `name` | String | - | AI Filter subcategory - `discrimination` \| `insult` \| `sexualHarassment` - `discrimination`: Degradation, discrimination, hate - `insult`: Profanity - `sexualHarassment`: Sexual harassment, obscenity |
| `score` | String | - | AI Filter score - `-1` \| `0` \| `1` \| `2` - `-1`: AI Filter error occurred. - `0`: Conversation messages are more likely to contain sensitive/hazardous language. - `1`: Conversation messages are likely to contain sensitive/hazardous language. - `2`: Conversation messages are unlikely to contain sensitive/hazardous language. |
| `result` | String | - | Whether AI Filter is operating properly - `OK` \| `ERROR` - `OK`: Normal operation - `ERROR`: Error occurred |

Note

AI Filter can analyze up to 500 characters. However, if the text being analyzed contains many unusual formats, emojis, or special characters, it may not be analyzed correctly.

### 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": {
        "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"
            }
        ]
    }
}
```

#### Failure

The following is a sample response upon a failed call.

- [Common client error troubleshooting (4xx)](/docs/en/clovastudio-troubleshoot-c4xx)
- [Common server error troubleshooting (5xx)](/docs/en/clovastudio-troubleshoot-c5xx)

## 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.

| Headers | Required | Description |
| --- | --- | --- |
| `Accept` | - | Response data format - `text/event-stream` |

### Response body

The response body includes the following data:

#### StreamingChatCompletionsTokenEvent

The following describes `StreamingChatCompletionsTokenEvent`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created` | Integer | - | Response timestamp |
| `usage` | Object | - | Token usage |
| `usage.promptTokens` | Integer | - | Number of input (prompt) tokens |
| `usage.completionTokens` | Integer | - | Generated token count |
| `message` | Object | - | Conversation messages |
| `message.role` | Enum | - | Conversation message role - `user` \| `assistant` - `user`: User's utterance or question - `assistant`: Model's answer |
| `message.content` | String | - | Content of conversation messages |
| `finishReason` | String | - | Reason for stopping token generation (typically passed to the last event) - `length` \| `stop` - `length`: Length limit - `stop`: Character specified in `stop` occurred during answer generation. |

#### StreamingChatCompletionsResultEvent

The following describes `StreamingChatCompletionsResultEvent`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created` | Integer | - | Response timestamp |
| `usage` | Object | - | Token usage |
| `usage.promptTokens` | Integer | - | Number of input (prompt) tokens |
| `usage.completionTokens` | Integer | - | Generated token count |
| `usage.totalTokens` | Integer | - | Total number of tokens - Number of generated tokens + number of input tokens |
| `message` | Object | - | Conversation messages |
| `message.role` | Enum | - | Conversation message role - `user` \| `assistant` - `user`: User's utterance or question - `assistant`: Model's answer |
| `message.content` | String | - | Content of conversation messages |
| `finishReason` | String | - | Reason for stopping token generation (typically passed to the last event) - `length` \| `stop` - `length`: Length limit - `stop`: Character specified in `stop` occurred during answer generation. |
| `aiFilter` | Array | - | AI Filter result: [aiFilter](/docs/en/clovastudio-chatcompletionsv3-so#aiFilter) |

#### ErrorEvent

The following describes `ErrorEvent`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | Object | - | See [Response status](/docs/en/ai-naver-clovastudio-summary#%EC%9D%91%EB%8B%B5). |
| `status.code` | Object | - | Response status code - See [CLOVA Studio troubleshooting](/docs/en/clovastudio-troubleshoot). |
| `status.message` | Object | - | Response status message - See [CLOVA Studio troubleshooting](/docs/en/clovastudio-troubleshoot). |

#### SignalEvent

The following describes `SignalEvent`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | String | - | Signal data information to pass |

### 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)](/docs/en/clovastudio-troubleshoot-c4xx)
- [Common server error troubleshooting (5xx)](/docs/en/clovastudio-troubleshoot-c5xx)