> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olostep.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建搜索

> 使用自然语言查询搜索网络，并返回一个去重的相关链接列表，包含标题和描述。  它将在网络上语义搜索查询并返回结果。  可选地，传递 `scrape_options` 以抓取每个返回的 URL，并将 `markdown_content` / `html_content` 直接嵌入到每个链接中。页面抓取会通过底层的 /v1/scrapes 端点自动计费到你的团队。  参见 [搜索功能](/features/search)。

## 创建搜索

使用此端点来创建新的搜索请求。

### 请求

**路径**

`POST /v1/searches`

**请求体**

请求体必须是一个包含以下属性的 JSON 对象：

* `query` (字符串): 要搜索的查询字符串。
* `filters` (对象): 可选的过滤器对象，用于限制搜索结果。
* `sort` (字符串): 可选的排序参数，定义结果的排序方式。

### 响应

成功的响应将返回一个包含搜索结果的 JSON 对象。

### 示例

```json theme={null}
POST /v1/searches HTTP/1.1
Content-Type: application/json

{
  "query": "Olostep",
  "filters": {
    "category": "technology"
  },
  "sort": "relevance"
}
```

### 响应示例

```json theme={null}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "results": [
    {
      "id": "123",
      "title": "Olostep Technology Overview",
      "snippet": "Learn more about Olostep's innovative technology solutions..."
    }
  ],
  "total": 1
}
```

### 错误

如果请求无效，服务器将返回一个错误响应。常见的错误包括：

* `400 Bad Request`: 请求体格式不正确或缺少必需的字段。
* `401 Unauthorized`: 缺少有效的身份验证凭据。
* `500 Internal Server Error`: 服务器遇到意外错误。

确保你的请求符合 API 规范，以避免这些错误。


## OpenAPI

````yaml zh/openapi/search.json POST /v1/searches
openapi: 3.0.3
info:
  title: 搜索 API
  version: 1.1.0
servers:
  - url: https://api.olostep.com
security: []
paths:
  /v1/searches:
    post:
      summary: 创建搜索
      description: >-
        使用自然语言查询搜索网络，并返回一个去重的相关链接列表，包含标题和描述。  它将在网络上语义搜索查询并返回结果。  可选地，传递
        `scrape_options` 以抓取每个返回的 URL，并将 `markdown_content` / `html_content`
        直接嵌入到每个链接中。页面抓取会通过底层的 /v1/scrapes 端点自动计费到你的团队。  参见
        [搜索功能](/features/search)。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: 自然语言的搜索查询。
                  example: What's going on with OpenAI's Sora shutting down?
                limit:
                  type: integer
                  description: 去重后返回的最大链接数量。
                  minimum: 1
                  maximum: 25
                  default: 12
                  example: 10
                include_domains:
                  type: array
                  description: 将结果限制在这些域名内。仅限裸主机——前导的 `http(s)://` 和尾部斜杠会自动去除。
                  items:
                    type: string
                  example:
                    - nytimes.com
                    - wsj.com
                exclude_domains:
                  type: array
                  description: 排除来自这些域名的结果。仅限裸主机——前导的 `http(s)://` 和尾部斜杠会自动去除。
                  items:
                    type: string
                  example:
                    - reddit.com
                fast_mode:
                  type: boolean
                  description: 使用你的查询字面请求直接、低延迟的搜索。默认模式执行更广泛的搜索以覆盖更广的结果。
                  default: false
                scrape_options:
                  $ref: '#/components/schemas/ScrapeOptions'
              required:
                - query
            examples:
              minimal:
                summary: 最小化——仅查询
                value:
                  query: Best Answer Engine Optimization startups
              withScrape:
                summary: 使用 scrape_options + 域名过滤器 + 限制
                value:
                  query: What's going on with OpenAI's Sora shutting down?
                  limit: 10
                  include_domains:
                    - nytimes.com
                    - wsj.com
                  exclude_domains:
                    - pinterest.com
                  scrape_options:
                    formats:
                      - markdown
                    remove_css_selectors: default
                    timeout: 25
      responses:
        '200':
          description: 成功响应并返回搜索结果。
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: search_9bi0sbj9xa
                  object:
                    type: string
                    example: search
                  created:
                    type: integer
                    example: 1760327323
                  metadata:
                    type: object
                  query:
                    type: string
                    example: Best Answer Engine Optimization startups
                  credits_consumed:
                    type: integer
                    description: 此请求消耗的总积分：5 个基础搜索积分 + 使用 scrape_options 时每页抓取积分的总和。
                    example: 10
                  result:
                    type: object
                    properties:
                      json_content:
                        type: string
                        description: 完整搜索结果的字符串化 JSON。
                      json_hosted_url:
                        type: string
                        description: 在 S3 上托管的 JSON 文件的 URL。
                        nullable: true
                      links:
                        type: array
                        description: >-
                          在多次搜索中找到的相关链接的去重列表。当提供 scrape_options 时，每个链接可能包含
                          `markdown_content` 和/或 `html_content`。
                        items:
                          $ref: '#/components/schemas/SearchLink'
                      size_exceeded:
                        type: boolean
                        description: >-
                          当每个链接的内联内容超过 9MB 安全上限时为真。当为真时，响应中的内容字段为空——使用
                          json_hosted_url 获取完整的负载。
                      credits_consumed:
                        type: integer
                        description: 与顶级 credits_consumed 相同的值。
        '400':
          description: >-
            错误请求——验证失败（缺少查询、无效的限制、不支持的 scrape_options.formats 值等）。响应体为 `{
            "message": "<reason>" }`。
        '401':
          description: 无效的 API 密钥
        '500':
          description: 内部服务器错误
      security:
        - Authorization: []
components:
  schemas:
    ScrapeOptions:
      type: object
      description: 可选。当提供时，每个返回的链接也会被抓取，其内容嵌入到响应中。每页抓取的费用会通过底层的 /v1/scrapes 端点自动计费。
      properties:
        formats:
          type: array
          description: >-
            请求每个抓取页面的输出格式。如果省略，默认为 ['markdown']。目前在 /v1/searches 上仅支持 'html' 和
            'markdown'。
          items:
            type: string
            enum:
              - html
              - markdown
          default:
            - markdown
          example:
            - markdown
        remove_css_selectors:
          type: string
          description: >-
            选择从内容中移除某些 CSS 选择器。转发到 /v1/scrapes。默认值为 'default'，会移除
            ['nav','footer','script','style','noscript','svg',[role=alert],[role=banner],[role=dialog],[role=alertdialog],[role=region][aria-label*=skip
            i],[aria-modal=true]]。传递 'none' 以禁用，或传递一个 JSON 字符串化的选择器数组以移除。
          default: default
        timeout:
          type: integer
          description: 整个抓取阶段的挂钟预算（以秒为单位）。在此时间过后，搜索将返回可用的链接——对于尚未完成抓取的链接，内容字段将为 null。
          minimum: 1
          maximum: 60
          default: 25
    SearchLink:
      type: object
      properties:
        url:
          type: string
          description: 结果的 URL。
        title:
          type: string
          nullable: true
          description: 结果页面的标题。
        description:
          type: string
          nullable: true
          description: 结果的简短片段或描述。
        markdown_content:
          type: string
          nullable: true
          description: >-
            页面的 Markdown 内容。仅当 scrape_options.formats 包含 'markdown'
            时存在。如果抓取失败、为空或达到全局超时，则为 null。对于 Reddit 评论 URL，这是由
            @olostep/reddit-post 解析器的结构化 JSON 生成的，以提高质量。
        html_content:
          type: string
          nullable: true
          description: >-
            页面的 HTML 内容。仅当 scrape_options.formats 包含 'html'
            时存在。如果抓取失败、为空或达到全局超时，则为 null。
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      description: Bearer认证头格式为Bearer <token>，其中<token>是你的认证令牌。

````