MENU
      Completions

        Completions


        기사 요약

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

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

        요청

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

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

        요청 헤더

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

        헤더필수 여부설명
        AuthorizationRequired인증을 위한 API 키 <예시> Bearer nv-************
        X-NCP-CLOVASTUDIO-REQUEST-IDOptional요청에 대한 아이디
        Content-TypeRequired요청 데이터의 형식
        • application/json

        요청 경로 파라미터

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

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

        요청 바디

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

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

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

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

        요청 예시

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

        curl --location --request POST 'https://clovastudio.stream.ntruss.com/testapp/v1/completions/LK-D2' \
        --header 'Authorization: Bearer {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
        }'
        Shell

        응답

        응답 형식을 설명합니다.

        응답 헤더

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

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

        응답 바디

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

        필드타입필수 여부설명
        statusObject-응답 상태
        resultObject-응답 결과
        result.textString-생성 토큰 (프롬프트와 생성된 결괏값)
        result.stopReasonString-결괏값 생성 중단 이유
        • length | end_token | stop_before
          • length: 길이 제한
          • end_token: 토큰 수 제한
          • stop_before: 답변 생성 중 stopBefore에 지정한 문자 출현
        result.startLengthInteger-입력 토큰 수
        inputTextString-사용자 입력값 (프롬프트)
        result.inputLengthInteger-입력 토큰 수(과금 기준으로 end of turn과 같은 특수 토큰도 포함)
        result.inputTokensArray-입력 토큰 정보
        result.outputTextInteger-생성 결괏값
        result.outputLengthInteger-생성 토큰 수
        result.outputTokensArray-생성 토큰 정보
        result.probsArray-응답 토큰의 후보 토큰 및 후보 토큰의 확률값
        result.okBoolean-응답 성공 여부
        • false | true
          • false: 응답 실패. 오류 메시지 반환
          • true: 응답 성공
        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": {
                "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"
                    }
                ]
            }
        }
        JSON

        실패

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


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

        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.