Thinking

Available in Classic and VPC

This guide describes Chat Completions v3, which leverages the HCX-007 inference model with complex problem-solving capabilities.

Request

This section describes the request format. The method and URI are as follows:

Request headers

The following describes the request headers.

Request path parameters

You can use the following path parameters with your request:

Request body

You can include the following data in the body of your request:

messages

The following describes messages.

content

The following describes content.

Request example

The request example is as follows:

curl --location --request POST 'https://clovastudio.stream.ntruss.com/v3/chat-completions/HCX-007' \
--header 'Authorization: Bearer {CLOVA Studio API Key}' \
--header 'X-NCP-CLOVASTUDIO-REQUEST-ID: {Request ID}' \
--header 'Content-Type: application/json' \
--header 'Accept: text/event-stream' \
--data '{
    "messages": [
      {
        "role": "system",
        "content": "- It is a highly organized analyst and an expert in logic-based problem solving."
      },
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Given a set with n elements, explain that the number of all subsets that can be made from this set is equal to n squared to the power of 2."
          }
        ]
      }
    ],
    "thinking": {
        "effort": "low"
        },
    "topP": 0.8,
    "topK": 0,
    "maxCompletionTokens": 5120,
    "temperature": 0.5,
    "repetitionPenalty": 1.1,
    "stop": []
  }'

Response

This section describes the response format.

Response headers

The following describes the response headers.

Response body

The response body includes the following data:

aiFilter

The following describes aiFilter.

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": "The number of subsets is determined by the two choices, with each element either included or excluded.\nFor example, the subset of {a} is ∅, {a} → 2 (2¹),
and the subset of {a,b} is ∅, {a}, {b}, {a,b} → 4 (2²).\nIn a set of n elements, each element has 2 choices (inclusion/exclusion), so the number of all cases is 2 × 2 × ... × 2 (n times) = 2ⁿ.\nAlternatively, the binomial theorem can be used: The number of cases where a subset has size k is the combination **C(n,k)**, so summing over all k (0 ≤ k ≤ n), we have ∑_{k=0}^n C(n,k) = (1+1)^n = 2ⁿ.\nTherefore, the number of subsets of n elements is always 2ⁿ.",
            "thinkingContent": "The question the user asked today is to explain why the number of all possible subsets of a set with n elements is n to the power of 2. Isn't this topic related to combinatorics or binary?\nFirst, consider that for each element, there are two cases: to select or not to select. For example, if there is only one element, there are two subsets: the conjugate and itself, totaling 2^1=2. When there are two elements, each is either included or excluded, so there are 2*2=4 and 2^2=4.\nGeneralizing, since there are two choices (inclusion/exclusion) for each element, the total number of cases is 2 multiplied by n times 2, or 2^n. This is basic combinatorial thinking.\nAlternatively, if we think of the number of cases where the subset is k in size, then C(n,k), and add it up from k=0 to n, we get (1+1)^n = 2^n, which is the binomial theorem, so we can conclude that the number of all cases is 2^n.\nSince the user probably wanted this explanation, I think I'll keep it simple and approach it as whether or not each element is chosen. I'll give an example, and then summarize the generalization."
        },
        "finishReason": "stop",
        "created": 1753362971
        "seed": 1561390649,
        "usage": {
            "promptTokens": 58,
            "completionTokens": 631,
            "totalTokens": 689,
            "completionTokensDetails": {
                "thinkingTokens": 366
            }
}

Failure

The following is a sample response upon a failed call.

• Common client error troubleshooting (4xx)
• Common server error troubleshooting (5xx)

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 body

The response body includes the following data:

StreamingChatCompletionsTokenEvent

The following describes StreamingChatCompletionsTokenEvent.

StreamingChatCompletionsResultEvent

The following describes StreamingChatCompletionsResultEvent.

ErrorEvent

The following describes ErrorEvent.

SignalEvent

The following describes SignalEvent.

Response example

The response example is as follows:

Succeeded

The following is a sample response upon a successful call.

id: aabdfe-dfgwr-edf-hpqwd-f3asd-g
event: token
data: {"message": {"role": "assistant", "thinkingContent": "today"},"finishReason": null, "created": 1744710905, "seed": 3284419119, "usage": null} 

...

id: aabdfe-dfgwr-edf-hpqwd-f2asd-g
event: token
data: {"message": {"role": "assistant", "content": "part"},"finishReason": null, "created": 1744710905, "seed": 3284419119, "usage": null} 

...

id: aabdfe-dfgwr-edf-hpqwd-f1asd-g
event: result
data: {
    "message": {
        "role": "assistant",
        "content": "The number of subsets is determined by the **inclusion status** of each element.  \nEach element can choose either **\"Include\" or \"Not include\"**, so there are two cases per element.  \n\nFor example: \n- Set with one element ({a}) → ∅, {a} (**2¹ = 2**) \n- Set with two elements ({a, b}) → ∅, {a}, {b}, {a,b} (**2² = 4**) \n\nBy extension, the **n elements** increase by **2 times** the previous result (2ⁿ-¹) at each step (**2ⁿ-¹ × 2 = 2ⁿ**).  \nIn other words, the number of all subsets is expressed as **2ⁿ**, reflecting the independent selectability of each element.  \n\nSince conjugates and complete sets are also naturally included, the formula **2ⁿ** provides a complete and consistent result.",
        "thinkingContent": "The question the user asked today is to explain why the number of subsets of a set of n elements is 2^n. How can we explain this easily? \n\nLet's start with the basic concept: each element has two choices: either it is in a subset or it is not. For example, if there is one element, then {}, {a} are two subsets, where 2^1=2.\n\nIf we add a second element, b, then for each of the existing subsets, we have to decide whether to add b or not. For each of the original {} and {a}, we either add b or not, for a total of 4. This is 2^2=4. When we expand in this way, for n, each step is repeated by multiplying the number of previous cases by 2, so we end up with 2×2×...×2 (n times) = 2^n\n\nAnother approach is to emphasize independent choices for each element. Since the inclusion or exclusion of each element does not affect each other, we can apply the multiplication law of combinations. So the total number of cases is 2 × 2 × ... × 2 (n times) = 2^n.\n\nDo I need to mention that sometimes conjugates or complete sets are also included? I think it would be clearer if I showed it with an example. But to keep it simple, I think it's enough to emphasize the key idea: the selectivity of each element.\n\nFinally, I could use induction to prove it mathematically rigorously, but since you're asking for a simple explanation, I'll stick to basic logic. I think this is how we'll work it out!"
    },
    "finishReason": "stop",
    "created": 1753363313,
    "seed": 3219533885,
    "usage": {
        "promptTokens": 58,
        "completionTokens": 588,
        "totalTokens": 646,
        "completionTokensDetails": {
            "thinkingTokens": 361
        }
    }
}

Failure

The following is a sample response upon a failed call.

• Common client error troubleshooting (4xx)
• Common server error troubleshooting (5xx)

Recommendations

CLOVA Studio inference models do not generate final responses directly, but rather analyze the user query, go through the necessary logical thought process, generate inferences (tokens), and then generate final responses based on them. The recommendations describe how to effectively utilize the inference model for optimized final response generation.

Set whether to infer and how long to infer

The CLOVA Studio inference models are trained so that you can set whether to infer and its length yourself. See the following instructions to set the inference availability and length for your request type.

• Whether to infer and depth of thought process for inference
  • Set via thinking.effort. Depending on the settings, the following defaults for the maximum number of request tokens to generate are applied.

    thinking.effort settings	maxCompletionTokens default	Description
    	none	512
    	low	5120
    	medium	10240
    	high	20480

• Inference length (maximum number of generated tokens)
  • Set via maxCompletionTokens. It includes both inferences and the number of final response tokens.
    • Inference uses maxCompletionTokens, not maxTokens.
  • You can set the value yourself, but if it is not large enough, the model may not be able to generate the final response if it reaches that length during the inference process. Therefore, adhere to the default value or try several times to find and set the appropriate length.

Check inference content

When you make an API request using inference, the response result consists of the inference content and the final response. You can check the inference content and token count as follows:

• The inference content, which contains the thought process that the inference model generated for the final response, can be found in message.thinkingContent in the response body.
• The number of tokens in the inference content can be found in usage.completionTokensDetails.thinkingTokens in the response body.

Input processing in multi-turn conversation

When you want to continue a multi-turn conversation, you should exclude the thinking content (message.thinkingContent) of the CLOVA Studio inference model and include only the final response, the model response (message.content), in the next turn's input. See the following image.