MENU
      Chat Completions

        Chat Completions


        기사 요약

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

        HyperCLOVA X 모델을 사용하여 대화형 문장을 생성합니다.

        요청

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

        메서드URI
        POST
        • /v1/chat-completions/{modelName}
          • 모델을 사용하여 문장 생성
        • /v1/tasks/{taskId}/chat-completions
        • /v2/tasks/{taskId}/chat-completions
          • 튜닝 학습한 작업을 사용하여 문장 생성

        요청 헤더

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

        헤더필수 여부설명
        AuthorizationRequired인증을 위한 API 키 <예시> Bearer nv-************
        X-NCP-CLOVASTUDIO-REQUEST-IDOptional요청에 대한 아이디
        Content-TypeRequired요청 데이터의 형식
        • application/json
        AcceptConditional응답 데이터의 형식
        • text/event-stream
        참고
        • 응답 결과는 기본적으로 JSON 형태로 반환되지만, Accepttext/event-stream으로 지정 시 응답 결과를 스트림 형태로 반환합니다.
        • 응답 스트림 이용 시 API URL은 https://clovastudio.stream.ntruss.com/으로 사용해 주십시오.

        요청 경로 파라미터

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

        필드타입필수 여부설명
        modelNameStringConditional모델 이름
        • 모델을 사용하여 문장 생성을 하려는 경우
        • <예시> HCX-003
        taskIdStringConditional학습 아이디
        • 튜닝 학습한 작업을 사용하여 문장 생성을 하려는 경우
        • 학습 생성 API의 응답 바디에서 확인 가능

        요청 바디

        응답 바디에 대한 설명은 다음과 같습니다.

        필드타입필수 여부설명
        messagesArrayRequired대화 메시지
        temperatureDoubleOptional생성 토큰에 대한 다양성 정도(설정값이 높을수록 다양한 문장 생성)
        • 0.00 < temperature ≤ 1.00 (기본값: 0.50)
          • 소수점 둘째 자리까지 표기
        topKIntegerOptional생성 토큰 후보군에서 확률이 높은 K개를 후보로 지정하여 샘플링
      • 0 ≤ topK ≤ 128 (기본값: 0)
      • topPDoubleOptional생성 토큰 후보군을 누적 확률을 기반으로 샘플링
        • 0.00 < topP ≤ 1.00 (기본값: 0.80)
          • 소수점 둘째 자리까지 표기
        repeatPenaltyDoubleOptional같은 토큰을 생성하는 것에 대한 패널티 정도(설정값이 높을수록 같은 결괏값을 반복 생성할 확률 감소)
      • 0.0 < repeatPenalty ≤ 10.0 (기본값: 5.0)
      • stopBeforeArrayOptional토큰 생성 중단 문자
      • [](기본값)
      • maxTokensIntegerOptional최대 생성 토큰 수
      • 0 < maxTokens ≤ 4096 (기본값: 100)
      • includeAiFiltersBooleanOptionalAI 필터(생성된 결괏값에 대해 욕설, 비하/차별/혐오, 성희롱/음란 등 카테고리별로 해당하는 정도) 결과 표시 여부
        • false (기본값) | true
          • false: 표시 안 함
          • true: 표시
        seedIntegerOptional모델 반복 실행 시 결괏값의 일관성 수준 조정
        • 0: 일관성 수준 랜덤 적용 (기본값)
        • 1 ≤ seed ≤ 4294967295: 일관되게 생성하고자 하는 결괏값의 seed 값 또는 사용자가 지정하고자 하는 seed
        참고

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

        • HCX-003
          • 입력 토큰과 출력 토큰의 합은 8192 토큰을 초과할 수 없습니다.
          • 입력 토큰은 최대 7600 토큰까지 가능합니다.
          • 모델에 요청할 출력 토큰(maxTokens)은 최대 4096 토큰까지 가능합니다.
        • HCX-DASH-001
          • 입력 토큰과 출력 토큰의 합은 4096 토큰을 초과할 수 없습니다.
          • 입력 토큰은 최대 3500 토큰까지 가능합니다.
          • 모델에 요청할 출력 토큰(maxTokens)은 최대 4096 토큰까지 가능합니다.

        messages

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

        필드타입필수 여부설명
        roleEnumRequired대화 메시지 역할
        • system | user | assistant
          • system: 역할을 규정하는 지시문
          • user: 사용자의 발화 또는 질문
          • assistant: 사용자의 발화 또는 질문에 대한 답변
        contentStringRequired대화 메시지 내용

        요청 예시

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

        curl --location --request POST 'https://clovastudio.stream.ntruss.com/testapp/v1/chat-completions/HCX-003' \
        --header 'Authorization: Bearer {API Key}' \
        --header 'X-NCP-CLOVASTUDIO-REQUEST-ID: {Request ID}' \
        --header 'Content-Type: application/json' \
        --header 'Accept: text/event-stream' \
        --data '{
          "topK" : 0,
          "includeAiFilters" : true,
          "maxTokens" : 256,
          "temperature" : 0.5,
          "messages" : [ {
            "role" : "system",
            "content" : "test"
          }, {
            "role" : "user",
            "content" : "테스트 해보자."
          }, {
            "role" : "assistant",
            "content" : "알겠습니다. 무엇을 테스트해볼까요?"
          } ],
          "stopBefore" : [ ],
          "repeatPenalty" : 5.0,
          "topP" : 0.8
        }'
        Shell

        응답

        응답 형식을 설명합니다.

        응답 헤더

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

        헤더필수 여부설명
        Content-Type-응답 데이터의 형식
        • application/json

        응답 바디

        응답 바디에 대한 설명은 다음과 같습니다.

        필드타입필수 여부설명
        statusObject-응답 상태
        resultObject-응답 결과
        result.messageObject-대화 메시지
        result.message.roleEnum-대화 메시지 역할
        • system | user | assistant
          • system: 역할을 규정하는 지시문
          • user: 사용자의 발화 또는 질문
          • assistant: 모델의 답변
        result.message.contentString-대화 메시지 내용
        result.stopReasonEnum-결괏값 생성 중단 이유
        • length | end_token | stop_before
          • length: 길이 제한
          • end_token: 토큰 수 제한
          • stop_before:
          • 모델이 자체적으로 출력을 종료
          • 답변 생성 중 stopBefore에 지정한 문자 출현
        result.inputLengthInteger-입력 토큰 수(과금 기준으로 end of turn과 같은 특수 토큰도 포함)
        result.outputLengthInteger-응답 토큰 수
        result.seedint-입력 seed 값(0 입력 또는 미입력 시 랜덤 값 반환)
        result.aiFilterArray-AI 필터 결과

        aiFilter

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

        필드타입필수 여부설명
        groupNameString-AI 필터 카테고리
        • curse | unsafeContents
          • curse: 비하, 차별, 혐오 및 욕설
          • unsafeContents: 성희롱, 음란
        nameString-AI 필터 세부 카테고리
        • discrimination | insult | sexualHarassment
          • discrimination: 비하, 차별, 혐오
          • insult: 욕설
          • sexualHarassment: 성희롱, 음란
        scoreString-AI 필터 점수
        • -1 | 0 | 1 | 2
          • -1: AI 필터 오류 발생
          • 0: 대화 메시지에 민감/위험 표현 포함 가능성 높음
          • 1: 대화 메시지에 민감/위험 표현 포함 가능성 있음
          • 2: 대화 메시지에 민감/위험 표현 포함 가능성 낮음
        resultString-AI 필터 정상 작동 여부
        • OK | ERROR
          • OK: 정상 작동
          • ERROR: 오류 발생
        참고

        AI Filter는 최대 500자까지 분석할 수 있습니다. 단, 분석 대상 텍스트에 비정상적인 형식, 이모티콘, 특수 문자 등이 많은 경우, 정상적으로 분석되지 않을 수 있습니다.

        응답 예시

        응답 예시는 다음과 같습니다.

        성공

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

        {
          "status": {
            "code": "20000",
            "message": "OK"
          },
          "result": {
            "message": {
              "role": "assistant",
              "content": "문구: 오늘 하루 있었던 일들을 기록하며, 내일을 준비하세요. 다이어리는 당신의 삶을 더욱 풍요롭게 만들어 줄 것입니다.\n"
            },
            "stopReason": "LENGTH",
            "inputLength": 100,
            "outputLength": 10,
            "aiFilter": [
              {
                "groupName": "curse",
                "name": "insult",
                "score": "1"
              },
              {
                "groupName": "curse",
                "name": "discrimination",
                "score": "0"
              },
              {
                "groupName": "unsafeContents",
                "name": "sexualHarassment",
                "score": "2"
              }
            ]
          }
        }
        JSON

        실패

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

        응답 스트림

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

        응답 헤더

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

        헤더필수 여부설명
        Accept-응답 데이터의 형식
        • text/event-stream

        응답 바디

        응답 바디에 대한 설명은 다음과 같습니다.

        StreamingChatCompletionsResultEvent

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

        필드타입필수 여부설명
        messageObject-대화 메시지
        message.roleEnum-대화 메시지 역할
        • system | user | assistant
          • system: 역할을 규정하는 지시문
          • user: 사용자의 발화 또는 질문
          • assistant: 모델의 답변
        message.contentString-대화 메시지 내용
        stopReasonEnum-결괏값 생성 중단 이유
        • length | end_token | stop_before
          • length: 길이 제한
          • end_token: 토큰 수 제한
          • stop_before: 답변 생성 중 stopBefore에 지정한 문자 출현
        inputLengthInteger-입력 토큰 수(과금 기준으로 end of turn과 같은 특수 토큰도 포함)
        outputLengthInteger-응답 토큰 수(과금 기준으로 end of turn과 같은 특수 토큰도 포함)
        aiFilterArray-AI 필터 결과

        StreamingChatCompletionsTokenEvent

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

        필드타입필수 여부설명
        idString-요청을 식별하는 이벤트 아이디
        messageObject-대화 메시지
        message.roleEnum-대화 메시지 역할
        • system | user | assistant
          • system: 역할을 규정하는 지시문
          • user: 사용자의 발화 또는 질문
          • assistant: 모델의 답변
        message.contentString-대화 메시지 내용
        inputLengthInteger-입력 토큰 수(과금 기준으로 end of turn과 같은 특수 토큰도 포함)
        outputLengthInteger-응답 토큰 수(과금 기준으로 end of turn과 같은 특수 토큰도 포함)
        stopReasonEnum-결괏값 생성 중단 이유
        • length | end_token | stop_before
          • length: 길이 제한
          • end_token: 토큰 수 제한
          • stop_before:
            • 모델이 정상적으로 생성 완료
            • 답변 생성 중 stopBefore에 지정한 문자 출현

        ErrorEvent

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

        필드타입필수 여부설명
        statusObject-응답 상태

        SignalEvent

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

        필드타입필수 여부설명
        dataString-전달할 시그널 데이터 정보

        응답 예시

        응답 예시는 다음과 같습니다.

        성공

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

        id: aabdfe-dfgwr-edf-hpqwd-f2asd-g
        event: token
        data: {"message": {"role": "assistant", "content": “안”}}
        
        id: aabdfe-dfgwr-edf-hpqwd-f1asd-g
        event: result
        data: {"message": {"role": "assistant", "content": “녕”}}
        Python

        실패

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


        이 문서가 도움이 되었습니까?

        Changing your password will log you out immediately. Use the new password to log back in.
        First name must have atleast 2 characters. Numbers and special characters are not allowed.
        Last name must have atleast 1 characters. Numbers and special characters are not allowed.
        Enter a valid email
        Enter a valid password
        Your profile has been successfully updated.