# Web Search

Grok 联网搜索有两条入口：**推荐主路径**是 `/v1/responses` + `tools:[{"type":"web_search"}]`，可以让模型边搜索边推理并返回带引用答案；本页的独立 `/v1/web_search` 是 Clomio 的**简化兼容入口**，只返回统一来源列表，且 **仅 Grok 分组**支持。

```text
POST https://api.clomio.ai/v1/web_search
```

> 用其他分组调用会返回 404 `Web Search API is not supported for this platform`。Grok 分组的创建见 [创建 API 密钥](#/api-key)。新接入统一使用 `/v1/web_search`。如果你的客户端支持 Responses tools，优先使用 `/v1/responses` + `web_search`；独立 `/v1/web_search` 适合“只要 sources 列表”的程序化场景。

---

## 它和 Grok Responses web_search tool 的关系

| 用法 | 请求形态 | 返回形态 | 适合场景 |
|------|----------|----------|----------|
| 本页 `/v1/web_search` | `{ "query": "...", "max_results": 5 }` | 统一 JSON：`query/results/provider/max_results` | 程序只想拿搜索结果列表，再自行总结/入库；不是官方 tool 参数透传 |
| Grok `/v1/responses` + `tools:[{"type":"web_search"}]` | OpenAI Responses 兼容请求 | Grok 模型回答 + citations/tool usage | 需要模型边搜索边推理并给最终答案 |
| xAI 官方 Web Search tool | `web_search` server-side tool | xAI API 自动执行工具并返回引用 | 与官方 SDK/Responses API 对齐 |
| xAI 官方 X Search tool | `x_search` server-side tool | 搜索 X/Twitter 内容 | 查 X 帖子、用户、thread，而不是普通网页 |

`/v1/web_search` 会返回统一的 `query/results/provider/max_results` 结构；如果它返回 `scheduling_error` 或 `web_search_error`，先用同一个 Grok Key 测 `/v1/responses` + `web_search` tool，以区分主搜索能力和简化入口问题。

xAI 官方说明 Web Search 是 Grok 的实时网页搜索/浏览工具，OpenAI Responses API 兼容工具名为 `web_search`；X Search 的工具名是 `x_search`，面向 X 平台内容。参考：<https://docs.x.ai/developers/tools/web-search>、<https://docs.x.ai/developers/tools/x-search>、<https://docs.x.ai/developers/tools/overview>。

---

## 请求头

| 请求头 | 必填 | 值 |
|--------|:----:|-----|
| `Authorization` | 是 | `Bearer 你的Grok密钥` |
| `Content-Type` | 是 | `application/json` |

---

## 请求参数

| 参数 | 类型 | 必填 | 网关处理 / 说明 |
|------|------|:----:|------|
| `query` | string | 是 | 搜索关键词 / 问题；请传 trim 后非空查询。不支持把官方 tool 的 filters 参数放在本端点顶层 |
| `max_results` | integer | 否 | `<=0` 默认 5，最大 20；用于限制统一结果列表 |

### 不支持直接透传的官方 tool 参数

xAI 官方 `web_search` tool 支持 `filters.allowed_domains`、`filters.excluded_domains`、`enable_image_understanding`、`enable_image_search` 等参数；这些属于 **Responses tool** 参数。本页 `/v1/web_search` 的简化接口当前只接收 `query` 和 `max_results`，不会把 allowed/excluded domains 或图片搜索开关透传。X/Twitter 搜索必须走 `/v1/responses` + `tools:[{"type":"x_search"}]`,不是 `/v1/web_search`。需要这些高级能力时，请直接调用 [Responses](#/api-responses)：

```json
{
  "model": "grok-4.3",
  "input": [{ "role": "user", "content": "What is xAI?" }],
  "tools": [{
    "type": "web_search",
    "filters": { "allowed_domains": ["x.ai"] },
    "enable_image_search": true
  }]
}
```

反例：不要把 `allowed_domains`、`excluded_domains`、`enable_image_search`、`enable_image_understanding` 直接放到 `/v1/web_search` 顶层；当前独立端点只读取 `query` 与 `max_results`。这些字段必须放在 `/v1/responses` 请求的 `tools[].` 里才可能由 Grok/xAI 上游识别。

---

## 响应

```json
{
  "query": "What is xAI?",
  "results": [
    { "url": "https://x.ai/", "title": "xAI", "snippet": "" }
  ],
  "provider": "grok-native",
  "max_results": 5
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `query` | string | 原始查询 |
| `results` | array | 统一来源列表 |
| `results[].url` | string | 来源 URL |
| `results[].title` | string | 来源标题；上游缺失时可能为空 |
| `results[].snippet` | string | 摘要；Grok native sources 常只有 URL/title，可能为空 |
| `provider` | string | `grok-native` 或 Grok 服务标识 |
| `max_results` | integer | 本次请求的回显参数;不代表上游实际搜索条数 |

> 该端点只返回来源列表，不返回 Grok 的自然语言总结；要直接得到带引用的答案，请用 `/v1/responses` + `web_search` tool。成功调用会按一次 Grok web search 记录用量,不是按返回结果条数计费。

---

## 最小可验证 curl

优先先测 Responses tool；这能验证 Grok Key、模型、Responses 路由和上游 web_search 工具是否可用。独立 `/v1/web_search` 再用于验证 sources-list 兼容入口。

## 推荐: Responses + web_search tool

```bash
curl https://api.clomio.ai/v1/responses \
  -H "Authorization: Bearer 你的Grok密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.3",
    "input": "检索 xAI API 文档里 Web Search 的参数并总结",
    "tools": [{"type":"web_search"}],
    "stream": false
  }'
```

如果这里能返回答案和 citations/annotations，而 `/v1/web_search` 报错，说明 Grok 搜索主链路可用，问题集中在独立 sources-list 入口或当前请求参数。

## 示例: 独立 sources-list 搜索

```bash
curl https://api.clomio.ai/v1/web_search \
  -H "Authorization: Bearer 你的Grok密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "2026 年最新的 AI 编程工具",
    "max_results": 5
  }'
```

```python
import requests

r = requests.post(
    "https://api.clomio.ai/v1/web_search",
    headers={"Authorization": "Bearer 你的Grok密钥", "Content-Type": "application/json"},
    json={"query": "2026 年最新的 AI 编程工具", "max_results": 5},
)
r.raise_for_status()
for item in r.json().get("results", []):
    print(item.get("title", ""), "-", item["url"])
```

```javascript
const r = await fetch("https://api.clomio.ai/v1/web_search", {
  method: "POST",
  headers: {
    "Authorization": "Bearer 你的Grok密钥",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "2026 年最新的 AI 编程工具", max_results: 5 }),
});
if (!r.ok) throw new Error(await r.text());
const data = await r.json();
for (const item of data.results ?? []) console.log(item.title ?? "", "-", item.url);
```

---

## 示例: 直接让 Grok 搜索并总结

如果你不需要中间 `results` 列表，而是要最终答案和引用，用 Responses tool：

```bash
curl https://api.clomio.ai/v1/responses \
  -H "Authorization: Bearer 你的Grok密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.3",
    "input": [{"role":"user","content":"What is xAI? Please cite sources."}],
    "tools": [{"type":"web_search"}],
    "stream": false
  }'
```

xAI 官方工具会在服务端自动执行；流式模式下可以观察工具调用，最终响应通常带 citations/annotations。工具调用按 xAI 规则计费。

---

## 实战场景: 搜索 + 自己总结/入库

```python
import requests

KEY = "你的Grok密钥"
WEB_SEARCH_URL = "https://api.clomio.ai/v1/web_search"
H = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

q = "Claude Code 和 Codex 有什么区别"
hits = requests.post(
    WEB_SEARCH_URL,
    headers=H,
    json={"query": q, "max_results": 5},
).json()["results"]

context = "\n".join(f"- {h.get('title','')}: {h.get('snippet','')} ({h['url']})" for h in hits)
ans = requests.post(f"{BASE}/responses", headers=H, json={
    "model": "grok-4.3",
    "input": f"根据以下搜索结果回答:{q}\n\n{context}\n\n请给出结论并标注来源链接。",
}).json()
print(ans.get("output_text", ans))
```

---

## 排障

| 现象 | 常见原因 | 处理 |
|------|----------|------|
| 404 `Web Search API is not supported for this platform` | API Key 不在 Grok 分组 | 换 Grok 分组 Key |
| 400 JSON binding 错误 / `query` 缺失 | 请求体不是合法 JSON，或未传 `query`；错误文本来自 Gin binding（如 `Key: ... Error:Field validation for ... failed on the 'required' tag`） | 设置 `Content-Type: application/json`，传入 `query` |
| 400 `web search is only supported for grok groups` | 当前 Key 分组不是 Grok | 检查 Key 绑定分组和平台 |
| 400 `group required` | API Key 没有关联分组 | 在控制台给 Key 绑定 Grok 分组 |
| 503 `scheduling_error` | 独立端点暂时没有可用服务能力，或搜索服务繁忙 | 先用同 Key 测 `/v1/responses` + `web_search`；若主链路可用但独立端点持续失败，带 `x-request-id`、时间和错误体提交工单 |
| 502 `web_search_error` | 搜索服务暂时失败 | 同 Key 先测 `/v1/responses` + `web_search`；若可用，带 `x-request-id`、时间和错误体反馈 |
| `results` 为空但请求成功 | Grok 没有在响应中暴露 sources/annotations，或该问题无需搜索 | 改用 `/v1/responses` 让模型直接回答并查看 citations/annotations |
| 想限制域名或开启图片搜索 | `/v1/web_search` 不透传这些参数 | 直接用 `/v1/responses` + `tools[].filters` / `enable_image_search` |

---

> Grok 分组的对话走 [Responses](#/api-responses)；图像见 [Images](#/api-images)。Videos 仍是 Grok-only 相邻能力，见 [Videos](#/api-videos)。

## 字段约束速查

| 字段 | 可选值/范围 | 说明 |
|---|---|---|
| `query` | 非空 string | 必填；建议限制在明确问题 |
| `max_results` | `1..20` | 不传默认 `5`，超过 20 会归一化为 20 |

独立 `/v1/web_search` 只返回 `results` 列表；域名过滤、X Search、图片搜索和工具参数请改用 `/v1/responses` 的官方 tool 形态。

## 完整响应与错误

```json
{
  "query":"最新的 Go 版本",
  "provider":"grok-native",
  "max_results":5,
  "results":[{"url":"https://go.dev/","title":"The Go Programming Language","snippet":"..."}]
}
```

| HTTP | 典型错误 | 处理 |
|---:|---|---|
| 400 | `query` 缺失、JSON binding 错误 | 使用 JSON body 和非空 query |
| 401 | `API key required` / Key 无效 | 检查 Grok Key |
| 404 | `Web Search API is not supported for this platform` | 换 Grok 分组 |
| 429 | 请求频率过高 | 降低调用频率 |
| 502 | `web_search_error` | 改测 Responses + web_search 区分上游与兼容层 |
| 503 | `scheduling_error` | 暂无可用 Grok 搜索账号，稍后重试 |