MENU
      Login
          Login
          내용 x
          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 형태로 반환되지만, Accept를 text/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

              실패

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

              이 문서가 도움이 되었습니까?
              Change password!
              Changing your password will log you out immediately. Use the new password to log back in.
              Change profile
              Success!
              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.
              Logout