Completions

Available in Classic and VPC

Generate conversational sentences utilizing the normal mode (LK model) of Playground.

Note

The Completions API and LK model will be discontinued by the end of the year. We recommend using the HyperCLOVA X model for improved performance.

Request

This section describes the request format. The method and URI are as follows:

Method	URI
POST	/v1/chat-completions/{modelName} When generating sentences using the model /v1/tasks/{taskId}/chat-completions When generating sentences using tuning trained jobs

Request headers

The following describes the request headers.

Headers	Required	Description
`Authorization`	Required	API key for authentication Example: `Bearer nv-************`
`X-NCP-CLOVASTUDIO-REQUEST-ID`	Optional	Request ID for the request
`Content-Type`	Required	Request data format `application/json`

Request path parameters

You can use the following path parameters with your request:

Field	Type	Required	Description
`model`	String	Conditional	Model name When using a model to generate sentences Example: LK-D2
`taskId`	String	Conditional	Training ID When using tuning trained job to generate sentences Can be checked in the response body of the Create training API

Request body

You can include the following data in the body of your request:

Field	Type	Required	Description
`text`	String	Required	User input (prompt) New sentence is generated based on this prompt.
`topK`	Integer	Optional	Sample K high-probability candidates from the pool of generated token candidates. 0 ≤ `topK` ≤ 128 (default: 0)
`topP`	Float	Optional	Sample generated token candidates based on cumulative probability. 0.00 ＜ `topP` ≤ 1.00 (default: 0.80) Display to two decimal places.
`repeatPenalty`	Float	Optional	Degree of penalty for generating the same token (the higher the setting, the less likely it is to generate the same result repeatedly) 0.0 ＜ `repeatPenalty` ≤ 10.0 (default: 5.0)
`stopBefore`	Array	Optional	Character to abort token generation [] (default)
`restart`	String	Optional	Text to be attached behind the generated result value
`start`	String	Optional	Text to be attached behind the user input value
`maxTokens`	Integer	Optional	Maximum number of generated tokens 0 ＜ `maxTokens` ≤ 2048 (default: 100)
`includeTokens`	Boolean	Optional	Whether input_tokens and output_tokens will be included in the response `false` \| `true` (default) `false`: do not include `true`: include
`temperature`	Float	Optional	Degree of diversity for the generated tokens (higher values generate more diverse sentences) 0.00 ＜ `temperature` ≤ 1.00 (default: 0.50) Display to two decimal places.
`includeAiFilters`	Boolean	Optional	Whether to display the AI Filter results (degree of the generated results in categories such as profanity, degradation/discrimination/hate, sexual harassment/obscenity, etc.) `false` (default) \| `true` `false`: not display `true`: display

Note

When entering some fields, check the following:

text: The sum of the number of tokens entered and the number of tokens entered in maxTokens can't exceed 2048 tokens.

Request example

The request example is as follows:

curl --location --request POST 'https://clovastudio.stream.ntruss.com/v1/completions/LK-D2' \
--header 'Authorization: Bearer {API Key}' \
--header 'X-NCP-CLOVASTUDIO-REQUEST-ID: {Request ID}' \
--header 'Content-Type: application/json' \
--data '{
  "start": "\nEnglish: ",
  "stopBefore": ["\nKorean: "],
  "text": "Korean: 사과\nEnglish: Apple\nKorean: 바나나",
  "includeAiFilters": true
}'

Response

This section describes the response format.

Response headers

The following describes the response headers.

Headers	Required	Description
Content-Type	-	Response data format `application/json`

Response body

The response body includes the following data:

Field	Type	Required	Description
`status`	Object	-	Response status
`result`	Object	-	Response result
`result.text`	String	-	Generated token (prompt and generated result value)
`result.stopReason`	String	-	Reason for stopping results generation `length` \| `end_token` \| `stop_before` `length`: length limit `end_token`: token count limit `stop_before`: character specified in `stopBefore` occurred during answer generation
`result.startLength`	Integer	-	Input token count
`inputText`	String	-	User input value (prompt)
`result.inputLength`	Integer	-	Number of input tokens (including special tokens such as END OF TURN based on billing)
`result.inputTokens`	Array	-	Entered token information
`result.outputText`	Integer	-	Generated result value
`result.outputLength`	Integer	-	Generated token count
`result.outputTokens`	Array	-	Generated token information
`result.probs`	Array	-	Candidate tokens for response tokens and probability values for candidate tokens
`result.ok`	Boolean	-	Whether response was successful `false` \| `true` `false`: Response failed. An error message is returned. `true`: Response successful
`aiFilter`	Array	-	AI Filter result

`aiFilter`

The following describes aiFilter.

Field	Type	Required	Description
`groupName`	String	-	AI Filter category `curse` \| `unsafeContents` `curse`: degradation, discrimination, hate, and profanity `unsafeContents`: sexual harassment, obscenity
`name`	String	-	AI Filter subcategory `discrimination` \| `insult` \| `sexualHarassment` `discrimination`: degradation, discrimination, hate `insult`: profanity `sexualHarassment`: sexual harassment, obscenity
`score`	String	-	AI Filter score `-1` \| `0` \| `1` \| `2` `-1`: AI Filter error occurred. `0`: Conversation messages are more likely to contain sensitive/hazardous language. `1`: Conversation messages are likely to contain sensitive/hazardous language. `2`: Conversation messages are unlikely to contain sensitive/hazardous language.
`result`	String	-	Whether AI Filter is operating properly `OK` \| `ERROR` `OK`: normal operation `ERROR`: error occurred

Note

AI Filter can analyze up to 500 characters. However, if the text being analyzed contains many unusual formats, emojis, or special characters, it may not be analyzed correctly.

Response example

The response example is as follows:

Succeeded

The following is a sample response upon a successful call.

{
 
    "status": {
        "code": "20000",
        "message": "OK"
    },
    "result": {
        "text": "Write emotional marketing copy\n\nProduct: lotion\nText: Moisturizes as soon as it touches your skin\n###\nProduct: planner\nText: a gift I give to myself",
        "stopReason": "end_token",
        "startLength": 33,
        "inputText": "Write emotional marketing copy\n\nProduct: lotion\nText: Moisturizes as soon as it touches your skin\n###\nProduct: planner",
        "inputLength": 33,
        "inputTokens": ["Wr", "ite", " emo", "tion", "al", " market","ing", " copy", "\n",
        "\n", "Product", ":", " lotion", "\n", "Text", ":"," Moisturizes", " as", " soon", " as", " it", " touches", " your skin"
        "\n", "##", "#", "\n", "Product", ":", " planner", "\n", "Text", ":"
        ],
        "outputText": "\nText: a gift I give to myself",
        "outputLength": 7,
        "outputTokens": ["a", "gift", "I", "give", "to", "myself",""
        ],
        "probs": [],
        "ok": true,
        "aiFilter": [
            {
                "groupName": "curse",
                "name": "insult",
                "score": "2"
            },
            {
                "groupName": "curse",
                "name": "discrimination",
                "score": "1"
            },
            {
                "groupName": "unsafeContents",
                "name": "sexualHarassment",
                "score": "2"
            }
        ]
    }
}

Failure

The following is a sample response upon a failed call.