独立搜索接口 #

/v1/alpha/search 是面向特定 Agent 或编程工具的独立搜索兼容接口。它不是普通聊天接口，也不是所有模型都能调用的通用搜索入口。

接口信息 #

请求体应使用调用方客户端对应的搜索协议。网关会保留未识别的 JSON 字段，并在配置了模型映射时只改写 model 字段，因此不要把它当成普通 /v1/chat/completions 请求来调用。

适用场景 #

• 编程工具或 Agent 将搜索作为独立请求发送。
• 客户端已经实现了该搜索协议，需要把请求地址改为自定义网关。
• 需要把搜索请求和普通对话请求分开计量或路由。

如果你的客户端只是想让模型在 Responses 工作流中使用联网搜索，优先阅读 Responses API 接入，不要手动把普通聊天请求改成 /v1/alpha/search。

最小路由验证 #

下面的请求只用于确认 API Key、路径和模型字段是否能通过网关校验。真正的搜索请求还需要由客户端补充它所需的协议字段，只有 model 的请求可能会被上游拒绝。

export COREROUTER_API_KEY="sk-xxxxxxxxxxxxxxxx"

curl https://api.corerouter.tech/v1/alpha/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $COREROUTER_API_KEY" \
  -d '{
    "model": "search-model-id"
  }'

客户端接入要点 #

1. 把客户端的搜索 Endpoint 改成 https://api.corerouter.tech/v1/alpha/search。
2. 使用控制台中的搜索能力 Model ID。
3. 保留客户端原本生成的请求体字段，不要自行替换成 Chat Completions 的 messages。
4. 先用客户端的调试日志确认最终请求路径、认证 Header 和模型名。
5. 如果客户端同时使用 /v1/responses，需要分别确认 Responses 和独立搜索能力，二者不是同一个开关。

兼容边界 #

• 只有配置了对应搜索能力的渠道和模型才能成功转发；没有匹配能力时通常会返回 400。
• 上游通常不会返回标准 token usage，网关会按一次搜索工具调用进行计量，实际费用以控制台记录为准。
• 该接口不保证支持流式输出；请求中的 stream 字段会保留并转发，但最终行为取决于上游和客户端。
• 搜索结果结构、引用字段和错误格式由上游协议决定，不能按 Chat Completions 的 choices 结构解析。

常见问题 #

返回 channel does not support /v1/alpha/search #

当前路由没有绑定搜索兼容渠道。请更换控制台中明确支持搜索的模型，或联系服务维护者确认该能力是否已配置。

请求被上游拒绝 #

常见原因是请求体缺少客户端协议要求的字段。网关只校验 model，不会替客户端补齐完整的搜索请求结构。请使用客户端原生生成的请求体，并检查最终模型 ID。

为什么没有 token usage #

独立搜索响应可能不包含标准 usage 字段。网关会按一次搜索工具调用计量，排查费用时应以控制台消费记录为准。