Chat Completions

English

Chat Completions

Article summary

Did you find this summary helpful?

Thank you for your feedback

The latest service changes have not yet been reflected in this content. We will update the content as soon as possible. Please refer to the Korean version for information on the latest updates.

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} Generate sentences using the model /v1/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

The following describes the request path parameters.

Field	Type	Required	Description
`modelName`	String	Conditional	Model name When using a 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 following describes the response body.

Field	Type	Required	Description
`messages`	Object	Required	Conversation messages
`messages.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
`messages.content`	String	Required	Content of 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 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 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.

Request example

The following is a sample request.

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

The following 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 following describes the response body.

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`: 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 following is a sample example.

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 following describes the response body.

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`: 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 following is a sample example.

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