跳转到主要内容
POST
创建消息
将 Anthropic Messages API 请求体发送到 /v1/messages,即可为 Phaseo 路由的任何模型获得 Anthropic 格式的响应。支持 Anthropic 的工具调用字段,X-Phaseo-Strictness 标头控制如何处理不支持的参数。 设置 stream: true 可接收 Anthropic 格式的服务器发送事件(message_start、content_block_*、message_delta、message_stop)。流式传输在工具循环中同样可用。

对话中途的系统消息

在 messages 中添加一条 role: "system" 消息,作为从对话中该位置开始生效的指令。顶层 system 字段保持不变,因此缓存的前缀仍能命中。
系统消息可以是字符串或文本块。它必须紧跟在用户轮次之后(或紧跟在以服务器工具结果结尾的助手轮次之后),并且必须是最后一条消息,或者后面紧跟一个助手轮次。放在其他位置会返回 400。不支持 clear_at、output_config 以及 tool_addition 或 tool_removal 块。

使用服务器工具

在 tools 中添加一个 phaseo: 工具,模型调用它时由 Phaseo 运行:Phaseo 会在上游将其改写为 Anthropic 的工具格式,并在服务器端继续工具循环。/v1/messages 接受除 phaseo:apply_patch 以外的所有服务器工具;服务器工具指南列出了这些工具。
服务器工具调用会计入 usage.server_tool_use。旧的 gateway:datetime 类型仍然可用。设置 stream: true 时,Phaseo 会自行运行工具轮次,然后将后续回答作为单个流发送给你。

使用 Anthropic 原生网页搜索

当路由到的 Anthropic 模型和提供商支持原生网页搜索时,可直接传入 Anthropic 的工具定义,例如 type: "web_search_20250305"。执行前,提供商路由仍会筛选支持 web_search_options 的提供商。

授权

Authorization
string
header
必填

Bearer 令牌身份验证

请求体

application/json

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

model
string
必填
messages
object[]
必填
Minimum array length: 1
max_tokens
integer
必填
必填范围: x >= 1
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 或将其设为同一引用,并发送空对话或要追加在模板之后的轮次。

system
service_tier
enum<string>

在兼容的文本 API 上选择受支持的路由或定价等级。

可用选项:
standard,
default,
fast,
ultrafast,
priority,
flex,
batch,
auto,
standard_only
temperature
number
必填范围: 0 <= x <= 1
top_p
number
必填范围: 0 <= x <= 1
top_k
integer
必填范围: x >= 1
tools
object[]

兼容 Anthropic 的工具,以及由网关管理的服务器工具。

tool_choice

Anthropic 工具选择对象或字符串。也接受由网关管理的服务器工具名称,并由网关进行改写。

plugins
object[]

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

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

stream
boolean
metadata
object
session_id
string

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

Maximum string length: 256
reasoning
object
context_management
object

Anthropic 上下文编辑。edits 接受 clear_tool_uses_* 和 clear_thinking_* 策略,并附带相应的 beta 请求头发送给 Anthropic。其他提供商会在不含此字段的情况下运行请求,并在 X-Phaseo-Dropped-Params 中列出 context_management。压缩编辑(compact_*)返回 400。

user
string

最终用户标识符,与 Chat Completions 中相同。除非已设置 metadata.user_id,否则 Claude 模型会以 metadata.user_id 的形式接收它。

prompt_cache_key
string | null

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

stop_sequences
string[]
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。

provider_options
object

可选的提供商专用选项。

usage
boolean
meta
boolean
echo_upstream_request
boolean
debug
object

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

provider
object

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

响应

消息响应

id
string
type
string
role
enum<string>
可用选项:
assistant
model
string
content
object[]
stop_reason
string
stop_sequence
string
usage
object
context_management
object

当请求使用了 context_management 且 Anthropic 应用了编辑时出现。applied_edits 列出每项编辑及其清除的内容。流式响应中,它位于最后的 message_delta 事件里。

最后修改于 2026年11月5日