联网搜索

API 配置

保存后下方「Try It」面板会自动携带此 API Key 发送真实请求。

Base: api.xrtoken.net

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

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

接口字段明细见联网搜索 API。

搜索类型（Type）

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

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

快速开始

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 示例：

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，结构示意）

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

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

计费

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

余额与冻结机制见计费说明。

错误处理

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

本地校验错误示例：

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

限制与说明

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