Raw prompt mode

略過具名 pipeline，直接把自訂的 system/user prompt 送給模型 — 請求格式、模型選擇，以及不適用於具名 pipeline 的限制。

本節其他每一篇指南呼叫的都是具名 pipeline（translate-string、summarize 等）— 也就是有宣告輸入的固定 prompt 範本。Raw mode 略過範本：您直接送出自己的 system_prompt 與 user_prompt，平台會原封不動地執行它。適合用在把一個 prompt 打造成真正的 pipeline 之前先做原型測試，或是不適合任何一個內建工具的一次性呼叫。

啟用它

Raw mode 與具名 pipeline 是分開閘控的。您 JWT 的 pipelines[] claim 需要一個明確的 "raw" 項目 — 與用於具名 pipeline ID 的是同一個 claim，只是多了這一個額外的字串。它預設不會被授予，而且大多數終端使用者的 session token 永遠都不應該擁有它：具名 pipeline 的成本受限於它的範本，但 raw prompt 的成本只受限於您願意送出多長的 prompt，以及您要求模型產生多少 token。

如果您的 app 是自行發行 session token（見 Node.js server integration 的 POST /auth/token 章節），請只針對真正需要的特定 token 請求 "raw" — 例如內部的管理工具，而不是發給任意終端使用者的 token。在您用這個 claim 請求 token 之前，請先向平台維運方確認您 Application 的 allowed_pipelines 包含 "raw"；若您的 Application 沒有被允許授予某個 claim，該 claim 會被靜默地從發出的 token 中移除。

靜態的 x-api-key（unbound、operator 範圍 — 見取得您的 API 金鑰）會完全略過 pipeline 清單檢查，這一點與具名 pipeline 相同。 Console 發行、綁定 app 的 x-api-key，以及 JWT／webtoken 呼叫者，兩者都需要明確的 "raw" 授權。

呼叫方式 — SDK

const out = await ai.run({
  raw: {
    system_prompt: "You are a terse assistant. Answer in one sentence.",
    user_prompt: "What does raw mode skip that a named pipeline has?",
    model: "gpt-5-mini",   // optional — see "Choosing a model" below
    temperature: 0.2,       // optional
    max_tokens: 500,        // optional, up to 32768
  },
});
console.log(out.text);

user_prompt 在搭配 ai.runMany(...) 使用時，也可以是 inputs 的函式 — 該模式請見 SDK 更完整的 Integration Guide（它並非公開文件，請洽您的平台維運方索取副本）。ai.button(...) 也接受用 raw 設定取代 pipeline。

呼叫方式 — 直接 HTTP

需要帶有 "raw" 授權的 Authorization: Bearer <jwt>（若是 unbound 的 operator 類型，靜態的 x-api-key 也可以 — 見上方）。params 是選填的，其中兩個欄位也都是選填的：

curl -X POST "https://api.quravin.com/tickets" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-jwt>" \
  -d '{
    "mode": "raw",
    "system_prompt": "You are a terse assistant. Answer in one sentence.",
    "user_prompt": "What does raw mode skip that a named pipeline has?",
    "model": "gpt-5-mini",
    "params": { "temperature": 0.2, "max_tokens": 500 }
  }'

回應（202），接著以與其他 ticket 相同的方式輪詢 — 如果您還沒建立那個輪詢迴圈，請見 Direct API 整合：

{ "ticket_id": "01J...ULID", "status": "QUEUED" }

curl "https://api.quravin.com/tickets/01J...ULID" \
  -H "Authorization: Bearer <your-jwt>"

完成後的回應 — 不論是哪個模型執行的，格式永遠是相同的四個欄位加上 text：

{
  "ticket_id": "01J...ULID",
  "status": "DONE",
  "mode": "raw",
  "result": {
    "text": "It skips the fixed prompt template and declared input schema.",
    "model": "gpt-5-mini",
    "latency_ms": 640,
    "tokens_in": 38,
    "tokens_out": 14
  },
  "created_at": "2026-07-10T12:00:00.000Z",
  "updated_at": "2026-07-10T12:00:02.000Z"
}

沒有 pipeline 專屬的欄位需要查找（沒有 translation，也沒有 tldr）— result.text 永遠是模型輸出的落點。

選擇模型

model 是選填的 — 省略即可使用平台目前的預設值。若您明確指定，它必須是平台已有驗證成本費率的模型，這會在呼叫送達 LLM 之前就先檢查：送出清單以外的值，您會拿到 400 invalid_model，而不是一筆昂貴的意外支出。截至本文撰寫時，該清單為 gpt-4o-mini、gpt-4o、o3 與 gpt-5-mini — 請洽您的平台維運方取得目前的清單，因為它會隨著新模型加入而變動。

與具名 pipeline 的差異

沒有 input schema。 具名 pipeline 會在呼叫被接受之前，依照其宣告的 schema 驗證您的 inputs（欄位缺漏、型別錯誤 → 400）。Raw mode 沒有 schema — system_prompt 與 user_prompt 是必填的字串，但它們的內容永遠不會被驗證。一個對模型來說毫無意義的 prompt 不會在事前就失敗；ticket 會照樣執行，您會在輪詢結果時才發現。
沒有快取。 具名 pipeline 會依輸入內容快取相同的呼叫。Raw mode 永遠不會檢查快取 — 即使您連續兩次送出完全相同的 prompt，每次呼叫都是一次全新的模型呼叫。
全域的輸入大小防線依然適用，只是量測方式不同：system_prompt.length + user_prompt.length 相加後，必須低於平台的字元數上限（預設 50,000）— 與限制具名 pipeline inputs 的是同一個縱深防禦上限，只是改成加總這兩個欄位，而不是整個 JSON body。
max_tokens 上限為 32768，不論底層模型原本允許多少 — 這是單次呼叫最壞情況的上限，不是一個目標值。

錯誤

與其他呼叫相同的已認證路徑錯誤對照表 — 完整清單請見 Direct API 整合。有一個錯誤是 raw mode 專屬的： 400 invalid_model，說明見上方。

若您的 JWT 沒有 "raw" 授權，您會拿到與呼叫未被允許的具名 pipeline 相同的 403 — 憑證授權的運作方式，請見選擇您的認證模式。