Chat Completions v3

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

HCX-DASH-002 모델을 활용하여 대화형 문장을 생성합니다.

참고

해당 기능은 플레이그라운드에서 제공하지 않으며, API로만 지원합니다.
HCX-003, HCX-DASH-001 모델은 해당 API를 이용할 수 없습니다.

요청

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

메서드	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으로 지정 시 응답 결과를 스트림 형태로 반환합니다.
응답 스트림 이용 시 API URL은 https://clovastudio.stream.gov-ntruss.com/으로 사용해 주십시오.

요청 경로 파라미터

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

필드	타입	필수 여부	설명
`modelName`	String	Conditional	모델 이름 모델을 사용하여 문장 생성을 하려는 경우

요청 바디

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

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

참고

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

입력 토큰과 출력 토큰의 합은 8,192 토큰을 초과할 수 없습니다.
입력 토큰은 최대 7,600 토큰까지 가능합니다.
모델에 요청할 출력 토큰(maxTokens)은 최대 4,096 토큰까지 가능합니다.

`messages`

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

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

요청 예시

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

curl --location --request POST 'https://clovastudio.stream.gov-ntruss.com/testapp/v3/chat-completions/{modelName}' \
--header 'Authorization: Bearer <API-KEY>' \
--header 'X-NCP-CLOVASTUDIO-REQUEST-ID: <X-NCP-CLOVASTUDIO-REQUEST-ID>' \
--header 'Content-Type: application/json' \
--header 'Accept: text/event-stream' \
--data '{
        "messages": [ {
            "role" : "system",
            "content" : "시스템 프롬프트"
             }, {
            "role" : "user",
            "content" : "사용자 입력"
            }, {
            "role" : "assistant",
            "content" : "어시스턴트 "
        } ],
        "temperature": 0.5,
        "topK": 0,
        "topP": 0.8,
        "repetitionPenalty": 1.1,
        "stop": [],
        "maxTokens": 100,
        "includeAiFilters": false
    }'

응답

응답 형식을 설명합니다.

응답 헤더

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

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

응답 바디

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

필드	타입	필수 여부	설명
`status`	Object	-	응답 상태
`result`	Object	-	응답 결과
`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 에 지정한 문자 출현 또는 모델이 정상적으로 생성 완료
`result.created`	Integer	-	응답 날짜 (Unix timestamp 형식)
`result.seed`	Integer	-	입력 seed 값(0 입력 또는 미입력 시 랜덤 값 반환)
`result.usage`	Object	-	토큰 수 정보
`result.usage.promptTokens`	Integer	-	입력 토큰 수
`result.usage.completionTokens`	Integer	-	생성 토큰 수
`result.usage.totalTokens`	Integer	-	전체 토큰 수(`promptTokens`+`completionTokens`
`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": "문구: 내 삶의 기록, 내 생각의 흔적, 내 꿈의 시작. 다이어리가 당신의 이야기와 함께합니다."
        },
        "finishReason": "stop",
        "created": 1733997272,
        "seed": 2499308148,
        "usage": {
            "promptTokens": 190,
            "completionTokens": 30,
            "totalTokens": 220
         },
        "aiFilter": [
            {
             "groupName": "curse",
             "name": "insult",
             "score": "1"
            },
            {
             "groupName": "curse",
             "name": "discrimination",
             "score": "0"
            },
            {
             "groupName": "unsafeContents",
             "name": "sexualHarassment",
             "score": "2"
            }
          ]
    }
}

실패

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

응답 스트림

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

응답 헤더

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

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

응답 바디

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

StreamingChatCompletionsResultEvent

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

필드	타입	필수 여부	설명
`id`	String	-	요청을 식별하는 이벤트 아이디
`message`	Object	-	대화 메시지
`message.role`	Enum	-	대화 메시지 역할 `system` \| `user` \| `assistant` `system`: 역할을 규정하는 지시문 `user`: 사용자의 발화 또는 질문 `assistant`: 모델의 답변
`message.content`	String	-	대화 메시지 내용
`finishReason`	String	-	결괏값 생성 중단 이유 `length` \| `stop` `length`: 설정한 최대 토큰 수 도달 `stop`: 답변 생성 중 stop 에 지정한 문자 출현 또는 모델이 정상적으로 생성 완료
`created`	Integer	-	응답 날짜 (Unix timestamp 형식)
`seed`	Integer	-	입력 seed 값(0 입력 또는 미입력 시 랜덤 값 반환)
`usage`	Object	-	토큰 수 정보
`usage.promptTokens`	Integer	-	입력 토큰 수
`usage.completionTokens`	Integer	-	생성 토큰 수
`result.usage.totalTokens`	Integer	-	전체 토큰 수(`promptTokens`+`completionTokens`
`aiFilter`	Array	-	AI 필터 결과

StreamingChatCompletionsTokenEvent

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

필드	타입	필수 여부	설명
`id`	String	-	요청을 식별하는 이벤트 아이디
`message`	Object	-	대화 메시지
`message.role`	Enum	-	대화 메시지 역할 `system` \| `user` \| `assistant` `system`: 역할을 규정하는 지시문 `user`: 사용자의 발화 또는 질문 `assistant`: 모델의 답변
`message.content`	String	-	대화 메시지 내용
`finishReason`	String	-	결괏값 생성 중단 이유 `length` \| `stop` `length`: 설정한 최대 토큰 수 도달 `stop`: 답변 생성 중 stop 에 지정한 문자 출현 또는 모델이 정상적으로 생성 완료
`created`	Integer	-	응답 날짜 (Unix timestamp 형식)
`seed`	Integer	-	입력 seed 값(0 입력 또는 미입력 시 랜덤 값 반환)
`usage`	Object	-	토큰 수 정보

ErrorEvent

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

필드	타입	필수 여부	설명
`status`	Object	-	응답 상태

SignalEvent

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

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

응답 예시

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

성공

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

id: 484f9a63-8231-441b-b2dc-683ed135dd03
event: signal
data:
{
  "data": "[DONE]"
}

id: 8138bd06-9d29-43fb-9a91-72bc12bd31a1
event: result
data:
{
  "message": {
      "role": "assistant",
      "content": "문구: 생각을 기록하고, 꿈을 그리다. 내 삶의 이야기, 다이어리가 함께합니다."
  },
  "finishReason": "stop",
  "created": 1734016821,
  "seed": 1342914828,
  "usage": {
      "promptTokens": 98,
      "completionTokens": 212,
      "totalTokens": 310
 }
}

id: 9517637c-17aa-4a4a-a076-3fde680a953e
event: token
data:
{
  "message": {
      "role": "assistant",
      "content": "."
  },
  "finishReason": null,
  "created": 1734016821,
  "seed": 1342914828,
  "usage": null
}

id: 1dd8d882-4b8c-4435-abc5-f58bdbbc17a8
event: token
data:
{
  "message": {
      "role": "assistant",
      "content": "합니다"
  },
  "finishReason": null,
  "created": 1734016821,
  "seed": 1342914828,
  "usage": null
}
…

실패

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