# Decision Model API

> Call POST /compatible-mode/v1/systemone to use the Bailian decision model (decision-model-preview), which returns classification, scoring, and yes/no decisions with full probability distributions and confidence in a single forward pass, without generating text. Suitable for high-frequency structured decisions such as ticket routing, content moderation, agent routing, and result verification.

## Prerequisites <span id="dm-010" />

You have created an API Key and set it as the environment variable `DASHSCOPE_API_KEY`. For more information, see [Configure an API key in environment variables](/help/en/model-studio/get-api-key).

## Request <span id="dm-020" />

<strong>Protocol</strong>: TypeSafe System One (`POST /compatible-mode/v1/systemone`)

A single request carries the business `state` and several typed questions (`choice` / `noul` / `score`). The model returns the decision result and probability distribution for each question in one forward pass, with `choice` and `score` additionally returning confidence, and **does not generate text**, so latency and cost are independent of output length.

<strong>Endpoint</strong>

Replace `{WorkspaceId}` with your workspace ID. See [Regions and endpoints](/help/en/model-studio/regions#h2_migrate_domain).

<table style={{ display: "table", tableLayout: "fixed", width: "100%" }}><colgroup><col style={{ width: "30%" }} /><col style={{ width: "70%" }} /></colgroup><thead><tr><th><p><strong>Region</strong></p></th><th><p><strong>Endpoint</strong></p></th></tr></thead><tbody><tr><td><p>Singapore</p></td><td><p><code>https\://\{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/systemone</code></p></td></tr><tr><td><p>China (Beijing)</p></td><td><p><code>https\://\{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/systemone</code></p></td></tr></tbody></table>

<Columns cols={2}>
  <Column>
    ## Request Parameters <span id="dm-100" />

    <strong>Content-Type</strong> · `String` · Header · Required

    Request type: `application/json`.

    <strong>Authorization</strong> · `String` · Header · Required

    API key, in the format: `Bearer $DASHSCOPE_API_KEY`.

    <strong>model</strong> · `String` · Body · Required

    Model name: `decision-model-preview`.

    <strong>state</strong> · `String / Object / Array` · Body · Required

    The business state to make decisions on: ticket text, a conversation, or a structured object (objects are serialized before being sent to the model).

    <strong>questions</strong> · `Object` · Body · Required

    A map of questions. The key is a caller-defined question id; the value is a question object with the following fields.

    <Accordion title="Question object properties">
      <strong>type</strong> · `String` · Required

      Question type:

      - `choice`: single choice
      - `noul`: yes/no
      - `score`: ordinal scale

      <strong>instructions</strong> · `String` · Optional

      Question description or judgment criteria.

      <strong>criteria</strong> · `Object / Array` · Depends on type

      - `choice`: a map of option name → option description (1–255 items; providing all options and an `other` fallback is recommended).
      - `noul`: optional `{"true":…, "false":…}` descriptions.
      - `score`: an array of level descriptions from low to high (2–255 levels; 3–7 clearly distinguishable levels recommended).
    </Accordion>

    <strong>Limits and recommendations</strong>

    - Maximum 16 questions (latency grows near-linearly with the number of questions).
    - `choice` options: ≤ 255.
    - `score` levels: 2–255 (3–7 recommended).
    - Context: maximum 65536 tokens; overlong `state` is rejected.
  </Column>

  <Column>
    ## Request Examples <span id="dm-400" />

    The DashScope SDKs already support the decision model (compatible with the TypeSafe System One protocol):

    - **Python**: DashScope SDK **2.0.1 or later**. The decision model is new in 2.0.1 — older versions do not have the `client.decision` interface and raise an `AttributeError`. Install: `pip install -U "dashscope>=2.0.1"`. See [Install the SDK](/help/en/model-studio/install-sdk). The SDK derives the `/compatible-mode/v1/systemone` endpoint from your workspace and region automatically.
    - **Java**: DashScope SDK **2.23.3 or later**. The decision model is new in 2.23.3 — older versions do not have the `com.alibaba.dashscope.decision` package. Maven coordinates: `com.alibaba:dashscope-sdk-java:2.23.3` (Gradle: `implementation group: 'com.alibaba', name: 'dashscope-sdk-java', version: '2.23.3'`). The API key is read from the `DASHSCOPE_API_KEY` environment variable by default.
    - On failure, the Python SDK raises a `DashScopeError` exception and the Java SDK raises an `ApiException`.

    You can also use the generic TypeSafe SDK (`typesafe-sdk`) with `base_url` pointing to the Bailian gateway. The SDK automatically appends `/v1/systemone` and parses the response. Install: `pip install typesafe-sdk`.

    <Tabs>
      <Tab title="Ticket routing">
        A single request handles three decisions at once: team assignment (`choice`), escalation (`noul`), and severity (`score`). The example below uses the Singapore region.

        <Tabs>
          <Tab title="DashScope Python">
            ```python
            import os

            import dashscope

            # The following is the configuration for the Singapore region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
            # The decision model endpoint always sits under the compatible-mode path of the workspace gateway; the SDK derives it from workspace and region.
            client = dashscope.Client(
                # If you have not configured an environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
                api_key=os.getenv("DASHSCOPE_API_KEY"),
                workspace="{WorkspaceId}",
                region="ap-southeast-1",
            )

            result = client.decision.create(
                model="decision-model-preview",
                state={"ticket_id": "T-1001", "content": "More than 24 hours after payment, the order has not been credited."},
                questions={
                    "department": {"type": "choice", "instructions": "Which team should handle this?",
                                   "criteria": {"billing": "Payment, refund, and billing issues", "technical": "Product failure and integration issues"}},
                    "escalate": {"type": "noul", "instructions": "Should on-call staff be notified immediately?"},
                    "severity": {"type": "score", "instructions": "How severe is this issue?",
                                 "criteria": ["Minor issue, no impact on functionality", "Some functionality affected, but a workaround exists",
                                              "Core functionality unavailable, no workaround", "Severe business or security impact"]},
                },
            )

            print(result.answers["department"].choice)   # selected option
            print(result.answers["escalate"].noul)       # P(yes)
            print(result.answers["severity"].score)      # probability-weighted level index
            print(result.usage.input_tokens, result.latency_ms)
            ```
          </Tab>

          <Tab title="DashScope Java">
            ```java
            import com.alibaba.dashscope.decision.DecisionModel;
            import com.alibaba.dashscope.decision.DecisionModelParam;
            import com.alibaba.dashscope.decision.DecisionModelResult;
            import com.alibaba.dashscope.decision.DecisionQuestion;
            import com.alibaba.dashscope.utils.JsonUtils;
            import java.util.Arrays;
            import java.util.HashMap;
            import java.util.LinkedHashMap;
            import java.util.List;
            import java.util.Map;

            public class DecisionDemo {
              public static void main(String[] args) throws Exception {
                // The API key is read from the DASHSCOPE_API_KEY environment variable by default.
                // The constructor takes the workspace ID and region; the SDK derives
                // https://{WorkspaceId}.{region}.maas.aliyuncs.com/compatible-mode/v1/systemone
                Map<String, Object> state = new HashMap<>();
                state.put("ticket_id", "T-1001");
                state.put("content", "More than 24 hours after payment, the order has not been credited. The user cannot continue using core services and demands immediate handling.");

                Map<String, String> options = new LinkedHashMap<>();
                options.put("billing", "Payment, refund, and billing issues");
                options.put("technical", "Product failure and integration issues");

                List<String> levels = Arrays.asList(
                    "Minor issue, no impact on functionality",
                    "Some functionality affected, but a workaround exists",
                    "Core functionality unavailable, no workaround",
                    "Severe business or security impact");

                Map<String, DecisionQuestion> questions = new LinkedHashMap<>();
                questions.put("department", DecisionQuestion.choice("Which team should handle this?", options));
                questions.put("escalate", DecisionQuestion.noul("Should on-call staff be notified immediately?"));
                questions.put("severity", DecisionQuestion.score("How severe is this issue?", levels));

                DecisionModelParam param = DecisionModelParam.builder()
                    .model(DecisionModelParam.Models.DECISION_MODEL_PREVIEW)
                    .state(state)
                    .questions(questions)
                    .build();

                DecisionModel decisionModel = new DecisionModel("{WorkspaceId}", "ap-southeast-1");
                DecisionModelResult result = decisionModel.call(param);

                System.out.println(JsonUtils.toJson(result));
              }
            }
            ```
          </Tab>

          <Tab title="TypeSafe Python">
            ```python
            import os
            from typesafe_sdk import TypeSafeClient

            client = TypeSafeClient(
                api_key=os.environ["DASHSCOPE_API_KEY"],
                base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode",
            )

            result = client.system_one(
                model="decision-model-preview",
                state={"ticket_id": "T-1001", "content": "More than 24 hours after payment, the order has not been credited."},
                questions={
                    "department": {"type": "choice", "instructions": "Which team should handle this?",
                                   "criteria": {"billing": "Payment, refund, and billing issues", "technical": "Product failure and integration issues"}},
                    "escalate": {"type": "noul", "instructions": "Should on-call staff be notified immediately?"},
                    "severity": {"type": "score", "instructions": "How severe is this issue?",
                                 "criteria": ["Minor issue, no impact on functionality", "Some functionality affected, but a workaround exists",
                                              "Core functionality unavailable, no workaround", "Severe business or security impact"]},
                },
            )

            print(result.answers["department"])   # choice, confidence, probabilities
            print(result.answers["escalate"])     # noul P(yes)
            print(result.answers["severity"])     # score, legend, probabilities
            ```
          </Tab>

          <Tab title="curl">
            ```bash
            curl -sS -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/systemone \
              -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
              -H 'Content-Type: application/json' \
              -d '{
                "model": "decision-model-preview",
                "state": {"ticket_id": "T-1001", "content": "More than 24 hours after payment, the order has not been credited. The user cannot continue using core services and demands immediate handling."},
                "questions": {
                  "department": {"type": "choice", "instructions": "Which team should handle this?",
                                 "criteria": {"billing": "Payment, refund, and billing issues", "technical": "Product failure and integration issues"}},
                  "escalate":   {"type": "noul",  "instructions": "Should on-call staff be notified immediately?"},
                  "severity":   {"type": "score", "instructions": "How severe is this issue?",
                                 "criteria": ["Minor issue, no impact on functionality", "Some functionality affected, but a workaround exists",
                                              "Core functionality unavailable, no workaround", "Severe business or security impact"]}
                }
              }'
            ```
          </Tab>
        </Tabs>
      </Tab>

      <Tab title="Yes/no decision">
        A `noul` question returns P(yes), where 0 = no and 1 = yes. The example below uses the Singapore region.

        <Tabs>
          <Tab title="DashScope Python">
            ```python
            import os

            import dashscope

            client = dashscope.Client(
                # If you have not configured an environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
                api_key=os.getenv("DASHSCOPE_API_KEY"),
                workspace="{WorkspaceId}",
                region="ap-southeast-1",
            )

            result = client.decision.create(
                model="decision-model-preview",
                state="Is this comment asking for a refund?",
                questions={"refund": {"type": "noul", "instructions": "Is the user asking for a refund?"}},
            )

            print(result.answers["refund"].noul)   # P(yes)
            ```
          </Tab>

          <Tab title="DashScope Java">
            ```java
            import com.alibaba.dashscope.decision.DecisionModel;
            import com.alibaba.dashscope.decision.DecisionModelParam;
            import com.alibaba.dashscope.decision.DecisionModelResult;
            import com.alibaba.dashscope.decision.DecisionQuestion;
            import java.util.LinkedHashMap;
            import java.util.Map;

            public class DecisionDemo {
              public static void main(String[] args) throws Exception {
                Map<String, DecisionQuestion> questions = new LinkedHashMap<>();
                questions.put("refund", DecisionQuestion.noul("Is the user asking for a refund?"));

                DecisionModelParam param = DecisionModelParam.builder()
                    .model(DecisionModelParam.Models.DECISION_MODEL_PREVIEW)
                    .state("Is this comment asking for a refund?")
                    .questions(questions)
                    .build();

                DecisionModel decisionModel = new DecisionModel("{WorkspaceId}", "ap-southeast-1");
                DecisionModelResult result = decisionModel.call(param);

                System.out.println(result.getAnswers().get("refund").getNoul());   // P(yes)
              }
            }
            ```
          </Tab>

          <Tab title="TypeSafe Python">
            ```python
            import os
            from typesafe_sdk import TypeSafeClient

            client = TypeSafeClient(
                api_key=os.environ["DASHSCOPE_API_KEY"],
                base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode",
            )

            result = client.system_one(
                model="decision-model-preview",
                state="Is this comment asking for a refund?",
                questions={"refund": {"type": "noul", "instructions": "Is the user asking for a refund?"}},
            )

            print(result.answers["refund"])   # noul P(yes)
            ```
          </Tab>

          <Tab title="curl">
            ```bash
            curl -sS -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/systemone \
              -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
              -H 'Content-Type: application/json' \
              -d '{
                "model": "decision-model-preview",
                "state": "Is this comment asking for a refund?",
                "questions": {
                  "refund": {"type": "noul", "instructions": "Is the user asking for a refund?"}
                }
              }'
            ```
          </Tab>
        </Tabs>
      </Tab>
    </Tabs>
  </Column>
</Columns>

<Columns cols={2}>
  <Column>
    ## Response Parameters <span id="dm-300" />

    <strong>model</strong> · `String`

    Model name echoed back.

    <strong>request\_id</strong> · `String`

    Request ID, for troubleshooting.

    <strong>answers</strong> · `Object`

    A map of answers. The key corresponds to the question id in the request; the value is an answer object with the following fields.

    <Accordion title="Answer object properties">
      <strong>type</strong> · `String`

      Matches the question type (`choice` / `noul` / `score`).

      <strong>choice</strong> · `String`

      For `choice`: the selected option name.

      <strong>noul</strong> · `Float`

      For `noul`: P(yes), where 0 = no and 1 = yes.

      <strong>score</strong> · `Float`

      For `score`: the probability-weighted expectation of the level index, which can fall between two levels (e.g. `1.43`).

      <strong>probabilities</strong> · `Object`

      The probability of each option / level (sums to 1).

      <strong>confidence</strong> · `Float`

      The confidence of the answer (returned for `choice` / `score`).

      <strong>legend</strong> · `Object`

      For `score`: a map of level index → level description.
    </Accordion>

    <strong>usage</strong> · `Object`

    Metering information:

    - `input_tokens` (Integer): number of input tokens.

    <strong>latency\_ms</strong> · `Float`

    Server-side latency (milliseconds).
  </Column>

  <Column>
    ## Response Example <span id="dm-500" />

    The following is the response for the ticket routing example (abbreviated). Probabilities and confidence depend on the actual result.

    ```json expandable
    {
      "model": "decision-model-preview",
      "request_id": "7b986c65-b223-9341-b5f0-b988e27ecaac",
      "answers": {
        "department": {
          "type": "choice",
          "choice": "billing",
          "confidence": 0.88,
          "probabilities": {"billing": 0.94, "technical": 0.06}
        },
        "escalate": {
          "type": "noul",
          "noul": 0.99
        },
        "severity": {
          "type": "score",
          "score": 2.25,
          "confidence": 0.91,
          "legend": {
            "0": "Minor issue, no impact on functionality",
            "1": "Some functionality affected, but a workaround exists",
            "2": "Core functionality unavailable, no workaround",
            "3": "Severe business or security impact"
          },
          "probabilities": {"0": 0.0, "1": 0.01, "2": 0.73, "3": 0.26}
        }
      },
      "usage": {"input_tokens": 125},
      "latency_ms": 52.9
    }
    ```
  </Column>
</Columns>

## Error Codes <span id="dm-600" />

If the call fails, an error message is returned. For more error codes and solutions, see [Error messages](/help/en/model-studio/error-code).