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 utilizing the HyperCLOVA X model.

Request

The following describes the request format for the endpoint. The request format is as follows:

Method	URI
POST	/v1/chat-completions/{modelName}

Note

When using a task that has been tuning trained, it should be called in the form /v1/tasks/{taskId}/chat-completions. You can check the taskID required for calling in the response body of Create training API.

Request headers

The following describes the headers.

Headers	Required	Description
X-NCP-CLOVASTUDIO-API-KEY	Y	API key issued when creating the test app or service app
X-NCP-APIGW-API-KEY	Y	API Gateway key issued when creating the test app or service app
X-NCP-CLOVASTUDIO-REQUEST-ID	N	Request ID for each request
Content-Type	Y	application/json
Accept	N	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

The following describes the parameters.

Field	Type	Required	Description
modelName	string	Y	Model name to use <E.g.> HCX-003

The following describes the parameters when using a task that has been tuning trained.

Field	Type	Required	Description
taskId	string	Y	Training ID

Note

You can check the taskID required for calling in the response body of Create training API.

Request body

The following describes the body.

Field	Type	Required	Description
messages	object (ChatMessage)	Y	Conversation messages
ChatMessages.role	enum	Y	Role of conversation messages system: directives that define roles user: user utterances/questions assistant: answers to user utterances/questions
ChatMessages.content	string	Y	Content of conversation messages
temperature	double	N	Degree of diversity for the generated tokens (higher values generate more diverse sentences) 0.00 ＜ temperature ≤ 1 (default: 0.50)
topK	int	N	Sample k high-probability candidates from the pool of generated token candidates 0 ≤ topK ≤ 128 (default: 0)
topP	double	N	Sample generated token candidates based on cumulative probability 0 ＜ topP ≤ 1 (default: 0.8)
repeatPenalty	double	N	Degree of penalty for generating the same token (the higher the setting, the less likely it is to generate the same result repeatedly) 0 ＜ repeatPenalty ≤ 10 (default: 5.0)
stopBefore	string	N	Character to abort token generation [] (default)
maxTokens	int	N	Maximum number of generated tokens 0 - 4096 (default: 100)
includeAiFilters	boolean	N	Degree of the generated results in categories such as profanity, degradation/discrimination/hate, sexual harassment/obscenity, etc. false (default) true
seed	int	N	Adjust the consistency level of results in model iterations 0: randomize consistency level (default) 1 ≤ seed ≤ 4294967295: the seed value of the results you want to generate consistently, or a seed value you specify

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 verified by calling the Chat completions token calculation API.

topP, temperature: Write to two decimal places.

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.

Request syntax

The following is a sample syntax.

curl --location --request POST 'https://clovastudio.stream.ntruss.com/testapp/v1/chat-completions/HCX-002' \
--header 'X-NCP-CLOVASTUDIO-API-KEY: <X-NCP-CLOVASTUDIO-API-KEY>' \
--header 'X-NCP-APIGW-API-KEY: <X-NCP-APIGW-API-KEY>' \
--header 'X-NCP-CLOVASTUDIO-REQUEST-ID: <X-NCP-CLOVASTUDIO-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

The following describes the response format.

Response headers

The following describes the headers.

Headers	Required	Description
Content-Type	-	application/json

Response body

The following describes the body.

Field	Type	Required	Description
result	-	-	Response result
result.message	array	-	Conversation messages
result.message.role	enum	-	Role of conversation messages system: directives that define roles user: user utterances/questions assistant: answers to user utterances/questions
result.message.content	string	-	Content of conversation messages
result.stopReason	enum	-	Reason for stopping token generation (typically passed to the last event) LENGTH: length limit END_TOKEN: interrupted generation due to End Of Token (EOD) STOP_BEFORE: interruption caused by the character specified in stopBefore
result.inputLength	int	-	Number of input tokens (including special tokens such as END OF TURN based on billing)
result.outputLength	int	-	Number of response tokens
result.seed	int	-	Input seed value (Return a random value when 0 is entered or not entered)
aiFilter	array	-	AI Filter result
aiFilter.groupName	string	-	AI Filter category group name curse unsafeContents
aiFilter.name	string	-	AI Filter category detailed name discrimination: degradation, discrimination, hate (curse) insult: profanity (curse) sexualHarassment: sexual harassment, obscenity (unsafeContents)
aiFilter.score	string	-	AI Filter score 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 -1: AI Filter error occurred
aiFilter.score	string	-	Whether AI Filter is operating properly 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 syntax

The following is a sample syntax.

Succeeded

The following is a sample syntax 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 syntax 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.

Headers

The following describes the headers.

Headers	Required	Description
Accept	-	text/event-stream

Body

The following describes the body.

StreamingChatCompletionsResultEvent

The following describes StreamingChatCompletionsResultEvent.

Field	Type	Required	Description
message	array	-	Conversation messages
message.role	enum	-	Role of conversation messages system: directives that define roles user: user utterances/questions assistant: answers to user utterances/questions
message.content	string	-	Content of conversation messages
stopReason	enum	-	Reason for stopping token generation (typically passed to the last event) LENGTH: length limit END_TOKEN: interrupted generation due to End Of Token (EOD) STOP_BEFORE: interruption caused by the character specified in stopBefore
inputLength	int	-	Number of input tokens (including special tokens such as END OF TURN based on billing)
outputLength	int	-	Number of response tokens
aiFilter	array	-	AI Filter result
aiFilter.groupName	string	-	AI Filter category group name
aiFilter.name	string	-	AI Filter category detailed name
aiFilter.score	string	-	AI Filter score 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 -1: AI Filter error occurred
aiFilter.result	string	-	Whether AI Filter is operating properly OK: normal operation ERROR: error occurred

StreamingChatCompletionsTokenEvent

The following describes StreamingChatCompletionsResultEvent.

Field	Type	Required	Description
id	string	-	Event ID that identifies the request
message	array	-	Conversation messages
message.role	enum	-	Role of conversation messages system: directives that define roles user: user utterances/questions assistant: answers to user utterances/questions
message.content	string	-	Content of conversation messages
inputLength	int	-	Number of input tokens (including special tokens such as END OF TURN based on billing)
stopReason	enum	-	Reason for stopping token generation (typically passed to the last event) LENGTH: length limit END_TOKEN: interrupted generation due to End Of Token (EOD) STOP_BEFORE: interruption caused by the character specified in stopBefore

ErrorEvent

The following describes ErrorEvent.

Field	Type	Required	Description
status	status	-	Response status

SignalEvent

The following describes SignalEvent.

Field	Type	Required	Description
data	string	-	Signal data information to pass

Response syntax

The following is a sample syntax.

Succeeded

The following is a sample syntax 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 syntax upon a failed call.

Was this article helpful?

What's Next

Completions

Table of contents

Request
Response
Response stream