# DeepSeek 网页抓取

> 通用

提交网页抓取请求。`model` 固定为 `deepseek-tools-fetch`，仅用于平台选路，转发前被剥离；`url` 为待抓取的网页地址，原样透传给上游。

抓取结果受目标站点的可用性和访问策略影响；网关侧抓取超时为 60 秒。

## 请求地址

`POST https://api.modelverse.cn/v1/tools/fetch`

## 请求体

## 响应

- **200** — 抓取结果，包含页面标题与 Markdown 正文。
- **default** — 错误响应（网关侧参数/鉴权错误或上游非 200，原样透传状态码与错误体）。上游错误使用 OpenAI 兼容格式，`param` 恒为 `null`。

常见错误：

| HTTP 状态码 | 说明 |
|---|---|
| 400 | 请求体不合法，如缺少 `url`、URL 非 http/https、携带用户名密码，或指向内网地址（网关 SSRF 拦截） |
| 401 | API Key 缺失或无效 |
| 403 | 请求被上游安全策略拒绝 |
| 404 | 未能获取可用的网页内容，例如 URL 不可用、被站点策略拦截、目标站点返回错误、内容类型不受支持或页面没有可提取的 Markdown 正文 |
| 408 | 读取请求体超时 |
| 413 | 请求体超过大小限制 |
| 429 | 触发频率限制（含针对目标域名的限速） |
| 500 | 服务器内部错误 |
| 504 | 下游请求超时 |

遇到 408、429 或 5xx 时请等待后重试；其它 4xx 错误如不修改请求，请勿重试。


## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "x-language": "zh-CN",
  "info": {
    "title": "DeepSeek 网页抓取接口文档",
    "version": "1.0.0",
    "description": "这是 ModelVerse 上 **DeepSeek 网页抓取** 模型的接口文档。\n统一入口 `POST /v1/tools/fetch`，通过请求体中的 `model` 字段选路（转发前被剥离）。\n抓取单个网页，返回页面标题与 Markdown 格式正文，适用于 Agent 与 RAG 应用的网页阅读、内容提取场景。\n响应为非流式，一次性返回 JSON，**原样透传、原样返回，不做归一化**。\n计费：按次计费，HTTP 200 且 `content` 非空白计 1 次；请求失败、无可提取正文或超时不计费。\n安全：`url` 仅支持 http/https 协议，且必须是公网可访问地址，网关会拦截指向内网/保留地址段的请求（SSRF 防护）。\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API endpoint."
    }
  ],
  "tags": [
    {
      "name": "Tools Fetch",
      "description": "网页抓取。"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/tools/fetch": {
      "post": {
        "tags": [
          "Tools Fetch"
        ],
        "operationId": "createDeepseekToolsFetch",
        "summary": "DeepSeek 网页抓取",
        "description": "提交网页抓取请求。`model` 固定为 `deepseek-tools-fetch`，仅用于平台选路，转发前被剥离；`url` 为待抓取的网页地址，原样透传给上游。\n\n抓取结果受目标站点的可用性和访问策略影响；网关侧抓取超时为 60 秒。\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeepseekFetchRequest"
              },
              "examples": {
                "fetch": {
                  "summary": "抓取指定网页",
                  "value": {
                    "model": "deepseek-tools-fetch",
                    "url": "https://api-docs.deepseek.com/zh-cn/"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "抓取结果，包含页面标题与 Markdown 正文。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeepseekFetchResponse"
                },
                "examples": {
                  "result": {
                    "summary": "抓取结果（节选）",
                    "value": {
                      "title": "首次调用 API | DeepSeek API Docs",
                      "content": "# 首次调用 API\n\nDeepSeek API 使用与 OpenAI/Anthropic 兼容的 API 格式，通过修改配置，您可以使用 OpenAI/Anthropic SDK 来访问 DeepSeek API，或使用与 OpenAI/Anthropic API 兼容的软件。"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "错误响应（网关侧参数/鉴权错误或上游非 200，原样透传状态码与错误体）。上游错误使用 OpenAI 兼容格式，`param` 恒为 `null`。\n\n常见错误：\n\n| HTTP 状态码 | 说明 |\n|---|---|\n| 400 | 请求体不合法，如缺少 `url`、URL 非 http/https、携带用户名密码，或指向内网地址（网关 SSRF 拦截） |\n| 401 | API Key 缺失或无效 |\n| 403 | 请求被上游安全策略拒绝 |\n| 404 | 未能获取可用的网页内容，例如 URL 不可用、被站点策略拦截、目标站点返回错误、内容类型不受支持或页面没有可提取的 Markdown 正文 |\n| 408 | 读取请求体超时 |\n| 413 | 请求体超过大小限制 |\n| 429 | 触发频率限制（含针对目标域名的限速） |\n| 500 | 服务器内部错误 |\n| 504 | 下游请求超时 |\n\n遇到 408、429 或 5xx 时请等待后重试；其它 4xx 错误如不修改请求，请勿重试。\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeepseekErrorResponse"
                },
                "examples": {
                  "error": {
                    "summary": "标准 JSON 错误响应",
                    "value": {
                      "error": {
                        "message": "错误描述信息",
                        "type": "invalid_request_error",
                        "param": null,
                        "code": "invalid_request_error"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "平台下发的 API Key，通过 `Authorization: Bearer <API Key>` 传入。"
      }
    },
    "schemas": {
      "DeepseekFetchRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "url"
        ],
        "properties": {
          "model": {
            "type": "string",
            "const": "deepseek-tools-fetch",
            "description": "模型选路标识，固定为 `deepseek-tools-fetch`，转发前被剥离。"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "minLength": 1,
            "maxLength": 8192,
            "description": "要抓取的网页地址，长度不超过 8192；必须为含 host 的 HTTP/HTTPS URL，目标必须为公网地址，且不能携带用户名或密码。"
          }
        }
      },
      "DeepseekFetchResponse": {
        "type": "object",
        "required": [
          "title",
          "content"
        ],
        "properties": {
          "title": {
            "type": "string",
            "description": "页面标题；缺失时为空字符串。"
          },
          "content": {
            "type": "string",
            "description": "抓取后的 Markdown 正文。"
          }
        }
      },
      "DeepseekErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/DeepseekError"
          }
        }
      },
      "DeepseekError": {
        "type": "object",
        "required": [
          "message",
          "type",
          "code"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "错误说明。"
          },
          "type": {
            "type": "string",
            "description": "错误类型。",
            "examples": [
              "invalid_request_error"
            ]
          },
          "param": {
            "type": [
              "string",
              "null"
            ],
            "description": "上游错误中恒为 `null`。"
          },
          "code": {
            "type": "string",
            "description": "机器可读的错误码。",
            "examples": [
              "invalid_request_error"
            ]
          }
        }
      }
    }
  }
}
```