Reasoning

For /v1/responses, see Using the Responses API. The other examples on this page use Chat Completions.

What is reasoning?

Reasoning lets Solar spend additional reasoning tokens before producing the final answer. Those extra tokens give the model room to work through a problem in stages, which can help on tasks that require multiple dependent steps, where each step builds on the result of the previous one.

When to use reasoning

Reasoning generally uses more output tokens and can increase latency and cost; the section below covers how to control it.

Controlling reasoning

The reasoning_effort parameter controls whether the model spends a reasoning budget before answering, and roughly how much. A higher effort can use more output tokens and increase latency and cost, but it does not guarantee a better answer, so start with reasoning off or at a low effort and raise it only when the task actually needs multi-step work.

Which values turn reasoning on differs by model, and the mapping can change as models are updated. Check the response fields described below rather than assuming a fixed behavior.

solar-pro4 does not reason unless you turn it on: omitting reasoning_effort — or sending it as null — leaves reasoning off, and it turns on only when you set an effort between low and max. When reasoning is on, the thought process is returned in choices[].message.reasoning, and in choices[].delta.reasoning when streaming.

solar-mini4 follows the same rules as solar-pro4: the same effort values turn reasoning on and off, and its thought process is returned the same way.

solar-mini does not support reasoning and does not accept reasoning_effort. Sending any value returns an HTTP 400 error, so omit the parameter entirely for that model.

Response behavior

• Read the final answer from message.content, whether or not reasoning is on.
• Whether the thought process itself is returned in message.reasoning is model-specific — see the table above.
• The number of tokens spent on reasoning is reported in usage.completion_tokens_details.reasoning_tokens whenever reasoning is on.

Make a reasoning request

Send a problem that takes more than one step with reasoning_effort set to medium, so solar-pro4 works through it before answering.

from openai import OpenAI

client = OpenAI(
    api_key="UPSTAGE_API_KEY",
    base_url="https://api.upstage.ai/v1"
)

response = client.chat.completions.create(
    model="solar-pro4",
    messages=[
        {
            "role": "user",
            "content": "An $80 item gets a 20% discount, then 10% tax is added. What is the final price? Answer with only the dollar amount."
        }
    ],
    reasoning_effort="medium"
)

message = response.choices[0].message

reasoning = getattr(message, "reasoning", None)
if reasoning:
    print(reasoning)

print(message.content)

Understand the response

This solar-pro4 response carries the final answer in message.content, the visible thought process in message.reasoning, and the number of tokens spent on reasoning in usage.completion_tokens_details.reasoning_tokens.

{
  "id": "b8592385-8fa2-442f-9838-71b2086ee310",
  "object": "chat.completion",
  "created": 1785957101,
  "model": "solar-pro4-260806",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "$70.40",
        "reasoning": "Thinking Process:\n\n1.  **Analyze the Request:**\n    *   Item price: $80\n    *   Discount: 20%\n    *   Tax: 10% (applied after discount)\n    *   Output format: Only the dollar amount.\n\n2.  **Calculate the Discount:**\n    *   Discount amount = $80 * 20% = $80 * 0.20 = $16\n    *   Price after discount = $80 - $16 = $64\n    *   Alternatively: $80 * (1 - 0.20) = $80 * 0.80 = $64\n\n3.  **Calculate the Tax:**\n    *   Tax is applied to the discounted price ($64).\n    *   Tax amount = $64 * 10% = $64 * 0.10 = $6.40\n\n4.  **Calculate the Final Price:**\n    *   Final Price = Price after discount + Tax amount\n    *   Final Price = $64 + $6.40 = $70.40\n\n5.  **Format the Output:**\n    *   The user requested \"only the dollar amount\".\n    *   Standard format for dollar amounts includes the '$' sign and two decimal places.\n    *   Result: $70.40\n\n6.  **Final Verification:**\n    *   $80 * 0.8 = 64$\n    *   $64 * 1.1 = 70.4$\n    *   Output: $70.40\n\n7.  **Construct Final Response:**\n    *   $70.40\n"
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 86,
    "completion_tokens": 371,
    "total_tokens": 457,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 363,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "system_fingerprint": null
}

Stream the response

Set stream to true to receive the answer as it is produced. Reasoning and the final answer arrive in separate stream deltas: the visible thought process comes in delta.reasoning, and the final answer comes in delta.content. Handle and accumulate the two separately so your application can render the reasoning — or hide it — independently of the answer.

Only expose or log visible reasoning in a controlled debugging environment. It can contain user input or sensitive intermediate details, so do not persist it in production logs by default.

If you read the raw SSE stream instead of using an SDK, the stream ends with a data: [DONE] line.

from openai import OpenAI

client = OpenAI(
    api_key="UPSTAGE_API_KEY",
    base_url="https://api.upstage.ai/v1"
)

stream = client.chat.completions.create(
    model="solar-pro4",
    messages=[
        {
            "role": "user",
            "content": "An $80 item gets a 20% discount, then 10% tax is added. What is the final price? Answer with only the dollar amount."
        }
    ],
    reasoning_effort="medium",
    stream=True
)

reasoning_started = False
answer_started = False

for chunk in stream:
    delta = chunk.choices[0].delta

    reasoning = getattr(delta, "reasoning", None)
    if reasoning:
        if not reasoning_started:
            print("[Reasoning]")
            reasoning_started = True
        print(reasoning, end="", flush=True)

    if delta.content:
        if not answer_started:
            print("\n\n[Answer]")
            answer_started = True
        print(delta.content, end="", flush=True)

Using the Responses API

The Responses API is available on Solar Pro 4 and Solar Mini 4.

Set reasoning.effort to enable reasoning. The token budget includes both reasoning and the answer. Read reasoning from output items of type reasoning and its token count from usage.output_tokens_details.reasoning_tokens.

from openai import OpenAI

client = OpenAI(
    api_key="UPSTAGE_API_KEY",
    base_url="https://api.upstage.ai/v1",
)

response = client.responses.create(
    model="solar-pro4",
    input="What is 17 * 23? Answer with the number only.",
    reasoning={"effort": "medium"},
    max_output_tokens=2000,
)

for item in response.output:
    if item.type == "reasoning":
        # Reasoning can contain user input. Do not log it in production.
        print("reasoning:", item.content[0].text)
print("reasoning tokens:", response.usage.output_tokens_details.reasoning_tokens)
print("answer:", response.output_text)