# 联网搜索

通过一次请求获取与搜索词相关的网页结果，适合 Agent 工具调用、RAG 检索、资料聚合等场景。

- **端点**：`POST /v1/search`
- **鉴权**：`Authorization: Bearer tr-...`（与其它 `/v1` 接口相同）
- **计费**：**按次**计费，成功扣费、失败不扣费；具体价格见 [模型市场](/dashboard/models) 或 `GET /v1/models`

接口字段明细见 [联网搜索 API](/docs/api/createSearch)。

## 搜索类型（Type）

| `Type` | 模型 ID | 说明 |
| --- | --- | --- |
| `web` | `doubao-web-search` | 网页搜索；本期仅 `SearchType=web` |
| `global` | `doubao-global-search` | 全球搜索；请求字段与 `web` 不完全相同 |

调用时用 body 里的 `Type` 选择产品线即可，不必在 path 上分模型。模型列表见 `GET /v1/models`（`model_type: search`）。

## 快速开始

```bash
export XRT_API_KEY="tr-xxxxxxxx"
export XRT_BASE="https://api.xrtoken.net"   # 中国站

# 网页搜索
curl -sS "$XRT_BASE/v1/search" \
  -H "Authorization: Bearer $XRT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Type": "web",
    "Query": "北京周边游玩景点推荐",
    "Count": 5,
    "SearchType": "web"
  }'

# 全球搜索
curl -sS "$XRT_BASE/v1/search" \
  -H "Authorization: Bearer $XRT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Type": "global",
    "Query": "openai research",
    "DocCount": 5,
    "MaxSnippetLength": 500
  }'
```

Python 示例：

```python
import os
import requests

BASE = os.environ.get("XRT_BASE", "https://api.xrtoken.net")
KEY = os.environ["XRT_API_KEY"]

resp = requests.post(
    f"{BASE}/v1/search",
    headers={
        "Authorization": f"Bearer {KEY}",
        "Content-Type": "application/json",
    },
    json={
        "Type": "web",
        "Query": "今日科技新闻",
        "Count": 10,
        "SearchType": "web",
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
for item in (data.get("Result") or {}).get("WebResults") or []:
    print(item.get("Title"), item.get("Url"))
```

## 请求字段

### 网关字段

| 字段 | 必须 | 说明 |
| --- | --- | --- |
| `Type` | 是 | `web` 或 `global` |
| `model` | 否 | 若填写，须与 Type 对应模型一致（`doubao-web-search` / `doubao-global-search`） |

### Type = web

| 字段 | 必须 | 说明 |
| --- | --- | --- |
| `Query` | 是 | 搜索词，1–100 字 |
| `SearchType` | 否 | 默认 `web`；`image` 本期不支持 |
| `Count` | 否 | 返回条数，最多 50，默认 10 |
| `Filter` | 否 | 过滤：`NeedContent` / `NeedUrl` / `Sites` / `BlockHosts` / `AuthInfoLevel` 等 |
| `TimeRange` | 否 | `OneDay` / `OneWeek` / `OneMonth` / `OneYear` 或 `YYYY-MM-DD..YYYY-MM-DD` |
| `QueryControl.QueryRewrite` | 否 | 是否开启 Query 改写（会增加耗时） |
| `ContentFormats` | 否 | 正文格式：`text` / `markdown` |
| `Industry` | 否 | `finance` / `game` / `gov` |

### Type = global

| 字段 | 必须 | 说明 |
| --- | --- | --- |
| `Query` | 是 | 搜索词，1–100 字 |
| `DocCount` | 否 | 返回条数，最多 20，默认 10 |
| `MaxSnippetLength` | 否 | 单条摘要最大 tokens，建议 ≤1000，上限 3000 |
| `MaxImageCountPerDoc` | 否 | 单条结果最多图片数，默认 3，最多 10 |

## 响应

- HTTP 通常为 **200**；body 为 JSON，含 `ResponseMetadata`、`Result`。
- 响应头含 **`X-Request-Id`**（`tr-req-...`），便于排障。
- **web** 成功时看：`Result.WebResults[]`（`Title` / `Url` / `Snippet` / `Summary` / `Content` 等）。
- **global** 成功时看：`Result.Documents[]` 与 `TotalDocCount`。

### 响应示例（web，结构示意）

```json
{
  "ResponseMetadata": {
    "RequestId": "..."
  },
  "Result": {
    "ResultCount": 2,
    "WebResults": [
      {
        "Id": "...",
        "SortId": 1,
        "Title": "标题",
        "SiteName": "站点",
        "Url": "https://...",
        "Snippet": "列表摘要…",
        "Summary": "适合大模型使用的相关摘要…"
      }
    ],
    "TimeCost": 123
  }
}
```

大模型场景优先使用 **`Summary`**（若有），`Snippet` 仅适合列表展示。

## 计费

| 项 | 规则 |
| --- | --- |
| 方式 | 按次计费 |
| 与条数关系 | 单价与 `Count` / `DocCount` 无关 |
| 失败 | 参数错误、余额不足、服务错误等：**不扣费** |
| 价格 | 见 [模型市场](/dashboard/models) 或 `GET /v1/models` |

余额与冻结机制见 [计费说明](/docs/billing)。

## 错误处理

| HTTP | 典型原因 |
| --- | --- |
| 400 | 缺 `Type` / `Query`、`SearchType=image`、`DocCount>20`、`model` 与 `Type` 不一致 |
| 401 | API Key 无效 |
| 402 | 余额不足 |
| 429 | 请求过于频繁 |
| 502 / 503 | 服务暂时不可用 |

本地校验错误示例：

```json
{ "error": "Query is required", "type": "invalid_request_error" }
```

## 限制与说明

- 本期 **仅中国站**上架（`api.xrtoken.net`）；是否可用以 `GET /v1/models` 为准。
- 图片搜索（`SearchType=image`）未开放。
- 同步接口：无需轮询任务状态。
- 请合理控制并发。

## 相关链接

- [API 参考：POST /v1/search](/docs/api/createSearch)
- [认证](/docs/authentication)
- [模型选择](/docs/models)
- [计费说明](/docs/billing)
- [错误码](/docs/errors)