Korean

Completions

인쇄
공유
PDF

Completions

인쇄
공유
PDF

기사 요약

이 요약이 도움이 되었나요?

의견을 보내 주셔서 감사합니다.

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

플레이그라운드의 일반 모드(LK 모델)를 활용하여 대화형 문장을 생성합니다.

요청

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

메서드	URI
POST	/v1/completions/{modelName} 모델을 사용하여 문장 생성을 하려는 경우 /v1/tasks/{taskId}/completions 튜닝 학습한 작업을 사용하여 문장 생성을 하려는 경우

요청 헤더

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

헤더	필수 여부	설명
`X-NCP-CLOVASTUDIO-API-KEY`	Required	테스트 앱이나 서비스 앱 생성 시 발급받은 API Key
`X-NCP-APIGW-API-KEY`	Required	테스트 앱이나 서비스 앱 생성 시 발급받은 API Gateway Key
`X-NCP-CLOVASTUDIO-REQUEST-ID`	Optional	요청에 대한 아이디
`Content-Type`	Required	요청 데이터의 형식 `application/json`

요청 경로 파라미터

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

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

요청 바디

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

필드	타입	필수 여부	설명
`text`	String	Required	사용자 입력값(프롬프트) 프롬프트를 바탕으로 새로운 문장 생성
`topK`	Integer	Optional	생성 토큰 후보군에서 확률이 높은 K개를 후보로 지정하여 샘플링 0 ≤ `topK` ≤ 128 (기본값: 0)
`topP`	Float	Optional	생성 토큰 후보군을 누적 확률을 기반으로 샘플링 0.00 ＜ `topP` ≤ 1.00 (기본값: 0.80) 소수점 둘째 자리까지 표기
`repeatPenalty`	Float	Optional	같은 토큰을 생성하는 것에 대한 패널티 정도(설정값이 높을수록 같은 결괏값을 반복 생성할 확률 감소) 0.0 ＜ `repeatPenalty` ≤ 10.0 (기본값: 5.0)
`stopBefore`	Array	Optional	토큰 생성 중단 문자 [](기본값)
`restart`	String	Optional	생성된 결괏값 뒤에 붙일 텍스트
`start`	String	Optional	사용자 입력값 뒤에 붙일 텍스트
`maxTokens`	Integer	Optional	최대 생성 토큰 수 0 ＜ `maxTokens` ≤ 2048 (기본값: 100)
`includeTokens`	Boolean	Optional	응답에 input_tokens, output_tokens 포함 여부 `false` \| `true` (기본값) `false`: 포함 안 함 `true`: 포함
`temperature`	Float	Optional	생성 토큰에 대한 다양성 정도(설정값이 높을수록 다양한 문장 생성) 0.00 ＜ `temperature` ≤ 1.00 (기본값: 0.50) 소수점 둘째 자리까지 표기
`includeAiFilters`	Boolean	Optional	AI 필터(생성된 결괏값에 대해 욕설, 비하/차별/혐오, 성희롱/음란 등 카테고리별로 해당하는 정도) 결과 표시 여부 `false` (기본값) \| `true` `false`: 표시 안 함 `true`: 표시

참고

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

text: 입력한 토큰 수와 maxTokens에서 입력한 토큰 수의 합은 2,048 토큰을 초과할 수 없습니다.

요청 예시

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

curl --location --request POST 'https://clovastudio.apigw.ntruss.com/testapp/v1/completions/LK-D2' \
--header 'X-NCP-CLOVASTUDIO-API-KEY: {CLOVA Studio API Key}' \
--header 'X-NCP-APIGW-API-KEY: {API Gateway API Key}' \
--header 'X-NCP-CLOVASTUDIO-REQUEST-ID: {Request ID}' \
--header 'Content-Type: application/json' \
--data '{
  "start": "\n영어: ",
  "stopBefore": ["\n한국어: "],
  "text": "한국어: 사과\n영어: Apple\n한국어: 바나나",
  "includeAiFilters": true
}'

응답

응답 형식을 설명합니다.

응답 헤더

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

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

응답 바디

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

필드	타입	필수 여부	설명
`status`	Object	-	응답 상태
`result`	Object	-	응답 결과
`result.text`	String	-	생성 토큰 (프롬프트와 생성된 결괏값)
`result.stopReason`	String	-	결괏값 생성 중단 이유 `length` \| `end_token` \| `stop_before` `length`: 길이 제한 `end_token`: 토큰 수 제한 `stop_before`: 답변 생성 중 `stopBefore`에 지정한 문자 출현
`result.startLength`	Integer	-	입력 토큰 수
`inputText`	String	-	사용자 입력값 (프롬프트)
`result.inputLength`	Integer	-	입력 토큰 수(과금 기준으로 end of turn과 같은 특수 토큰도 포함)
`result.inputTokens`	Array	-	입력 토큰 정보
`result.outputText`	Integer	-	생성 결괏값
`result.outputLength`	Integer	-	생성 토큰 수
`result.outputTokens`	Array	-	생성 토큰 정보
`result.probs`	Array	-	응답 토큰의 후보 토큰 및 후보 토큰의 확률값
`result.ok`	Boolean	-	응답 성공 여부 `false` \| `true` `false`: 응답 실패. 오류 메시지 반환 `true`: 응답 성공
`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": {
        "text": "감성적인 마케팅 문구를 작성하시오\n\n제품: 로션\n문구: 피부에 닿는 순간 흡수되는 촉촉함\n###\n제품: 다이어리\n문구: 내가 나에게 주는 선물",
        "stopReason": "end_token",
        "startLength": 33,
        "inputText": "감성적인 마케팅 문구를 작성하시오\n\n제품: 로션\n문구: 피부에 닿는 순간 흡수되는 촉촉함\n###\n제품: 다이어리",
        "inputLength": 33,
        "inputTokens": ["감","성적","인"," 마케팅"," 문구","를"," 작성","하시오","\n",
        "\n","제품",":"," 로션","\n","문구",":"," 피부","에"," 닿는"," 순간"," 흡수","되는"," 촉촉함",
        "\n","##","#","\n","제품",":"," 다이어리","\n","문구",":"
        ],
        "outputText": "\n문구: 내가 나에게 주는 선물",
        "outputLength": 7,
        "outputTokens": ["내","가","나","에게","주는","선물",""
        ],
        "probs": [],
        "ok": true,
        "aiFilter": [
            {
                "groupName": "curse",
                "name": "insult",
                "score": "2"
            },
            {
                "groupName": "curse",
                "name": "discrimination",
                "score": "1"
            },
            {
                "groupName": "unsafeContents",
                "name": "sexualHarassment",
                "score": "2"
            }
        ]
    }
}

실패

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

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

What's Next

학습 조회

요청
응답

태그

CLOVA Studio