> ## 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 Fetch API 参考与在线调试：/v1/tools/fetch 端点把任意网页抓成 Markdown 正文，含参数、响应结构与错误码对照。

> [!NOTE]
>
> 右侧 Playground 可直接调试：在 **Authorization** 填 `Bearer sk-your-api-key`（`default` 或 `svip` 分组的令牌），
> 填入任意网址后发送即可。只有成功抓到正文才扣费。

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

## 参数说明速查

| 参数 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `url` | string | ✓ | HTTP / HTTPS 网址，必须带域名，最长 8192 个字符，不能带用户名密码 |

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

## 响应要点

```json theme={null}
{
  "title": "网页搜索与抓取",
  "content": "# 网页搜索与抓取\n\n正文已转成 Markdown……"
}
```

* `content` 是提取后的正文 Markdown，导航栏、广告等页面框架大多已去掉
* 网页没有标题时 `title` 为空字符串
* 实测一篇文档页约 6400 字、1.6 秒；部分站点较慢，建议客户端超时设 30 秒以上

## 错误码对照

| HTTP | 错误信息示例 | 原因与处理 | 扣费 |
| - | - | - | - |
| 400 | `'url' must be a valid HTTP or HTTPS URL` | 网址格式不对 | 否 |
| 400 | `missing field 'url'` | 缺 `url` | 否 |
| 401 | `Invalid token.` | API Key 无效或未带 `Authorization` 头 | 否 |
| 404 | `failed to fetch URL` | 抓不到可用内容：目标页 404、域名不存在、内网地址、目标站拒绝访问、类型不支持等。换一个网址 | 否 |
| 429 | — | 超出上游限流（25 QPS，同一目标域名另有限制），等待后重试 | 否 |
| 503 | `no available channels for model deepseek-fetch` | 令牌所在分组没有开通本接口（如 ClaudeCode 分组），换 `default` / `svip` 令牌 | 否 |
| 5xx / 504 | — | 上游内部错误或抓取超时，稍后重试 | 否 |

> [!WARNING]
>
> **「软 404」照常扣费**：有些网站对不存在的页面不返回 404，而是返回首页或提示页，
> Fetch 会把它当成功抓取。调用前请自行确认网址有效。

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


## OpenAPI

````yaml api-reference/deepseek-fetch-openapi.yaml POST /v1/tools/fetch
openapi: 3.1.0
info:
  title: DeepSeek 网页抓取 API
  description: |
    `deepseek-fetch` —— DeepSeek 原生网页抓取接口，把任意网页抓成 Markdown 正文。

    - 不是对话模型，不消耗 token，**按成功请求次数计费**
    - 抓取失败（404）、参数错误（400）不扣费
    - 上游限流 25 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/fetch:
    post:
      tags:
        - 搜索与抓取
      summary: 网页抓取：deepseek-fetch
      description: |
        传入一个网址，返回网页标题和 Markdown 正文。请求体不需要 `model` 字段。
      operationId: deepseekToolsFetch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FetchRequest'
            example:
              url: https://docs.apiyi.com/
      responses:
        '200':
          description: 抓取成功（计费一次）
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FetchResponse'
              example:
                title: API易 文档中心
                content: |-
                  # API易 文档中心

                  正文已转成 Markdown……
        '400':
          description: 参数错误，不扣费：网址格式不对或缺少 url
        '401':
          description: API Key 无效
        '404':
          description: 抓不到可用内容，不扣费：目标页 404、域名不存在、内网地址、目标站拒绝访问等。错误信息为 failed to fetch URL
        '429':
          description: 超出上游限流（25 QPS），等待后重试
        '503':
          description: 令牌所在分组没有开通本接口（如 ClaudeCode 分组），请换 default / svip 分组令牌
      security:
        - bearerAuth: []
components:
  schemas:
    FetchRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          description: HTTP / HTTPS 网址，必须带域名，最长 8192 个字符，不能带用户名密码
          example: https://docs.apiyi.com/
    FetchResponse:
      type: object
      properties:
        title:
          type: string
          description: 网页标题，没有时为空字符串
        content:
          type: string
          description: 提取后的正文，Markdown 格式
  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.