快速入門

您的第一個具型別決策

以下範例展示合約的格式。這些範本需要已授權的 API 金鑰;請以電子郵件連結或 Google 登入,在儀表板建立金鑰,然後兌換邀請碼,或從 1 歐元起儲值。

示意範例

請將 DECISIONMODELS_API_KEY 設為您儀表板中的金鑰。切勿將真實的 API 金鑰放進原始碼版本控制或瀏覽器的打包檔中。

請先在 shell 中設定金鑰;下方的每個 curl 範例都會讀取它:

Shell
export DECISIONMODELS_API_KEY="paste-your-key-here"

文字打包

針對同一個 state 最多提出三個問題

s1-pro 與 reax-1 可在同一個 questions 映射中接受最多三個具名的文字問題。共用的文字只計費一次;每個問題會增加提示詞 token。計費總數由模型的分詞器決定,並以模型的輸入上限為限(每個問題含其 state,依模型而定為 8,000 至 8,192 個 token;請見限制表)。每個問題都是分別評估的;打包並不保證速度會變快。

s1-fast、s1-vision 與 quyet-1-large 接受一個問題。容量吃緊時,打包請求可能回傳可重試的 503 model_unavailable 或 capacity_limit。歐盟請求優先。重複使用同一個冪等鍵(idempotency key)會回傳原本的用量收據,不會再次扣款;原始回答不會被保留。

01 / 請求與回應

點選範例決策

這些範例各含一個具型別的問題。s1-pro 與 reax-1 最多支援三個;s1-fast、s1-vision 與 quyet-1-large 支援一個。選擇一個範例,即可查看其請求本文與回應的格式。

請求 · POST /v1/systemone
{
  "model": "s1-fast",
  "state": "Mia owns a red bicycle.",
  "questions": {
    "color": {
      "type": "choice",
      "instructions": "Which color is the bicycle?",
      "criteria": {"red": null, "blue": null}
    }
  }
}
回應 · 示意
{
  "id": "dec_example",
  "model": "s1-fast",
  "answers": {
    "color": { "type": "choice", "choice": "red", "confidence": 0.91,
      "probabilities": { "red": 0.91, "blue": 0.09 } }
  },
  "usage": { "input_tokens": 328, "output_tokens": 0, "decisions": 1 },
  "tier": "eu"
}
請求 · POST /v1/systemone
{"model":"s1-fast","state":{"message":"I need to update my invoice address.","account_type":"business"},"questions":{"route":{"type":"choice","instructions":"Choose the support queue that best fits the request.","criteria":{"billing":null,"technical":null,"account":null}}}}
回應 · 示意
{"id":"dec_route","model":"s1-fast","answers":{"route":{"type":"choice","choice":"billing","confidence":0.87,"probabilities":{"billing":0.87,"technical":0.09,"account":0.04}}},"usage":{"input_tokens":351,"output_tokens":0,"decisions":1},"tier":"eu"}
請求 · POST /v1/systemone
{"model":"s1-fast","state":{"action":"delete_workspace","actor_role":"viewer"},"questions":{"allowed":{"type":"noul","instructions":"Is this action allowed under the stated role policy?"}}}
回應 · 示意
{"id":"dec_guard","model":"s1-fast","answers":{"allowed":{"type":"noul","noul":0.04}},"usage":{"input_tokens":298,"output_tokens":0,"decisions":1},"tier":"eu"}
請求 · POST /v1/systemone
{"model":"s1-pro","state":{"draft":"Short release note draft","rubric":"Clarity and factual support"},"questions":{"quality":{"type":"score","instructions":"Rate the draft against the rubric.","criteria":["low","medium","high"]}}}
回應 · 示意
{"id":"dec_score","model":"s1-pro","answers":{"quality":{"type":"score","score":1.57,"confidence":0.71,"legend":{"0":"low","1":"medium","2":"high"},"probabilities":{"0":0.05,"1":0.33,"2":0.62}}},"usage":{"input_tokens":512,"output_tokens":0,"decisions":1},"tier":"eu"}

02 / 從您的技術堆疊呼叫

七種語言的可複製範例

每個範例都送出相同的請求:對歐盟層級的 s1-fast 提出一個 choice 問題。請將金鑰存放在環境變數中。

curl · 示意
curl https://api.decisionmodels.io/v1/systemone \
  -H "Authorization: Bearer $DECISIONMODELS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "S1-Region: eu" \
  -d '{  "model": "s1-fast",  "state": "Mia owns a red bicycle.",  "questions": {    "color": {      "type": "choice",      "instructions": "Which color is the bicycle?",      "criteria": {"red": null, "blue": null}    }  }}'
Python · 示意
import os
import requests

response = requests.post(
    "https://api.decisionmodels.io/v1/systemone",
    headers={
        "Authorization": f"Bearer {os.environ['DECISIONMODELS_API_KEY']}",
        "Content-Type": "application/json",
        "S1-Region": "eu",
    },
    json={
        "model": "s1-fast",
        "state": "Mia owns a red bicycle.",
        "questions": {
            "color": {
                "type": "choice",
                "instructions": "Which color is the bicycle?",
                "criteria": {"red": None, "blue": None},
            }
        },
    },
    timeout=30,
)
print(response.json())
JavaScript · 示意
const response = await fetch("https://api.decisionmodels.io/v1/systemone", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.DECISIONMODELS_API_KEY,
    "Content-Type": "application/json",
    "S1-Region": "eu",
  },
  body: JSON.stringify({
    model: "s1-fast",
    state: "Mia owns a red bicycle.",
    questions: {
      color: { type: "choice", instructions: "Which color is the bicycle?",
        criteria: { red: null, blue: null } },
    },
  }),
});
if (!response.ok) throw new Error("HTTP " + response.status);
const result = await response.json();
console.log(result.answers.color);
TypeScript · 示意
type DecisionAnswer = {
  type: "noul" | "choice" | "score";
  choice?: string;
  noul?: number;
  score?: number;
  confidence?: number;
  legend?: Record<string, string>;
  probabilities?: Record<string, number>;
};
type DecisionResponse = {
  id: string;
  model: string;
  answers: Record<string, DecisionAnswer>;
  usage: { input_tokens: number; output_tokens: number; decisions: number };
  tier: "eu" | "global";
};

const response = await fetch("https://api.decisionmodels.io/v1/systemone", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.DECISIONMODELS_API_KEY,
    "Content-Type": "application/json",
    "S1-Region": "eu",
  },
  body: JSON.stringify({
    model: "s1-fast",
    state: "Mia owns a red bicycle.",
    questions: {
      color: { type: "choice", instructions: "Which color is the bicycle?",
        criteria: { red: null, blue: null } },
    },
  }),
});
if (!response.ok) throw new Error("HTTP " + response.status);
const result = (await response.json()) as DecisionResponse;
console.log(result.answers.color);
Rust · 示意
// cargo add reqwest --features json
// cargo add tokio --features full
// cargo add serde_json
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = reqwest::Client::new();
    let body = serde_json::json!({
        "model": "s1-fast",
        "state": "Mia owns a red bicycle.",
        "questions": {
            "color": { "type": "choice",
                "instructions": "Which color is the bicycle?",
                "criteria": { "red": null, "blue": null } }
        }
    });
    let response = client
        .post("https://api.decisionmodels.io/v1/systemone")
        .bearer_auth(std::env::var("DECISIONMODELS_API_KEY").expect("DECISIONMODELS_API_KEY"))
        .header("S1-Region", "eu")
        .json(&body)
        .send().await?;
    println!("{}", response.text().await?);
    Ok(())
}
C# · 示意
using System.Net.Http.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization",
    "Bearer " + Environment.GetEnvironmentVariable("DECISIONMODELS_API_KEY"));
client.DefaultRequestHeaders.Add("S1-Region", "eu");

var body = new {
    model = "s1-fast",
    state = "Mia owns a red bicycle.",
    questions = new {
        color = new { type = "choice",
            instructions = "Which color is the bicycle?",
            criteria = new { red = (string?)null, blue = (string?)null } }
    }
};
var response = await client.PostAsJsonAsync(
    "https://api.decisionmodels.io/v1/systemone", body);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
Java · 示意
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class DecisionModelsQuickstart {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        String body = """
          {"model":"s1-fast","state":"Mia owns a red bicycle.",
           "questions":{"color":{"type":"choice",
             "instructions":"Which color is the bicycle?",
             "criteria":{"red":null,"blue":null}}}}""";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.decisionmodels.io/v1/systemone"))
            .header("Authorization", "Bearer " + System.getenv("DECISIONMODELS_API_KEY"))
            .header("Content-Type", "application/json")
            .header("S1-Region", "eu")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
        System.out.println(client.send(request,
            HttpResponse.BodyHandlers.ofString()).body());
    }
}

還沒有額度嗎?API 會回應 402 insufficient_credit,並附上從 1 歐元起儲值的連結。

回應是示意性的API 請求與回應格式,並非實際測得的模型輸出。用量收據會載明實際的輸入 token 數,並且在啟用計費時,載明精確的整數 nanos 費用。

03 / 圖片決策

使用 s1-vision 針對一張圖片做出決策

搭配模型 s1-vision、一個 state 與一個問題,傳送恰好一張 PNG、JPEG 或 WebP 圖片,格式可為 base64 data URL 或公開的 HTTPS URL(解碼後最大 4 MiB、2,000,000 像素)。圖片會以模型實際讀取的輸入 token 計算(通常約 300–450)。含有圖片的請求,其所有輸入 token(文字與圖片位置)皆依 s1-vision 的圖片費率計費;僅含文字的 s1-vision 請求則使用 s1-vision 的文字費率。HTTPS URL 只會由閘道擷取一次,且不會被儲存。

curl
IMG=$(base64 -w0 photo.jpg)
curl https://api.decisionmodels.io/v1/multimodal \
  -H "Authorization: Bearer $DECISIONMODELS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "S1-Region: eu" \
  -d '{
    "model": "s1-vision",
    "state": "Customer return request: item arrived damaged.",
    "questions": {
      "damage": {
        "type": "choice",
        "instructions": "What does the photo show?",
        "criteria": {"visible_damage": null, "no_damage": null, "not_the_product": null}
      }
    },
    "images": ["data:image/jpeg;base64,'"$IMG"'"]
  }'
Python
import base64, os, requests

with open("photo.jpg", "rb") as f:
    image = "data:image/jpeg;base64," + base64.b64encode(f.read()).decode()

response = requests.post(
    "https://api.decisionmodels.io/v1/multimodal",
    headers={
        "Authorization": f"Bearer {os.environ['DECISIONMODELS_API_KEY']}",
        "S1-Region": "eu",
    },
    json={
        "model": "s1-vision",
        "state": "Customer return request: item arrived damaged.",
        "questions": {
            "damage": {
                "type": "choice",
                "instructions": "What does the photo show?",
                "criteria": {"visible_damage": None, "no_damage": None, "not_the_product": None},
            }
        },
        "images": [image],
    },
    timeout=10,
)
response.raise_for_status()
print(response.json()["answers"]["damage"])
JavaScript (Node 18+)
import { readFile } from "node:fs/promises";

const image = "data:image/jpeg;base64," + (await readFile("photo.jpg")).toString("base64");
const response = await fetch("https://api.decisionmodels.io/v1/multimodal", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.DECISIONMODELS_API_KEY,
    "Content-Type": "application/json",
    "S1-Region": "eu",
  },
  body: JSON.stringify({
    model: "s1-vision",
    state: "Customer return request: item arrived damaged.",
    questions: {
      damage: {
        type: "choice",
        instructions: "What does the photo show?",
        criteria: { visible_damage: null, no_damage: null, not_the_product: null },
      },
    },
    images: [image],
  }),
});
if (!response.ok) throw new Error("HTTP " + response.status);
console.log((await response.json()).answers.damage);

https://api.system1models.ai 也仍可繼續使用。