MENU
      Chat Completions

        Chat Completions


        Article summary

        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:

        MethodURI
        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.

        HeadersRequiredDescription
        AuthorizationRequiredAPI key for authentication <e.g.,> Bearer nv-************
        X-NCP-CLOVASTUDIO-REQUEST-IDOptionalRequest ID for the request
        Content-TypeRequiredRequest data format
        • application/json
        AcceptConditionalResponse 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:

        FieldTypeRequiredDescription
        modelNameStringConditionalModel name
        • When using the model to generate sentences
        • <e.g.> HCX-003
        taskIdStringConditionalTraining 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:

        FieldTypeRequiredDescription
        messagesArrayRequiredConversation messages
        temperatureDoubleOptionalDegree 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
        topKIntegerOptionalSample K high-probability candidates from the pool of generated token candidates
      • 0 ≤ topK ≤ 128 (default: 0)
      • topPDoubleOptionalSample generated token candidates based on cumulative probability
        • 0.00 < topP ≤ 1.00 (default: 0.80)
          • Display to two decimal places
        repeatPenaltyDoubleOptionalDegree 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)
      • stopBeforeArrayOptionalCharacter to abort token generation
      • [] (default)
      • maxTokensIntegerOptionalMaximum number of generated tokens
      • 0 < maxTokens ≤ 4096 (default: 100)
      • includeAiFiltersBooleanOptionalWhether 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
        seedIntegerOptionalAdjust 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.

        • HCX-003
          • The sum of the input tokens and the output tokens cannot exceed 8192 tokens.
          • The input tokens can be up to 7600 tokens.
          • The output tokens (maxTokens) to be requested from the model can be up to 4096 tokens.
        • HCX-DASH-001
          • The sum of the input tokens and the output tokens cannot exceed 4096 tokens.
          • The input tokens can be up to 3500 tokens.
          • The output tokens (maxTokens) to be requested from the model can be up to 4096 tokens.

        messages

        The following describes messages.

        FieldTypeRequiredDescription
        roleEnumRequiredRole of conversation messages
        • system | user | assistant
          • system: directives that define roles
          • user: user utterances/questions
          • assistant: answers to user utterances/questions
        contentStringRequiredContent 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 'Authorization: Bearer {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
        }'
        Shell

        Response

        This section describes the response format.

        Response headers

        The following describes the response headers.

        HeadersRequiredDescription
        Content-Type-Response data format
        • application/json

        Response body

        The response body includes the following data:

        FieldTypeRequiredDescription
        statusObject-Response status
        resultObject-Response result
        result.messageObject-Conversation messages
        result.message.roleEnum-Role of conversation messages
        • system | user | assistant
          • system: directives that define roles
          • user: user utterances/questions
          • assistant: answers of the model
        result.message.contentString-Content of conversation messages
        result.stopReasonEnum-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.inputLengthInteger-Number of input tokens (including special tokens such as END OF TURN based on billing)
        result.outputLengthInteger-Number of response tokens
        result.seedint-Input seed value (Return a random value when 0 is entered or not entered)
        result.aiFilterArray-AI Filter result

        aiFilter

        The following describes aiFilter.

        FieldTypeRequiredDescription
        groupNameString-AI Filter category
        • curse | unsafeContents
          • curse: degradation, discrimination, hate, and profanity
          • unsafeContents: sexual harassment, obscenity
        nameString-AI Filter subcategory
        • discrimination | insult | sexualHarassment
          • discrimination: degradation, discrimination, hate
          • insult: profanity
          • sexualHarassment: sexual harassment, obscenity
        scoreString-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
        resultString-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"
              }
            ]
          }
        }
        JSON

        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.

        HeadersRequiredDescription
        Accept-Response data format
        • text/event-stream

        Response body

        The response body includes the following data:

        StreamingChatCompletionsResultEvent

        The following describes StreamingChatCompletionsResultEvent.

        FieldTypeRequiredDescription
        messageObject-Conversation messages
        message.roleEnum-Role of conversation messages
        • system | user | assistant
          • system: directives that define roles
          • user: user utterances/questions
          • assistant: answers of the model
        message.contentString-Content of conversation messages
        stopReasonEnum-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
        inputLengthInteger-Number of input tokens (including special tokens such as END OF TURN based on billing)
        outputLengthInteger-Number of response tokens (including special tokens such as END OF TURN based on billing)
        aiFilterArray-AI Filter result

        StreamingChatCompletionsTokenEvent

        The following describes StreamingChatCompletionsTokenEvent.

        FieldTypeRequiredDescription
        idString-Event ID that identifies the request
        messageObject-Conversation messages
        message.roleEnum-Role of conversation messages
        • system | user | assistant
          • system: directives that define roles
          • user: user utterances/questions
          • assistant: answers of the model
        message.contentString-Content of conversation messages
        inputLengthInteger-Number of input tokens (including special tokens such as END OF TURN based on billing)
        outputLengthInteger-Number of response tokens (including special tokens such as END OF TURN based on billing)
        stopReasonEnum-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.

        FieldTypeRequiredDescription
        statusObject-Response status

        SignalEvent

        The following describes SignalEvent.

        FieldTypeRequiredDescription
        dataString-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”}}
        Python

        Failure

        The following is a sample response upon a failed call.


        Was this article helpful?

        Changing your password will log you out immediately. Use the new password to log back in.
        First name must have atleast 2 characters. Numbers and special characters are not allowed.
        Last name must have atleast 1 characters. Numbers and special characters are not allowed.
        Enter a valid email
        Enter a valid password
        Your profile has been successfully updated.