--- title: "Structured Outputs" slug: "clovastudio-chatcompletionsv3-so" updated: 2026-09-17T09:15:56Z published: 2026-09-17T09:15:56Z 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

Classic/VPC 환경에서 이용 가능합니다.

Structured Outputs를 지원하여 원하는 JSON Schema 형식의 출력 결과를 생성할 수 있는 v3 Chat Completions에 대해 설명합니다. ## 요청 요청 형식을 설명합니다. 요청 형식은 다음과 같습니다. | 메서드 | URI | | --- | --- | | POST | /v3/chat-completions/{modelName} | ### 요청 헤더 CLOVA Studio API에서 공통으로 사용하는 헤더에 대한 정보는 [CLOVA Studio 요청 헤더](/docs/ai-naver-clovastudio-summary#요청헤더)를 참조해 주십시오. ### 요청 경로 파라미터 요청 경로 파라미터에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `modelName` | Enum | Required | 모델 이름 | :::(Info) (참고) Structured Outputs는 HCX-007 모델에서만 사용할 수 있습니다. ::: ### 요청 바디 요청 바디에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `messages` | Array | Required | 대화 메시지: [messages](#messages) | | `topP` | Double | Optional | 생성 토큰 후보군을 누적 확률을 기반으로 샘플링 | | `topK` | Integer | Optional | 생성 토큰 후보군에서 확률이 높은 K개를 후보로 지정하여 샘플링 | | `maxCompletionTokens` | Integer | Optional | 최대 생성 토큰 수 | | `temperature` | Double | Optional | 생성 토큰에 대한 다양성 정도(설정값이 높을수록 다양한 문장 생성) | | `repetitionPenalty` | Double | Optional | 같은 토큰을 생성하는 것에 대한 패널티 정도| | `stop` | Array | Optional | 토큰 생성 중단 문자 | | `seed` | Integer | Optional | 모델 반복 실행 시 결괏값의 일관성 수준 조정 | | `thinking` | Object | Optional | 추론 모델 설정 정보 | | `thinking.effort` | String | Optional | 추론 여부 및 사고 과정 깊이 설정 | | `responseFormat` | Object | Optional | 모델이 출력하는 답변 형식 | | `responseFormat.type` | String | Required | 답변 형식 타입| | `responseFormat.schema` | Object | Required | 답변 형식 스키마 | | `includeAiFilters` | Boolean | Optional | AI 필터(생성된 결괏값에 대해 욕설, 비하/차별/혐오, 성희롱/음란 등 카테고리별로 해당하는 정도) 결과 표시 여부 | #### `messages` `messages`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `role` | Enum | Required | 대화 메시지 역할| | `content` | String | Required | 대화 메시지 내용 | #### 지원하는 JSON Schema 지원하는 JSON Schema에 대한 설명은 다음과 같습니다. * 타입 * `string`, `number`, `boolean`, `integer`, `object`, `array` * 제약 키워드(Validation Keyword) * 문자열 (`string`) * `format`: 정의된 형식 중 하나여야 함 * <예시> ```json "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`: 나열된 스키마 중 하나 이상을 만족해야 함 :::(Info) (참고) 일부 필드 입력 시 다음 내용을 확인해 주십시오. * `role`: `system`인 [대화 메시지](#messages)는 요청당 1개만 포함할 수 있습니다. * Structured Outputs와 추론 또는 Function calling을 동시에 요청할 수 없습니다. * Structured Outputs는 JSON schema의 일부만 지원합니다. * `pattern`(Validation Keyword)는 지원하지 않습니다. ::: ### 요청 예시 요청 예시는 다음과 같습니다. ```shell 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" ] } } }' ``` ## 응답 응답 형식을 설명합니다. ### 응답 헤더 응답 헤더에 대한 설명은 다음과 같습니다. | 헤더 | 필수 여부 | 설명 | | --- | --- | --- | | `Content-Type` | - | 응답 데이터의 형식 | ### 응답 바디 응답 바디에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `status` | Object | - | [응답 상태](/docs/ai-naver-clovastudio-summary#응답) 참조 | | `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) | #### `aiFilter` `aiFilter`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `groupName` | String | - | AI 필터 카테고리 | | `name` | String | - | AI 필터 세부 카테고리 | | `score` | String | - | AI 필터 점수 | | `result` | String | - | AI 필터 정상 작동 여부 | :::(Info) (참고) AI Filter는 최대 500자까지 분석할 수 있습니다. 단, 분석 대상 텍스트에 비정상적인 형식, 이모티콘, 특수 문자 등이 많은 경우, 정상적으로 분석되지 않을 수 있습니다. ::: ### 응답 예시 응답 예시는 다음과 같습니다. #### 성공 호출이 성공한 경우의 응답 예시는 다음과 같습니다. ```json { "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)](/docs/clovastudio-troubleshoot-c4xx) * [서버 공통 오류 문제(5xx)](/docs/clovastudio-troubleshoot-c5xx) ## 응답 스트림 생성되는 토큰을 하나씩 출력하도록 토큰 스트리밍을 사용할 수 있습니다. 토큰 스트리밍 형식을 설명합니다. ### 응답 헤더 응답 헤더에 대한 설명은 다음과 같습니다. | 헤더 | 필수 여부 | 설명 | | --- | --- | --- | | `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 필터 결과: [aiFilter](#aiFilter) | #### ErrorEvent `ErrorEvent`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `status` | Object | - | [응답 상태](/docs/ai-naver-clovastudio-summary#응답) 참조 | | `status.code` | Object | - | 응답 상태 코드 | | `status.message` | Object | - | 응답 상태 메시지 | #### SignalEvent `SignalEvent`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `data` | String | - | 전달할 시그널 데이터 정보 | ### 응답 예시 응답 예시는 다음과 같습니다. #### 성공 호출이 성공한 경우의 응답 예시는 다음과 같습니다. ```json 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)](/docs/clovastudio-troubleshoot-c4xx) * [서버 공통 오류 문제(5xx)](/docs/clovastudio-troubleshoot-c5xx)