Structured Outputs

Prev Next

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

Structured Outputs를 지원하여 원하는 JSON Schema 형식의 출력 결과를 생성할 수 있는 v3 Chat Completions에 대해 설명합니다.

요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

메서드 URI
POST /v3/chat-completions/{modelName}

요청 헤더

CLOVA Studio API에서 공통으로 사용하는 헤더에 대한 정보는 CLOVA Studio 요청 헤더를 참조해 주십시오.

요청 경로 파라미터

요청 경로 파라미터에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
modelName Enum Required 모델 이름
  • <예시> HCX-007
참고

Structured Outputs는 HCX-007 모델에서만 사용할 수 있습니다.

요청 바디

요청 바디에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
messages Array Required 대화 메시지: messages
topP Double Optional 생성 토큰 후보군을 누적 확률을 기반으로 샘플링
  • 0.00 ＜ topP ≤ 1.00 (기본값: 0.80)
topK Integer Optional 생성 토큰 후보군에서 확률이 높은 K개를 후보로 지정하여 샘플링
  • 0 ≤ topK ≤ 128 (기본값: 0)
maxCompletionTokens Integer Optional 최대 생성 토큰 수
  • 0 ＜ maxCompletionTokens ≤ 32768 (기본값: 512)
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 값
thinking Object Optional 추론 모델 설정 정보
thinking.effort String Optional 추론 여부 및 사고 과정 깊이 설정
  • none (유효 값)
  • Structured Outputs와 동시 사용 불가
responseFormat Object Optional 모델이 출력하는 답변 형식
responseFormat.type String Required 답변 형식 타입
  • json (유효 값)
responseFormat.schema Object Required 답변 형식 스키마
includeAiFilters Boolean Optional AI 필터(생성된 결괏값에 대해 욕설, 비하/차별/혐오, 성희롱/음란 등 카테고리별로 해당하는 정도) 결과 표시 여부
  • true | false (기본값)
    • true: 표시
    • false: 표시 안 함

messages

messages에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
role Enum Required 대화 메시지 역할
  • system | user | assistant |
    • system: 역할을 규정하는 지시문
    • user: 사용자의 발화 또는 질문
    • assistant: 사용자의 발화 또는 질문에 대한 답변
content String Required 대화 메시지 내용
  • 텍스트 입력(String)

지원하는 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: 나열된 스키마 중 하나 이상을 만족해야 함
참고

일부 필드 입력 시 다음 내용을 확인해 주십시오.

  • role: system인 대화 메시지는 요청당 1개만 포함할 수 있습니다.
  • Structured Outputs와 추론 또는 Function calling을 동시에 요청할 수 없습니다.
  • Structured Outputs는 JSON schema의 일부만 지원합니다.
    • pattern(Validation Keyword)는 지원하지 않습니다.

요청 예시

요청 예시는 다음과 같습니다.

curl --location --request POST 'https://clovastudio.stream.gov-ntruss.com/testapp/v3/chat-completions/HCX-007' \
--header 'Authorization: Bearer <API-KEY>' \
--header 'X-NCP-CLOVASTUDIO-REQUEST-ID: <X-NCP-CLOVASTUDIO-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 - 응답 데이터의 형식
  • 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

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

실패

호출이 실패한 경우의 응답 예시는 다음과 같습니다.

응답 스트림

생성되는 토큰을 하나씩 출력하도록 토큰 스트리밍을 사용할 수 있습니다. 토큰 스트리밍 형식을 설명합니다.

응답 헤더

응답 헤더에 대한 설명은 다음과 같습니다.

헤더 필수 여부 설명
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 필터 결과: aiFilter

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": "{\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}}

실패

호출이 실패한 경우의 응답 예시는 다음과 같습니다.

사업자등록번호: 129-86-31394 통신판매업신고번호:제2009-경기성남-0510호
대표이사: 김유원 주소: 경기도 성남시 분당구 불정로 6네이버 그린팩토리 17~26층, 13561 고객지원 대표전화: 1833-5055
© NAVER Cloud Corp. All Rights Reserved.