Structured Outputs

Prev Next

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

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

요청

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

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

요청 헤더

요청 헤더에 대한 설명은 다음과 같습니다.

헤더 필수 여부 설명
Authorization Required 인증을 위한 API 키 <예시> Bearer nv-************
X-NCP-CLOVASTUDIO-REQUEST-ID Optional 요청에 대한 아이디
Content-Type Required 요청 데이터의 형식
  • application/json
Accept Conditional 응답 데이터의 형식
  • text/event-stream
참고

응답 결과는 기본적으로 JSON 형태로 반환되지만, Accept를 text/event-stream으로 지정 시 응답 결과를 스트림 형태로 반환합니다.

요청 경로 파라미터

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

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

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

요청 바디

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

필드 타입 필수 여부 설명
messages Array Required 대화 메시지
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와 동시 사용 불가
response_format Object Optional 모델이 출력하는 답변 형식
response_format.type String Required 답변 형식 타입
  • json_schema (유효 값)
response_format.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.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": "- 친절하게 답변하는 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에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
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 필터 결과

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

실패

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