Chat Completions

release/20240425
English

Chat Completions

Article Summary

Share feedback

Thanks for sharing your feedback!

Available in Classic and VPC

Generates conversational sentences using HyperCLOVA X model.

Requests

Describes the request format. The request format is as follows:

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

Header

The following describes the header.

Header	Required	Description
X-NCP-CLOVASTUDIO-API-KEY	Y	API key issued when creating a test app or service app
X-NCP-APIGW-API-KEY	Y	API Gateway key issued when creating a 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

The response result is returned in JSON format by default, but when Accept is specified as text/event-stream, the response result is returned in a stream format.
When using the response stream, please use https://clovastudio.stream.ntruss.com/ as the API URL.

Path parameters

The following describes the parameters.

Field	Type	Required	Description
modelName	string	Y	Model name: `HCX-002`

Body

The following describes the body.

Field	Type	Required	Description
messages	array	Y	Conversation messages
messages.role	enum	Y	Role of the conversational message system: directives that define roles user: user's speech/question assistant: response to the user's speech/question
messages.content	string	Y	Content of the conversation message
temperature	double	N	Degree of diversity for generated tokens (a higher setting generates more diverse sentences) 0.00 ＜ temperature ≤ 1 (default value: 0.50)
topK	int	N	Selects and samples the top k token candidates with the highest probabilities from the generated token pool 0 ≤ topK ≤ 128 (default value: 0)
topP	double	N	Samples based on the cumulative probabilities of the generated token candidates 0 ＜ topP ≤ 1 (default value: 0.8)
repeatPenalty	double	N	The degree of penalty applied when generating the same token (a higher setting reduces the likelihood of repeatedly generating the same result) 0 ＜ repeatPenalty ≤ 10 (default value: 5)
stopBefore	string	N	Character that halts token generation [] (default value)
maxTokens	int	N	Maximum number of tokens generated 0-4096 (default value: 100)
seed	int	N	When running the model repeatedly, adjust the level of consistency in the results 0: apply randomness to the level of consistency (default value) 1 ≤ seed ≤ 4294967295: seed value for desired consistent results or a user-specified seed value

Note

When filling out some fields, please check the following:

messages: the sum of the number of tokens entered and the number of tokens entered in "maxTokens" cannot exceed 4096 tokens. You can verify the number of tokens entered in messages using the Chat Completions tokenizer API.

topP, temperature: indicate up to two decimal places.

Seed: using this can increase the likelihood of obtaining consistent results even when the model is run repeatedly. However, the completeness of the results is not guaranteed, and slight variations in results may occur if other conditions change.

Syntax

The following is an example of 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 do a test."
  }, {
    "role" : "assistant",
    "content": "Understood. What would you like to test?"
  } ],
  "stopBefore" : [ ],
  "repeatPenalty" : 5.0,
  "topP" : 0.8
}'

Responses

Describes the responses format.

Header

The following describes the header.

Header	Required	Description
Content-Type	-	application/json

Body

The following describes the body.

Field	Type	Required	Description
result	-	-	Response result
result.message	array	Y	Conversation messages
result.message.role	enum	Y	Role of the conversational message system: directives that define roles user: user's speech/question assistant: response to the user's speech/question
result.message.content	string	Y	Content of the conversation message
result.stopReason	enum	-	Token generation termination reasons (typically passed in the last event) LENGTH: length limitation END_TOKEN: termination due to end of token (EOD) STOP_BEFORE: termination due to encountering a character specified in the stopBefore
result.inputLength	int	-	Number of input tokens (inclusive of special tokens like end of turn for billing purposes)
result.outputLength	int	-	Number of response tokens
result.seed	int	-	Input seed value (When 0 is entered or left blank, a random value will be returned)
aiFilter	array	-	AI Filter result
aiFilter.groupName	string	Y	AI Filter category group name curse unsafeContents
aiFilter.name	string	Y	Detailed AI Filter category name discrimination: denigration, discrimination, disdain (curse) insult (curse) sexualHarassment: sexual harassment, lewdness (unsafeContents)
aiFilter.score	string	Y	AI Filter score 0: high likelihood of sensitive/dangerous expressions in the conversation message 1: possible presence of sensitive/dangerous expressions in the conversation message 2: low likelihood of sensitive/dangerous expressions in the conversation message

Note

The AI Filter can analyze up to 500 characters. However, if the text for analysis contains many unconventional formats, emojis, special characters, and so on, it might not be analyzed accurately.

Syntax

The following is an example of syntax.

{
  "status": {
    "code": "20000",
    "message": "OK"
  },
  "result": {
    "message": {
      "role": "assistant",
      "content": "phrase: reflect on your day, jotting down the events that transpired, and prepare for tomorrow. A diary will enrich your life further.\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"
      }
    ]
  }
}

Response stream

You can use token streaming to display the generated tokens one by one. It describes the token streaming format.

Header

The following describes the header.

Header	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 the conversational message system: directives that define roles user: user's speech/question assistant: response to the user's speech/question
message.content	string	-	Content of the conversation message
stopReason	enum	-	Token generation termination reasons (typically passed in the last event) LENGTH: length limitation END_TOKEN: termination due to end of token (EOD) STOP_BEFORE: termination due to encountering a character specified in the stopBefore
inputLength	int	-	Number of input tokens (inclusive of special tokens like end of turn for billing purposes)
outputLength	int	-	Number of response tokens
aiFilter	array	-	AI Filter result
aiFilter.groupName	string	Y	AI Filter category group name
aiFilter.name	string	Y	AI Filter category detailed name
aiFilter.score	string	Y	AI Filter score 0: high likelihood of sensitive/dangerous expressions in the conversation message 1: possible presence of sensitive/dangerous expressions in the conversation message 2: low likelihood of sensitive/dangerous expressions in the conversation message

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 the conversational message system: directives that define roles user: user's speech/question assistant: response to the user's speech/question
message.content	string	-	Content of the conversation message
inputLength	int	-	Number of input tokens (inclusive of special tokens like end of turn for billing purposes)
stopReason	enum	-	Token generation termination reasons (typically passed in the last event) LENGTH: length limitation END_TOKEN: termination due to end of token (EOD) STOP_BEFORE: termination due to encountering a character specified in the 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 be transmitted

Syntax

The following is an example of syntax.

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

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

Was this article helpful?

What's Next

Completions

Table of contents

Requests
Responses
Response stream