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

# DeepSeek 网页搜索 API 参考

> DeepSeek Search API 参考与在线调试：/v1/tools/search 端点参数说明、搜索语法、响应结构与错误码对照。

> [!NOTE]
>
> 右侧 Playground 可直接调试：在 **Authorization** 填 `Bearer sk-your-api-key`（`default` 或 `svip` 分组的令牌），
> 默认示例已填好，点击发送即可看到搜索结果。每次成功调用扣费一次。
> `localization` 要填**用户的 IP 地址**（如 `8.8.8.8`），填 `zh-CN` 这类语言代码会返回 400。

> [!TIP]
>
> 定价、实测数据与必须知道的几件事见 [概览](/api-capabilities/deepseek-search-fetch/overview)。

## 参数说明速查

| 参数 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `query` | string | ✓ | 1–128 个字符，不能全是空白。支持 `site:`、`-site:`、`"..."`、`lang:`、`after:`、`before:` 等语法 |
| `count` | int | | 1–50，默认 10。不影响价格 |
| `need_content` | bool | | 默认 `false`；`true` 时每条结果附带网页正文 |
| `ori_question` | string | | 用户原始问题，1–128 个字符 |
| `localization` | string | | **用户 IP 地址**（不是语言代码），用于本地化排序 |

请求体不需要 `model` 字段；未识别的字段会被忽略。

## 响应要点

```json theme={null}
{
  "results": [
    {
      "title": "...",
      "url": "https://...",
      "snippet": "约 100–200 字的短摘要",
      "summary": "约 600–800 字的长摘要",
      "content": "",
      "rerank_score": 2.1,
      "authority": 3,
      "date": "2026-10-20T08:00:00Z",
      "site_name": "...",
      "site_icon": "https://..."
    }
  ]
}
```

* 给模型用 `summary`，给人看用 `snippet`；全文要么开 `need_content`，要么挑几条用 [Fetch](/api-capabilities/deepseek-search-fetch/fetch-api) 抓
* `rerank_score` ≥ 1.5、`authority` ≥ 3 可视为高质量结果，适合做过滤阈值
* `count=50` 时响应体约 180KB，开 `need_content` 会再大一倍以上，注意客户端超时设置

## 错误码对照

| HTTP | 错误信息示例 | 原因与处理 | 扣费 |
| - | - | - | - |
| 400 | `'count' must be between 1 and 50` | `count` 超范围 | 否 |
| 400 | `'query' must not be empty` / `missing field 'query'` | 缺 `query` 或为空 | 否 |
| 400 | `'localization' must be a valid IP address` | `localization` 传了语言代码，改传 IP 或去掉 | 否 |
| 401 | `Invalid token.` | API Key 无效或未带 `Authorization` 头 | 否 |
| 429 | — | 超出上游限流（100 QPS），等待后重试 | 否 |
| 503 | `no available channels for model deepseek-search` | 令牌所在分组没有开通本接口（如 ClaudeCode 分组），换 `default` / `svip` 令牌 | 否 |
| 5xx / 504 | — | 上游内部错误或超时，稍后重试 | 否 |

错误体的 `type` 统一为 `shell_api_error`，请以 HTTP 状态码判断错误种类。


## OpenAPI

````yaml api-reference/deepseek-search-openapi.yaml POST /v1/tools/search
openapi: 3.1.0
info:
  title: DeepSeek 网页搜索 API
  description: |
    `deepseek-search` —— DeepSeek 原生网页搜索接口，按关键词返回结构化搜索结果，给 Agent 与 RAG 联网取数。

    - 不是对话模型，不消耗 token，**按成功请求次数计费**；`count`、`need_content` 不影响价格
    - 400 等参数错误不扣费
    - 上游限流 100 QPS
    - `default` / `svip` 分组可用，ClaudeCode 分组令牌不可用

    **认证方式**：请求头 `Authorization: Bearer YOUR_API_KEY`

    **获取 API Key**：访问 API易控制台 `api.apiyi.com/token` 创建令牌
  version: 1.0.0
servers:
  - url: https://api.apiyi.com
    description: 主要端点
security:
  - bearerAuth: []
paths:
  /v1/tools/search:
    post:
      tags:
        - 搜索与抓取
      summary: 网页搜索：deepseek-search
      description: >
        传入关键词，返回 1–50 条网页搜索结果。请求体不需要 `model` 字段。


        `query` 支持搜索语法：`site:`（多个用 `OR`
        连接）、`-site:`、`"..."`、`-"..."`、`-关键词`、`lang:zh,en`、`after:`、`before:`。
      operationId: deepseekToolsSearch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            example:
              query: DeepSeek V4 发布
              count: 5
      responses:
        '200':
          description: 搜索成功（计费一次）
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
              example:
                results:
                  - title: DeepSeek V4 正式发布
                    url: https://example.com/news/deepseek-v4
                    snippet: 约 100–200 字的短摘要……
                    summary: 约 600–800 字的长摘要……
                    content: ''
                    rerank_score: 2.1
                    authority: 3
                    date: '2026-10-20T08:00:00Z'
                    site_name: Example News
                    site_icon: https://example.com/favicon.ico
        '400':
          description: 参数错误，不扣费：`count` 超出 1–50、`query` 为空或缺失、`localization` 不是 IP 地址等
        '401':
          description: API Key 无效
        '429':
          description: 超出上游限流（100 QPS），等待后重试
        '503':
          description: 令牌所在分组没有开通本接口（如 ClaudeCode 分组），请换 default / svip 分组令牌
      security:
        - bearerAuth: []
components:
  schemas:
    SearchRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: '搜索词，1–128 个字符，不能全是空白。支持 site: / lang: / after: 等搜索语法'
          example: DeepSeek V4 发布
        count:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
          description: 返回条数，1–50。不影响价格
          example: 5
        need_content:
          type: boolean
          default: false
          description: 是否返回网页正文。为 false 时 content 恒为空字符串
        ori_question:
          type: string
          description: 触发这次搜索的用户原始问题，1–128 个字符
        localization:
          type: string
          description: 用户的 IP 地址，用于优先返回本地化结果。**不是语言代码**，传 ja-JP 会返回 400
          example: 8.8.8.8
    SearchResponse:
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
              url:
                type: string
              snippet:
                type: string
                description: 短摘要，约 100–200 字，适合展示
              summary:
                type: string
                description: 长摘要，约 600–800 字，适合喂给模型
              content:
                type: string
                description: 网页正文；need_content 为 false 时为空字符串
              rerank_score:
                type: number
                description: 相关性分数 0–3，≥ 1.5 为高质量
              authority:
                type: integer
                description: 站点权威度 0–4，-1 为未知，≥ 3 为高权威
              date:
                type:
                  - string
                  - 'null'
                description: 发布时间，UTC RFC 3339
              site_name:
                type:
                  - string
                  - 'null'
              site_icon:
                type:
                  - string
                  - 'null'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: '在请求头中添加 Authorization: Bearer YOUR_API_KEY'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.