> ## 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]
>
> 定價、實測資料與必須知道的幾件事見 [概覽](/zh-Hant/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](/zh-Hant/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.