# 面向 AI 的实时网络搜索。

**API:** Data API

**Endpoint:** `POST /v1/beta/byteplus/web-search`

**Tags:** BytePlus

运行专为 AI 智能体构建的实时网络搜索，返回带标题、链接和摘要的排序结果列表。`Query` 为必填项；可用 `Count`（≤ 20）、`Filter`（限定 `Sites` 或排除 `BlockHosts`）、`Language` 和 `TimeRange` 收窄结果集。响应封装了 `ResponseMetadata.RequestId` 和网络结果列表 `Result`。适用于 RAG 检索增强、竞品/公关监测、事实核查和内容取材；将每个结果 URL 与 `post_byteplus_fetch` 配合，即可拉取完整页面内容。

### 计费参考

- 计量方式：按成功请求的固定成本计费。
- 参考请求估算：0.0048 美元。
- 参考客户倍率：1.0。不得对已结算的客户金额再次应用。

仅供参考的元数据，不是账户报价、保证价格或消费上限。资源额度不同于 Felo 额度。最终扣费以 Felo 计费记录为准。

## Base URL

- `https://openapi.felo.ai`

## Authentication

- `FeloBearerAuth` (http bearer, bearer format Felo API Key)
- `FeloApiKey` (apiKey in header `X-API-Key`)

## Request body

Required: **yes**

### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "Query": {
      "type": "string",
      "description": "搜索查询。必填。最多 400 个字符；上游引擎实际上还会限制在约 50 个词。",
      "example": "OpenAI news",
      "maxLength": 400
    },
    "Count": {
      "type": "integer",
      "description": "要返回的结果数量。可选；默认 10，最大 20。",
      "maximum": 20,
      "example": 10,
      "default": 10
    },
    "Filter": {
      "type": "object",
      "description": "可选的结果筛选。两个字段都是以竖线分隔的完整域名字符串（各最多 5 个）。",
      "properties": {
        "Sites": {
          "type": "string",
          "description": "将结果限定为这些完整域名。以竖线分隔，最多 5 个，例如“bytedance.com|byteplus.com”。（发送数组会返回 10400 Invalid Parameter。）",
          "example": "bytedance.com|byteplus.com"
        },
        "BlockHosts": {
          "type": "string",
          "description": "排除来自这些完整域名的结果。以竖线分隔，最多 5 个，例如“reddit.com|quora.com”。",
          "example": "reddit.com|quora.com"
        }
      }
    },
    "Language": {
      "type": "string",
      "description": "可选的语言提示，采用上游格式，例如 EN、ZH-HANS、ZH-HANT。",
      "example": "EN"
    },
    "TimeRange": {
      "description": "可选的时间窗口。可取命名窗口 OneDay / OneWeek / OneMonth / OneYear 之一，或自定义范围“YYYY-MM-DD..YYYY-MM-DD”。省略则不做时间筛选。注意：像“week”/“month”这样的值会被上游静默忽略。",
      "oneOf": [
        {
          "type": "string",
          "enum": [
            "OneDay",
            "OneWeek",
            "OneMonth",
            "OneYear"
          ]
        },
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}\\.\\.\\d{4}-\\d{2}-\\d{2}$",
          "description": "自定义范围，例如 2026-08-01..2026-09-01。"
        }
      ],
      "example": "OneWeek"
    }
  },
  "required": [
    "Query"
  ]
}
```

Example:

```json
{
  "Query": "OpenAI news"
}
```

## Responses

### 200 — 搜索成功完成。`Result` 包含排序后的网络结果。

Headers:
- `X-Request-Id` (string) — 联系 Felo 支持时需提供的请求标识符。

**application/json**

Schema: object

```json
{
  "type": "object",
  "properties": {
    "ResponseMetadata": {
      "type": "object",
      "description": "上游请求元数据。",
      "properties": {
        "RequestId": {
          "type": "string",
          "description": "此请求的唯一标识符。"
        },
        "Action": {
          "type": "string"
        },
        "Version": {
          "type": "string"
        },
        "Service": {
          "type": "string"
        },
        "Region": {
          "type": "string"
        }
      }
    },
    "Result": {
      "type": "object",
      "description": "搜索结果负载。",
      "properties": {
        "ResultCount": {
          "type": "integer",
          "description": "返回的网络结果数量。"
        },
        "WebResults": {
          "type": "array",
          "description": "排序后的网络结果列表。",
          "items": {
            "type": "object",
            "properties": {
              "Id": {
                "type": "string",
                "description": "不透明的结果 id。"
              },
              "SortId": {
                "type": "integer",
                "description": "结果的排名（从 1 开始）。"
              },
              "Title": {
                "type": "string",
                "description": "结果标题。"
              },
              "SiteName": {
                "type": "string",
                "description": "来源站点名称（可能为空）。"
              },
              "Url": {
                "type": "string",
                "description": "结果 URL。"
              },
              "Snippet": {
                "type": "string",
                "description": "来自页面的简短文本片段。"
              },
              "Summary": {
                "type": "string",
                "description": "页面内容的较长摘要。"
              },
              "PublishTime": {
                "type": "string",
                "description": "ISO 8601 格式的发布时间（可能为空）。"
              },
              "PublishTimeUnix": {
                "type": "integer",
                "description": "发布时间，Unix 秒（未知时为 0）。"
              },
              "LogoUrl": {
                "type": "string",
                "description": "带签名的站点 Logo URL（有时效）。"
              }
            }
          }
        },
        "SearchContext": {
          "type": "object",
          "description": "已解析查询上下文的回显。",
          "properties": {
            "OriginQuery": {
              "type": "string"
            },
            "SearchType": {
              "type": "string"
            }
          }
        },
        "TimeCost": {
          "type": "integer",
          "description": "上游处理时间，单位毫秒。"
        },
        "LogId": {
          "type": "string",
          "description": "上游日志 id（等于 ResponseMetadata.RequestId）。"
        },
        "Choices": {
          "type": [
            "array",
            "null"
          ],
          "description": "保留字段；不适用时为 null。",
          "items": {
            "type": "object"
          }
        },
        "Usage": {
          "type": [
            "object",
            "null"
          ],
          "description": "保留字段；不适用时为 null。"
        }
      }
    }
  }
}
```

Example:

```json
{
  "ResponseMetadata": {
    "RequestId": "20260904155503A787EC832774768DC56F",
    "Action": "",
    "Version": "",
    "Service": "",
    "Region": ""
  },
  "Result": {
    "ResultCount": 3,
    "WebResults": [
      {
        "Id": "19b903d59c017bbb04c7832574500d49",
        "SortId": 1,
        "Title": "OpenAI News | OpenAI",
        "SiteName": "OpenAI",
        "Url": "https://openai.com/news/",
        "Snippet": "Stay up to speed on the rapid advancement of AI technology and the benefits it offers to humanity.",
        "Summary": "Stay up to speed on the rapid advancement of AI technology and the benefits it offers to humanity.",
        "PublishTime": "2026-09-03T07:50:20+08:00",
        "PublishTimeUnix": 1788393020,
        "LogoUrl": "https://p16-bpsearch-sign.ibyteimg.com/...<signed>"
      }
    ],
    "SearchContext": {
      "OriginQuery": "OpenAI latest news",
      "SearchType": "web"
    },
    "TimeCost": 935,
    "LogId": "20260904155503A787EC832774768DC56F",
    "Choices": null,
    "Usage": null
  }
}
```

### 400 — 无法处理该请求。请检查请求参数。

### 401 — 需要有效的 Felo API 密钥。

### 402 — 由于未满足计费要求，请求无法继续。

### 403 — 该账户无权执行此操作。

### 429 — 已达到请求或支出限额。

### 502 — 服务无法完成该请求。

### 503 — API 或计费服务暂时不可用。

### 504 — 服务在处理请求时超时。

### default — 错误响应；上游透传响应可能采用提供方格式

**application/json**

Schema:

```json
{}
```