跳转到主要内容
POST
创建响应

使用服务器工具

在 tools 中、你自己的函数工具旁添加一个 phaseo: 工具,模型调用它时由 Phaseo 运行。/v1/responses 接受所有服务器工具,包括仅此端点支持的 phaseo:apply_patch;服务器工具指南列出了这些工具。
每次服务器工具调用都会计入 usage.server_tool_use: 旧的 gateway:datetime 类型仍然可用。设置 stream: true 时,Phaseo 会自行运行工具轮次,然后将后续回答作为单个流发送给你。

工具循环中的推理

在 OpenAI、Azure OpenAI 和 xAI 上,Phaseo 以 store: false 向上游发送 Responses 请求,因此模型的推理只能通过 reasoning 输出项在工具循环的各步骤之间延续。 每个 reasoning 项都有 id、summary 和 content。当提供商返回推理状态时,该项还会包含 encrypted_content,其中保存以下之一:
  • OpenAI、Azure OpenAI 和 xAI 的加密推理。对于推理模型,Phaseo 会通过 include: ["reasoning.encrypted_content"] 请求它。
  • Claude 思考签名和已编辑的思考。
  • Gemini 思维签名,包括一个单独的 reasoning 项,它紧挨着放在签名所属的函数调用之前。
  • Claude 回复运行时的强度级别,位于输出的最后一个 reasoning 项中,该项没有文本。
流式响应会在 response.output_item.done 和 response.completed 上携带相同的项。
在每个请求中(而不仅是在工具循环中)都要在 input 中原样发回所有输出项。切勿丢弃、编辑或重新排序 reasoning 项,无论是否带有 encrypted_content,也包括没有文本的项。
encrypted_content 是不透明的,并记录了生成它的提供商和模型。Phaseo 只会把它发送给该提供商系列和模型,因此回退到其他提供商时会丢弃它,而不会导致请求失败。缺少它时,Claude 会在工具循环的各步骤之间丢失推理,而更改 reasoning.effort 会重启 Claude 的提示词缓存;参见在对话中途更改推理强度。

授权

Authorization
string
header
必填

Bearer 令牌身份验证

请求体

application/json

以 null 发送的可选顶层字段会被视为未设置,与省略该字段相同。

model
string
必填
input
必填
models
string[]

在 model 之后按顺序尝试的可选回退模型。model 为必填项,且始终是主模型。当某次尝试以 429、500、502、503 或 504 失败时,会尝试下一项;其他错误按原样返回。最多接受 25 个模型 ID 或预设;重复项以及与 model 相同的项会被忽略。每次尝试都会作为独立请求进行验证、记录和计费,响应中的 model 字段和路由追踪会显示实际处理请求的模型。流式请求仅在发送第一个字节之前回退,视频和音乐任务仅在提交时回退。Batch、realtime 和 council 请求会拒绝 models。动态路由上设置的回退优先,且 phaseo/auto 不能与 models 一起使用。

Required array length: 1 - 25 elements
Minimum string length: 1
示例:
prompt
object

填充保存在预设中的提示词模板。可省略 model 或将其设为同一引用,并发送空对话或要追加在模板之后的轮次。

background
boolean
include
string[]
instructions
string
max_output_tokens
integer
必填范围: x >= 1
metadata
object
session_id
string

用于可观测性统计的唯一标识符,可将相关请求(例如对话或代理工作流)归为一组。

Maximum string length: 256
parallel_tool_calls
boolean
previous_response_id
string

不支持。Phaseo 不存储响应,因此设置了 previous_response_id 或 conversation 的请求会返回 400 unsupported_param。请在 input 中发送完整对话。

reasoning
object
service_tier
enum<string> | null

选择受支持的路由或定价等级。auto(或 null)表示不指定特定等级,路由和计费方式与未设置此字段时相同;scale 按标准等级 default 处理。

可用选项:
standard,
default,
fast,
ultrafast,
priority,
flex,
batch,
auto,
scale
store
boolean
stream
boolean
temperature
number
必填范围: 0 <= x <= 2
text
object
plugins
object[]

此请求使用的网关插件。web 为任意模型添加网页搜索,web-fetch 添加网页读取;response-healing 修复非流式结构化响应中格式错误的 JSON。工作区和预设的默认值会与此列表合并。未知的插件 id 返回 400 unknown_gateway_plugin。

向请求添加 phaseo:web_search 服务器工具,让任意模型都能搜索网页。请求的运行方式以及搜索的计数和计费,与使用 phaseo:web_search 工具完全相同。如果请求已包含网页搜索工具,插件不会添加任何内容。其他选项会被忽略。

tool_choice

工具选择策略。接受 Phaseo 服务器工具类型,并将其改写为上游函数或工具目标。allowed_tools 对象会连同所有工具原样发送给 OpenAI。其他提供商只会收到允许的工具及其模式(auto 或 required),当 required 只允许一个工具时,则收到对该工具的强制调用。如果 allowed_tools 列出了 tools 中未定义的工具,则只有 OpenAI 能处理该请求;否则返回 400 错误。

可用选项:
auto,
none,
required,
phaseo:datetime,
phaseo:web_search,
phaseo:web_fetch,
phaseo:subagent,
phaseo:fusion,
phaseo:search_models,
gateway:datetime,
gateway:web_search,
gateway:web_fetch
tools
object[]

用于模型函数调用和网关服务器工具的工具定义。网关内置服务器工具为 gateway:datetime、gateway:web_search 和 gateway:web_fetch。

top_p
number
必填范围: 0 <= x <= 1
truncation
enum<string>
可用选项:
auto,
disabled
user
string
prompt_cache_key
string | null

将相关请求归为一组,使其保留在持有其 prompt 缓存的提供商上。Phaseo 向上游发送的是你的工作区与该键的哈希值,绝不发送原始键。

prompt_cache_retention
enum<string>

适用于 GPT-5.6 之前的 OpenAI 和 Azure OpenAI 模型的 prompt 缓存保留策略。优先于 provider_options.openai.prompt_cache_retention。

可用选项:
in_memory,
24h
prompt_cache_options
object

适用于 GPT-5.6 及以后版本的 OpenAI 和 Azure OpenAI(ttl 30m,OpenAI 上也可为 12h)以及 DeepInfra(ttl 5m 或 1h)的 prompt 缓存模式和 TTL。对其他提供商会被移除。

cache_control
object

prompt 缓存控制。使用 type ephemeral,并可选设置 ttl 为 5m 或 1h。scope 仅适用于顶层 Claude 缓存策略。Amazon Bedrock 和 Google Vertex AI 对 Claude 3.7 Sonnet、3.5 Sonnet 和 3 Opus 只提供 5 分钟缓存;在这些路由上 ttl 会被移除,被移除的 1h 会在 X-Phaseo-Dropped-Params 中报告为 cache_control.ttl。

safety_identifier
string | null
modalities
enum<string>[]
可用选项:
text,
image,
audio
image_config
object
provider_options
object

可选的提供商专用选项。

usage
boolean
meta
boolean
echo_upstream_request
boolean
debug
object

网关调试控制项。这些标志绝不会转发给提供商。

provider
object

用于网关选择的提供商路由偏好设置。

响应

响应

id
string
object
string
created
integer
model
string
provider
string
provider_id
string
nativeResponseId
string | null
status
enum<string>
可用选项:
completed,
failed,
incomplete
finish_reason
string | null
meta
object
cost_nanos
number
cost_cents
integer
currency
string
pricing_lines
object[]
output
object[]
output_items
object[]
content
object[]
role
string
stop_reason
string
type
string
usage
object
最后修改于 2026年11月12日