服务端工具

服务端工具是 Synthorai 在**一次请求内**替你执行的能力:模型提出需求,我们把活干完,结果随同一个响应回来。你只需要在 tools 里加一个条目 —— 没有第二个接口要调,也没有回调要实现。

可用工具

所有服务端工具都带 synthorai: 前缀,因此绝不会和你自己的工具重名:

参数	说明	价格
`synthorai:web_search`	联网搜索并读取结果。	$0.01
`synthorai:web_fetch`	读取你已知 URL 的那个页面的完整正文。	$0.01

统一契约

所有服务端工具的行为一致,学会一个就会用下一个:

必须显式声明。不放进 tools 就什么都不会发生,请求与普通请求无异。
一次往返。工具循环由我们驱动;你拿到的是一个响应,里面已经包含工具活动与最终答案。
你自己的工具照常可用。服务端工具与你的函数工具可以同时声明 —— 模型调用你的工具时,我们把控制权交回,并如实给出 stop_reason: tool_use。(唯一例外:我们注入的那两个工具名是保留的,见下文。)
按次计价,usage 可见。次数落在 usage.server_tool_use,金额落在 usage.cost,每一笔请求都能自己对上账。
max_uses 是真闸。它封顶单次请求的花费,并且跨内部重试仍然成立。

Token 是成本的另一半

按次费只是请求成本的一部分。工具带回来的东西 —— 搜索摘要、页面正文 —— 会作为 input token 进入对话,按模型的正常单价计费;长页面上这部分通常是更大的一笔。另外,由于网关在内部驱动工具循环,usage.input_tokens 是**各内部轮次的累加值**,会明显大于你发送的 prompt。这是把结果喂回模型的真实成本,不是重复计费。

继续多轮对话

把 assistant 消息**原样**(含工具块)放回 messages 即可。后续请求建议继续声明同一个服务端工具,历史会保持在信息最完整的形态;如果不再声明,早先的工具结果会被扁平成纯文本,模型仍然看得到内容。

保留的工具名

使用 synthorai: 参数期间,对应的裸工具名是保留的:与 synthorai:web_search 同时声明一个你自己叫 web_search 的工具(web_fetch 同理),会返回一条指明工具名的 400。把你的工具改个名,或者去掉 synthorai: 参数即可。

原因是我们正是以那个名字把服务端工具注入给模型的。两个同名工具同时到达模型时,双方都无法判断回来的调用是谁的 —— 你的工具参数可能被送去我们的搜索后端,而你的调用可能收不回来。拒绝请求是唯一诚实的做法。若你**没有**使用对应的 synthorai: 参数,那么用这两个名字声明自己的工具完全不受影响:我们不注入,也就不会冲突。

失败不向你收费

按次费只对**真的拿到结果**的调用收取。被我们在出网之前拒掉的调用 —— URL 不合法、命中域名黑名单、后端未配置 —— 一分不收。已经打到后端却失败的调用会收费,因为后端向我们收了钱。两种情况都仍然计入你的 max_uses 预算,所以模型在一个坏 URL 上反复重试不会变成免费的死循环。

哪些端点支持

服务端工具运行在 /v1/messages、/v1/chat/completions 与 /v1/responses 上。把 synthorai: 参数发到不支持它们的端点(Gemini 端点)会返回一条说明情况的 400。我们宁可拒绝,也不把一个未知工具直发上游:那样最好的结果是拿到一条看不懂的第三方报错,最坏的结果是它被静默忽略 —— 搜索从未发生,而你为一次看似正常的请求付了钱。

开通方式

服务端工具按 API key 开通。没开通的 key 会收到一个明确指出该工具的 400,而不是参数被静默忽略。需要开通请联系我们。