Chat Completions

English

Chat Completions

Article summary

Did you find this summary helpful?

Thank you for your feedback

Available in Classic and VPC

Generate interactive sentences using the HyperCLOVA X model.

Request

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

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

Request headers

The following describes the request headers.

Headers	Required	Description
`X-NCP-CLOVASTUDIO-API-KEY`	Required	API key issued when creating the test app or service app
`X-NCP-APIGW-API-KEY`	Required	API Gateway key issued when creating the test app or service app
`X-NCP-CLOVASTUDIO-REQUEST-ID`	Optional	Request ID for the request
`Content-Type`	Required	Request data format `application/json`
`Accept`	Conditional	Response data format `text/event-stream`

Note

Response results are returned in JSON by default, but if you specify Accept as text/event-stream, then the response results are returned as a stream.
When using the response stream, use the API URL as https://clovastudio.stream.ntruss.com/.

Request path parameters

You can use the following path parameters with your request:

Field	Type	Required	Description
`modelName`	String	Conditional	Model name When using the model to generate sentences <e.g.> `HCX-003`
`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

The response body includes the following data:

Field	Type	Required	Description
`messages`	Array	Required	Conversation messages
`temperature`	Double	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
`topK`	Integer	Optional	Sample K high-probability candidates from the pool of generated token candidates 0 ≤ `topK` ≤ 128 (default: 0)
`topP`	Double	Optional	Sample generated token candidates based on cumulative probability 0.00 ＜ `topP` ≤ 1.00 (default: 0.80) Display to two decimal places
`repeatPenalty`	Double	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)
`maxTokens`	Integer	Optional	Maximum number of generated tokens 0 ＜ `maxTokens` ≤ 2048 (default: 100)
`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
`seed`	Integer	Optional	Adjust consistency level of output on model iterations 0: Randomize consistency level (default) 1 ≤ `seed` ≤ 4294967295: `seed` value of result value you want to generate consistently, or a user-specified `seed` value

Note

When entering some fields, check the following.

messages: The sum of the number of tokens entered and the number of tokens entered in maxTokens can't exceed 4096 tokens. The number of tokens entered in messages can be checked calling the Chat Completions token calculation API
seed: When used, you can increase the probability of getting consistent results over repeated runs of the model. However, it does not guarantee the completeness of the results, and results may vary slightly if other conditions change.

`messages`

The following describes messages.

Field	Type	Required	Description
`role`	Enum	Required	Role of conversation messages `system` \| `user` \| `assistant` `system`: directives that define roles `user`: user utterances/questions `assistant`: answers to user utterances/questions
`content`	String	Required	Content of conversation messages

Request example

The request example is as follows:

curl --location --request POST 'https://clovastudio.stream.ntruss.com/testapp/v1/chat-completions/HCX-003' \
--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' \
--header 'Accept: text/event-stream' \
--data '{
  "topK" : 0,
  "includeAiFilters" : true,
  "maxTokens" : 256,
  "temperature" : 0.5,
  "messages" : [ {
    "role" : "system",
    "content" : "test"
  }, {
    "role" : "user",
    "content" : "Let's test it."
  }, {
    "role" : "assistant",
    "content" : "Understood. What would you like to test?"
  } ],
  "stopBefore" : [ ],
  "repeatPenalty" : 5.0,
  "topP" : 0.8
}'

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.message`	Object	-	Conversation messages
`result.message.role`	Enum	-	Role of conversation messages `system` \| `user` \| `assistant` `system`: directives that define roles `user`: user utterances/questions `assistant`: answers of the model
`result.message.content`	String	-	Content of conversation messages
`result.stopReason`	Enum	-	Reason for stopping results generation `length` \| `end_token` \| `stop_before` `length`: length limit `end_token`: token count limit `stop_before`: The model terminated its output on its own Character specified in `stopBefore` occurred during answer generation
`result.inputLength`	Integer	-	Number of input tokens (including special tokens such as END OF TURN based on billing)
`result.outputLength`	Integer	-	Number of response tokens
`result.seed`	int	-	Input seed value (Return a random value when 0 is entered or not entered)
`result.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": {
    "message": {
      "role": "assistant",
      "content": "Phrase: Record what happened today, and prepare for tomorrow. A journal will make your life richer.\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"
      }
    ]
  }
}

Failure

The following is a sample response upon a failed call.

Response stream

You can use token streaming to output the tokens as they are generated, one by one. The following describes the token streaming format.

Response headers

The following describes the response headers.

Headers	Required	Description
Accept	-	Response data format `text/event-stream`

Response body

The response body includes the following data:

StreamingChatCompletionsResultEvent

The following describes StreamingChatCompletionsResultEvent.

Field	Type	Required	Description
`message`	Object	-	Conversation messages
`message.role`	Enum	-	Role of conversation messages `system` \| `user` \| `assistant` `system`: directives that define roles `user`: user utterances/questions `assistant`: answers of the model
`message.content`	String	-	Content of conversation messages
`stopReason`	Enum	-	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
`inputLength`	Integer	-	Number of input tokens (including special tokens such as END OF TURN based on billing)
`outputLength`	Integer	-	Number of response tokens
`aiFilter`	Array	-	AI Filter result

StreamingChatCompletionsTokenEvent

The following describes StreamingChatCompletionsResultEvent.

Field	Type	Required	Description
`id`	String	-	Event ID that identifies the request
`message`	Object	-	Conversation messages
`message.role`	Enum	-	Role of conversation messages `system` \| `user` \| `assistant` `system`: directives that define roles `user`: user utterances/questions `assistant`: answers of the model
`message.content`	String	-	Content of conversation messages
`inputLength`	Integer	-	Number of input tokens (including special tokens such as END OF TURN based on billing)
`stopReason`	Enum	-	Reason for stopping results generation `length` \| `end_token` \| `stop_before` `length`: length limit `end_token`: token count limit `stop_before`: The model successfully completed generation Character specified in `stopBefore` occurred during answer generation

ErrorEvent

The following describes ErrorEvent.

Field	Type	Required	Description
`status`	Object	-	Response status

SignalEvent

The following describes SignalEvent.

Field	Type	Required	Description
`data`	String	-	Signal data information to pass

Response example

The response example is as follows:

Succeeded

The following is a sample response upon a successful call.

id: aabdfe-dfgwr-edf-hpqwd-f2asd-g
event: token
data: {"message": {"role": "assistant", "content": “H”}}

id: aabdfe-dfgwr-edf-hpqwd-f1asd-g
event: result
data: {"message": {"role": "assistant", "content": “i”}}

Failure

The following is a sample response upon a failed call.

Was this article helpful?

What's Next

Completions

Table of contents

Request
Response
Response stream