伺服器工具

伺服器工具是 Synthorai 在單一請求內替你執行的能力:模型提出需求,我們完成工作,結果隨同一個回應返回。你只需在 tools 加一個條目——沒有第二個端點,也沒有需要實作的回呼。

可用工具

每個伺服器工具都以 synthorai: 前綴識別,因此永遠不會與你自己的工具名稱衝突:

參數	說明	價格
`synthorai:web_search`	搜尋網路並閱讀結果。	$0.01
`synthorai:web_fetch`	讀取你已有 URL 的頁面全文。	$0.01

共同契約

每個伺服器工具的行為都一致,學會一個就通用於下一個:

僅限主動選用。除非你把工具放進 tools,否則什麼都不會執行。不含工具的請求就是普通請求。
一次往返完成。工具迴圈由我們代為驅動;你收到的是單一回應,工具活動與答案都已在其中。
你自己的工具照常運作。伺服器工具與你的 function 工具可以一起宣告——當模型呼叫你的工具時,我們會以誠實的 stop_reason: tool_use 把控制權交還給你執行。(唯一例外:我們注入的工具名稱是保留的——見下文。)
按次計價,在 usage 中可見。次數記入 usage.server_tool_use,費用記入 usage.cost,因此每個請求都能與帳單對帳。
max_uses 是真實上限。它限制單一請求能花多少,且在內部重試之間依然有效。

Token 是成本的另一半

伺服器工具的按次費用只是請求成本的一部分。工具帶回的內容——搜尋摘要、頁面正文——會作為輸入 token 進入對話,按模型的正常費率計費。對長頁面來說,token 成本通常才是大頭。而且由於閘道在內部驅動工具迴圈,usage.input_tokens 是所有內部回合的總和,會明顯大於你送出的提示。這是把結果回饋給模型的實際成本,不是重複計費。

延續對話

把 assistant 訊息原樣(含工具區塊)附加回 messages。後續請求持續宣告同一個伺服器工具,歷史就能保持最完整的形式;若移除工具,先前的工具結果會被攤平成純文字,但模型仍看得到內容。

保留工具名稱

使用 synthorai: 參數期間,對應的裸名稱即被保留:在 synthorai:web_search 旁宣告你自己名為 web_search 的工具(或在 synthorai:web_fetch 旁宣告 web_fetch)會收到點名該工具的 400。請改名,或移除 synthorai: 參數。

原因是我們正是以那個名稱注入伺服器工具,兩個工具會以同一個名字到達模型,誰也分不清回來的是誰的呼叫——你工具的參數可能被送往我們的搜尋供應商,你的呼叫也可能遺失。拒絕請求是唯一誠實的回答。在沒有對應 synthorai: 參數時,以任一名稱宣告你自己的工具不受影響:我們什麼都不注入,自然什麼都不衝突。

失敗不收費

按次費用只對產生了結果的呼叫收取。在離開我們網路之前就被拒絕的呼叫——被駁回的 URL、被封鎖的網域、未配置的後端——不收費。到達供應商端並在那裡失敗的呼叫會收費,因為供應商向我們收了費。無論哪種情況,該回合仍計入 max_uses 預算,因此重試壞 URL 的模型無法免費空轉。

支援哪些端點

伺服器工具運行在 /v1/messages、/v1/chat/completions 與 /v1/responses 上。把 synthorai: 參數送到不支援它們的端點(Gemini 端點)會收到明確告知的 400。我們寧可拒絕,也不把未知工具傳給上游:最好的情況是令人困惑的第三方錯誤,最壞的情況是它被靜默忽略、搜尋從未發生,而你為一個悄悄少做了事的普通請求付了費。

可用性

伺服器工具按 API 金鑰啟用。若某工具未對你的金鑰啟用,你會收到明確點名該工具的 400,而不是被靜默忽略的參數。請聯絡我們開通。