工具參考手冊

每個內建工具的輸入、有效值、輸出格式 — 快速入門指南背後的完整參考資料。

前面的指南能讓您快速完成一次可運作的呼叫。這一頁則是您在真正整合時會回頭查閱的參考資料：每個工具的輸入與有效值，以及各自的輸出內容。至於每種呼叫路徑（匿名 vs. 已認證）確切的 HTTP 請求／回應格式，以及完整的錯誤對照表，請見 Direct API 整合。

工具一覽

以下工具都可以透過 POST /tools/:slug/run 匿名呼叫，也就是您的第一次 SDK 呼叫中的模式，也是公開 Tools 頁面上展示的那些工具。它們也可以透過 POST /tickets 已認證呼叫 — 參見取得您的 API 金鑰與選擇您的認證模式。

這兩者是各自獨立的 HTTP endpoint，並不是同一個 endpoint 用 header 區分而已，對同一個工具也會回傳不同的輸出欄位名稱 — 兩者各自完整的請求／回應格式，請見 Direct API 整合。

每個工具都同時有一個 slug（公開 Tool Portal 與 POST /tools/:slug/run 使用）與一個 pipeline_id（ai.run({ pipeline: ... }) 與 POST /tickets 使用）。除了 translate 之外，每個工具的這兩個值都相同 — translate 的 slug 是 translate，但 pipeline_id 是 translate-string — 請依您實際呼叫的方式使用正確的那一個。

工具	slug	pipeline_id	Credits
Translate	`translate`	`translate-string`	1
Summarize	`summarize`	`summarize`	1
Rewrite	`rewrite`	`rewrite`	1
Grammar fix	`grammar-fix`	`grammar-fix`	1
Email generator	`email-generator`	`email-generator`	2
Knowledge base Q&A	`knowledge-base-qa`	`knowledge-base-qa`	2

Credits 是每次執行實際從您的方案／錢包中扣除的費用 — 在您圍繞某個工具打造功能之前，請先確認這個數字。

以上都不符合您的需求？Raw prompt mode 讓您可以送出自訂的 system/user prompt，取代這些固定範本 — 它需要您的憑證另外取得授權，所以大多數整合應該先從上述工具著手，只有在沒有一個符合情境時，才考慮改用 raw 模式。

「有效值」只是指引，並非伺服器端強制檢查 — 即使是已認證路徑也一樣。 對於下方每一個 select／enum 類型的欄位（target_language、language、extract、action、tone 等），已認證的 POST /tickets 路徑只會驗證該欄位是否存在（若為必填）、型別與大小是否正確 — 並不會檢查其值是否為表列選項之一。傳入表列以外的值，會直接原封不動送到 LLM，匿名與已認證兩條路徑皆然。只有 required／型別／長度會被強制檢查。

translate

slug：translate · pipeline_id：translate-string

輸入	型別	是否必填	有效值	說明
`text`	string	是	最多 5000 字元	來源文字。語言會自動偵測 — 您不需要指定來源語言。
`target_language`	string	是	`en`、`es`、`de`、`ja`、`fr`、`pt`、`zh-Hans`、`zh-Hant`、`ko`、`ar`、`vi`、`th`、`ms`	要翻譯成的目標語言代碼。
`glossary_inline`	string	否	最多 4000 字元	選用的詞彙覆寫，每行一組，格式為 `source=target` 或 `source,target`。不會被儲存 — 僅套用於本次呼叫。

輸出（已認證 /tickets 格式）： translation（翻譯後的文字）、applied_terms（實際套用了哪些詞彙表項目，如果有的話）。匿名的 Tool Portal 路徑會將此正規化為 result.text — 兩個 endpoint 完整的請求／回應格式，請見 Direct API 整合。

const out = await ai.run({
  pipeline: "translate-string",   // pipeline_id，不是 "translate" 這個 slug
  inputs: { text: "Hello", target_language: "de" },
});
// out.translation === "Hallo"

summarize

slug：summarize · pipeline_id：summarize

輸入	型別	是否必填	有效值	說明
`text`	string	是	最多 5000 字元	要摘要的來源文字。
`length`	string	否	`short`、`medium`、`long`	省略則使用預設長度。
`language`	string	否	`""`（保留原文語言）或上方 translate 對照表中的任一代碼	輸出語言。空字串會保留來源文字的語言。
`extract`	string[]	否	`action_items`、`decisions`、`risks`、`timeline`	零個或多個額外的結構化區段。請依此確切順序傳送 — 順序不同就會被視為不同的請求（即使值本身相同），這會影響快取。

輸出： tldr、key_points，以及您在 extract 中要求的 action_items / decisions / risks / timeline 中的任何一項。

rewrite

slug：rewrite · pipeline_id：rewrite

輸入	型別	是否必填	有效值	說明
`text`	string	是	最多 5000 字元	要改寫的來源文字。
`action`	string	否	`rephrase`、`shorten`、`expand`、`simplify`、`formalize`、`bulletize`	改寫操作的類型。
`tone`	string	否	`professional`、`casual`、`friendly`、`concise`	目標語氣。
`language`	string	否	`""`（保留原文語言）或上方 translate 對照表中的任一代碼	輸出語言。
`glossary_inline`	string	否	最多 4000 字元	格式與上方 translate 的 `glossary_inline` 相同。

輸出： rewrite（改寫後的文字）、applied_terms。

grammar-fix

slug：grammar-fix · pipeline_id：grammar-fix

輸入	型別	是否必填	有效值	說明
`text`	string	是	最多 5000 字元	要校正的來源文字。
`glossary_inline`	string	否	最多 4000 字元	格式與上方 translate 的 `glossary_inline` 相同。

輸出： corrected（校正後的文字）、changes（變更內容的清單）、applied_terms。

email-generator

slug：email-generator · pipeline_id：email-generator

輸入	型別	是否必填	有效值	說明
`purpose`	string	是	最多 2000 字元	這封信的主旨，以及應該涵蓋的內容。
`recipient`	string	否	最多 500 字元	收件對象。省略則使用通用收件人。
`tone`	string	否	`formal`、`friendly`、`persuasive`	草擬信件的語氣。
`glossary_inline`	string	否	最多 4000 字元	格式與上方 translate 的 `glossary_inline` 相同。

輸出： subject、body、applied_terms。

knowledge-base-qa

slug：knowledge-base-qa · pipeline_id：knowledge-base-qa

輸入	型別	是否必填	有效值	說明
`question`	string	是	最多 1000 字元	要回答的問題。
`context`	string	是	最多 6000 字元	答案必須依據的單一文件。

輸出： answer、grounded（此答案是否確實由 context 支持）、citation（答案出自 context 中的哪個部分）。

這個工具背後沒有搜尋索引或外部知識庫 — 它永遠只依據同一次請求中的 context 文字來回答。如果您的來源文件超過約 6000 字元，請自行切分文字，並依每個切塊分別呼叫。

錯誤

您可能拿到哪些錯誤，取決於您的呼叫方式 — 匿名呼叫與已認證呼叫的驗證方式不同，各自也有完整的對照表。完整的匿名與已認證錯誤對照表（狀態碼、錯誤代碼，以及各自代表的意義），請見 Direct API 整合；若想更深入了解憑證授權的運作方式，請見選擇您的認證模式。