OpenAI Alpha Search

通过独立的 POST /v1/alpha/search 端点调用 Codex 或 Advanced Custom Web Search 路线

OpenAI Alpha Search 是独立的非流式 Web Search 中继端点：

POST /v1/alpha/search

它不复用 /v1/chat/completions 或 /v1/responses 的转换流程。MAX API 会完成 API Key 鉴权、Token 路由、渠道选择、模型映射、Param Override、请求体保留和 Web Search 计费，然后把成功的上游 JSON 响应直接返回给客户端。

该端点需要 v1.0.5-preview.4 或更高版本。Token 的路由计划中必须存在支持 Alpha Search 的渠道，否则即使模型名出现在其他普通 OpenAI 渠道中，请求也不会交给这些不兼容渠道。

支持的渠道

渠道类型	路由行为
Codex	客户端调用 `/v1/alpha/search`，平台转发到 Codex 原生 `/backend-api/codex/alpha/search`
Advanced Custom	必须配置 `incoming_path: /v1/alpha/search`，并使用 `converter: none` 的原生直通路线
普通 OpenAI 或其他渠道	不参与 Alpha Search 渠道选择，即使配置了同名模型也不会被误选

管理员配置方法见渠道管理。如果 API Key 使用手工路线，请确认至少一个手工分组包含支持该模型和端点的 Codex 或 Advanced Custom 渠道。

请求示例

将 gpt-5.1 替换为平台模型列表中实际支持 Alpha Search 的模型。

Bash

export MAX_API_BASE="https://your-platform.example"
export MAX_API_KEY="sk-xxxxxxxxxxxxxxxx"

curl "$MAX_API_BASE/v1/alpha/search" \
  -H "Authorization: Bearer $MAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.1",
    "input": [
      {"role": "user", "content": "Search for the latest artificial intelligence news."}
    ],
    "commands": {
      "search_query": [{"q": "latest artificial intelligence news"}]
    }
  }'

PowerShell

$env:MAX_API_BASE = "https://your-platform.example"
$env:MAX_API_KEY = "sk-xxxxxxxxxxxxxxxx"

$body = @{
  model = "gpt-5.1"
  input = @(
    @{
      role = "user"
      content = "Search for the latest artificial intelligence news."
    }
  )
  commands = @{
    search_query = @(
      @{ q = "latest artificial intelligence news" }
    )
  }
} | ConvertTo-Json -Depth 6

Invoke-RestMethod `
  -Method Post `
  -Uri "$env:MAX_API_BASE/v1/alpha/search" `
  -Headers @{ Authorization = "Bearer $env:MAX_API_KEY" } `
  -ContentType "application/json" `
  -Body $body

请求处理规则

model 为必填字段。平台先按 Token 路由计划选择候选分组，再按请求路径过滤不支持 Alpha Search 的渠道。
模型映射会更新发往上游的 model，渠道 Param Override 随后应用。
除模型映射和明确配置的 Param Override 外，原始 JSON 中的未知字段会继续保留并转发，便于兼容上游以后新增的 Alpha Search 参数。
当前端点按非流式请求处理。成功响应的 HTTP 状态、Content-Type 和 JSON 正文由上游直通返回。
模型详情页的 API 示例区同时提供 Alpha Search 的 cURL、Python、TypeScript 和 JavaScript 示例；JavaScript/TypeScript 示例会先检查 HTTP 状态再解析 JSON。

Alpha Search 的预消费由两部分组成：现有模型估算额度，以及一次 web_search_preview 工具调用附加费。工具价格在 系统设置 -> 计费 -> 模型定价 -> 工具价格 中配置，也可直接访问 /system-settings/billing/model-pricing。价格单位为每 1,000 次调用的美元价格，并会应用当前分组倍率；可使用 web_search_preview:<模型前缀>* 覆盖特定模型。

文档不承诺固定的 Alpha Search 单次价格。上线前应核对模型价格、web_search_preview 工具价格、分组倍率和分层计费表达式。负数、NaN、Infinity 或溢出配置会失败关闭，而不是继续生成不可信账单。

只有上游成功响应后，系统才记录 1 次 Web Search 用量并在响应体写回前完成结算。上游失败请求沿用现有退款路径，退回本次完整预消费；客户端接收响应失败不会把已经成功的上游搜索重新视为未计费请求。

常见问题

现象	检查项
没有可用渠道	检查 API Key 自动/手工路线、分组、模型能力，以及渠道是否为 Codex 或已配置 Alpha Search 路线的 Advanced Custom
Advanced Custom 不参与选择	确认 `incoming_path` 精确为 `/v1/alpha/search`，Converter 为 Native forwarding（`none`），并且上游路径与认证配置有效
返回模型映射错误	检查渠道模型列表、模型映射 JSON 和映射后的上游模型名
返回价格无效或额度不足	检查模型价格、`web_search_preview` 工具价格、分组倍率、Token/用户余额及分层计费配置