OpenAI Alpha Search

OpenAI Alpha Search is a standalone, non-streaming web-search relay endpoint:

POST /v1/alpha/search

It does not reuse the conversion flow for /v1/chat/completions or /v1/responses. MAX API performs API Key authentication, token routing, channel selection, model mapping, Param Override, request-body preservation, and Web Search billing, then returns the successful upstream JSON response directly to the client.

Supported Channels

See Channel Management for administrator setup. If the API Key uses manual routing, at least one manual group must contain a Codex or Advanced Custom channel that supports both the model and this endpoint.

Request Examples

Replace gpt-5.1 with a model that actually supports Alpha Search on your platform.

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

Request Processing

• model is required. The platform first builds the token route plan, then filters candidate channels by the Alpha Search request path.
• Model mapping updates the upstream model, and channel Param Override is applied afterward.
• Except for model mapping and explicitly configured Param Override operations, unknown fields in the original JSON body are preserved and forwarded for compatibility with future upstream Alpha Search parameters.
• The endpoint currently operates as non-streaming. On success, the upstream HTTP status, Content-Type, and JSON body are passed through.
• The model-details API panel also provides cURL, Python, TypeScript, and JavaScript Alpha Search samples. The JavaScript and TypeScript samples check HTTP status before parsing JSON.

Web Search Billing

Alpha Search pre-consumption has two parts: the existing model estimate and one web_search_preview tool-call surcharge. Configure tool prices under System Settings -> Billing -> Model Pricing -> Tool prices, or open /system-settings/billing/model-pricing. Prices are expressed in USD per 1,000 calls and are multiplied by the active group ratio. A key such as web_search_preview:<model-prefix>* can override the default for matching models.

The system records one Web Search call only after the upstream returns success, and settlement completes before the response body is copied to the client. Upstream failures follow the existing refund path and return the complete reservation for this request. A client-side response-write failure does not turn an already successful upstream search into an unbilled request.

Troubleshooting