Chat Completions
    • PDF

    Chat Completions

    • PDF

    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
    X-NCP-CLOVASTUDIO-API-KEYRequiredAPI key issued when creating the test app or service app
    X-NCP-APIGW-API-KEYRequiredAPI Gateway key issued when creating the test app or service app
    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 ≤ 2048 (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.

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

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

    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: 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"
          }
        ]
      }
    }
    

    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
    aiFilterArray-AI Filter result

    StreamingChatCompletionsTokenEvent

    The following describes StreamingChatCompletionsResultEvent.

    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)
    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

    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”}}
    

    Failure

    The following is a sample response upon a failed call.


    Was this article helpful?

    What's Next
    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.