工具參考手冊

每個內建工具的輸入、有效值、輸出格式，以及每種呼叫路徑可能回傳的錯誤 — 快速入門指南背後的完整參考資料。

前面的指南能讓您快速完成一次可運作的呼叫。這一頁則是您在真正整合時會回頭查閱的參考資料：每個工具的輸入與有效值、各自的輸出內容，以及您可能拿到的確切錯誤 — 並依您是匿名呼叫還是使用金鑰呼叫來區分，因為這兩種路徑的行為並不相同。

工具一覽

以下工具都可以匿名呼叫（無需 API 金鑰，但有速率限制），使用您的第一次 SDK 呼叫中的模式，也是公開 Tools 頁面上展示的那些工具。這些工具也可以使用已認證的方式呼叫（API 金鑰／JWT）— 參見取得您的 API 金鑰與選擇您的認證模式。

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

輸入	型別	是否必填	有效值	說明
`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`。不會被儲存 — 僅套用於本次呼叫。

輸出： translation（翻譯後的文字）、applied_terms（實際套用了哪些詞彙表項目，如果有的話）。

const out = await ai.run({
  pipeline: "translate-string",
  inputs: { text: "Hello", target_language: "de" },
});
// out.translation === "Hallo"

輸入	型別	是否必填	有效值	說明
`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 中的任何一項。

輸入	型別	是否必填	有效值	說明
`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。

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

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

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

輸出： subject、body、applied_terms。

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

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

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

您可能拿到哪些錯誤，取決於您的呼叫方式 — 匿名呼叫與已認證呼叫的驗證方式不同。請勿假設某一種路徑的錯誤行為也適用於另一種路徑。

也就是您的第一次 SDK 呼叫中的模式 — 可呼叫上方列出的所有工具，並依 IP 進行速率限制。

狀態碼	錯誤代碼	意義
404	—	未知的工具 slug。
403	—	機器人檢查未通過。
429	`guest_quota_exceeded`	您已達到匿名每 IP 或全域每日請求次數上限。
429	`guest_cost_exceeded`	您已達到匿名每 IP 或全域每日費用上限（成本較高的工具會更快耗盡這個額度）。
202	—	成功 — `{ ticket_id, status: "QUEUED" }`。請以與其他呼叫相同的方式輪詢結果。

注意： 在這條路徑上，您的 inputs 在呼叫被接受之前不會依照上方的表格進行檢查 — 缺少必填欄位或值無效並不會讓您拿到 400。而是這次執行本身會失敗，您會在輪詢結果時看到這個結果。當您取得 API 金鑰之後，請改用下方的已認證路徑，它會在事前就進行驗證。

也就是選擇您的認證模式中的模式 — 可呼叫您有權限使用的所有工具。

狀態碼	錯誤代碼	意義
401	—	憑證缺漏、無效或已過期。
403	`app_disabled`	您的應用程式已被停用。
403	`org_suspended`	您的組織已被停權。
403	`org_pending_deletion`	您的組織已排定刪除。
403	—	此工具不在您憑證的允許 pipeline 清單中。
400	—	您的 `inputs` 不符合該工具的要求（缺少必填欄位、值無效，或輸入總量過大）。與匿名路徑不同，這條路徑會事前進行驗證。
429	`rate_limited`	您送出請求的速度超過每分鐘限制。
429	`quota_exceeded`	您已達到每月請求配額上限。
429	`daily_cost_exceeded`	您已達到每日費用上限 — 這是速度型限制，與下方餘額用盡的情況不同。
402	`insufficient_credits`	您組織的 credit 餘額不足以支付這次呼叫。請儲值後再重試。
202	—	成功 — `{ ticket_id, status: "QUEUED" }`。請輪詢結果。

若想更深入了解憑證運作方式，以及 401/403/429 認證判斷邏輯，請參見選擇您的認證模式。