# Kimi 网页抓取

> 通用

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

## 请求地址

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

## 请求体

## 响应

- **200** — 抓取结果,包含抓取 URL、Markdown 正文与页面标题。
- **default** — 错误响应(网关侧参数/鉴权错误或上游非 200,原样透传状态码与错误体)。

上游常见错误:

| HTTP 状态码 | error.type | 说明 |
|---|---|---|
| 400 | `invalid_request` | 请求体不是合法 JSON |
| 400 | `invalid_url` | URL 为空、缺少主机名或协议非 http/https |
| 401 | - | API Key 缺失或无效(无错误响应体) |
| 403 | `security_risk` | URL 触发上游安全风控,请更换 URL |
| 404 | `markdown_not_found` | 页面无可提取的正文内容 |
| 408 | `client_canceled` | 客户端在服务端返回前断开连接 |
| 429 | `rate_limited` | 触发频率/并发限制;响应头携带 `X-RateLimit-Limit`、`X-RateLimit-Remaining`,触发每秒请求数限制时还携带 `X-RateLimit-Reset` |
| 429 | `rate_limit_unavailable` | 限速服务暂时不可用,请稍后重试 |
| 500 | `internal_error` | 上游内部错误,请稍后重试 |
| 502 | `upstream_failed` | 上游服务暂时不可用,请稍后重试 |
| 504 | `timeout` | 抓取超时,请稍后重试 |


## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "x-language": "zh-CN",
  "info": {
    "title": "Kimi 网页抓取接口文档",
    "version": "1.0.0",
    "description": "这是 ModelVerse 上 **Kimi(Moonshot)网页抓取** 模型的接口文档。\n统一入口 `POST /v1/tools/fetch`,通过请求体中的 `model` 字段选路(转发前被剥离)。\n抓取指定 URL 的网页内容,返回页面标题与 Markdown 格式正文,适用于网页阅读、资料整理等内容提取场景。\n响应为非流式,一次性返回 JSON,**原样透传、原样返回,不做归一化**。\n计费:一次成功调用计 1 次;上游失败或页面无可提取正文(200 但 markdown 为空白)不计费。\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": "createKimiToolsFetch",
        "summary": "Kimi 网页抓取",
        "description": "提交网页抓取请求。`model` 固定为 `kimi-tools-fetch-custom`,仅用于平台选路,转发前被剥离;`url` 为待抓取的网页地址,原样透传给上游。\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ToolsFetchRequest"
              },
              "examples": {
                "fetch": {
                  "summary": "抓取指定网页",
                  "value": {
                    "model": "kimi-tools-fetch-custom",
                    "url": "https://platform.kimi.com/docs/api/overview"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "抓取结果,包含抓取 URL、Markdown 正文与页面标题。",
            "headers": {
              "X-Msh-Track-Id": {
                "$ref": "#/components/headers/MshTrackId"
              },
              "X-Msh-Chat-Id": {
                "$ref": "#/components/headers/MshChatId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ToolsFetchResponse"
                },
                "examples": {
                  "result": {
                    "summary": "抓取结果",
                    "value": {
                      "url": "https://platform.kimi.com/docs/api/overview",
                      "markdown": "# API 概述\n\nKimi API 开放平台文档入口。\n\n![image1](https://platform.kimi.com/assets/logo/dark.svg)\n\n更多正文内容……",
                      "title": "API 概述 - Kimi API 开放平台"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "错误响应(网关侧参数/鉴权错误或上游非 200,原样透传状态码与错误体)。\n\n上游常见错误:\n\n| HTTP 状态码 | error.type | 说明 |\n|---|---|---|\n| 400 | `invalid_request` | 请求体不是合法 JSON |\n| 400 | `invalid_url` | URL 为空、缺少主机名或协议非 http/https |\n| 401 | - | API Key 缺失或无效(无错误响应体) |\n| 403 | `security_risk` | URL 触发上游安全风控,请更换 URL |\n| 404 | `markdown_not_found` | 页面无可提取的正文内容 |\n| 408 | `client_canceled` | 客户端在服务端返回前断开连接 |\n| 429 | `rate_limited` | 触发频率/并发限制;响应头携带 `X-RateLimit-Limit`、`X-RateLimit-Remaining`,触发每秒请求数限制时还携带 `X-RateLimit-Reset` |\n| 429 | `rate_limit_unavailable` | 限速服务暂时不可用,请稍后重试 |\n| 500 | `internal_error` | 上游内部错误,请稍后重试 |\n| 502 | `upstream_failed` | 上游服务暂时不可用,请稍后重试 |\n| 504 | `timeout` | 抓取超时,请稍后重试 |\n",
            "headers": {
              "X-Msh-Track-Id": {
                "$ref": "#/components/headers/MshTrackId"
              },
              "X-Msh-Chat-Id": {
                "$ref": "#/components/headers/MshChatId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ToolsFetchErrorResponse"
                },
                "examples": {
                  "invalidUrl": {
                    "summary": "URL 非法",
                    "value": {
                      "error": {
                        "message": "The provided URL is invalid: only http and https are supported",
                        "type": "invalid_url",
                        "code": "invalid_url"
                      }
                    }
                  },
                  "securityRisk": {
                    "summary": "触发安全风控",
                    "value": {
                      "error": {
                        "message": "We consider the current URL poses a security risk and are unable to provide fetch service at this time.",
                        "type": "security_risk",
                        "code": "security_risk"
                      }
                    }
                  },
                  "markdownNotFound": {
                    "summary": "无可提取正文",
                    "value": {
                      "error": {
                        "message": "No text/markdown content found for the current URL.",
                        "type": "markdown_not_found",
                        "code": "markdown_not_found"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "平台下发的 API Key,通过 `Authorization: Bearer <API Key>` 传入。"
      }
    },
    "headers": {
      "MshTrackId": {
        "description": "上游请求 ID,所有响应(含错误响应)均携带并原样透传;排查问题时请提供该 ID。",
        "schema": {
          "type": "string"
        }
      },
      "MshChatId": {
        "description": "上游会话 ID,固定为 `toolgw-{X-Msh-Track-Id}`;排查问题时请一并提供。",
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "ToolsFetchRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "url"
        ],
        "properties": {
          "model": {
            "type": "string",
            "const": "kimi-tools-fetch-custom",
            "description": "模型选路标识,固定为 `kimi-tools-fetch-custom`,转发前被剥离。"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "要抓取的网页 URL,仅支持 http/https 协议,目标必须为公网地址。"
          }
        }
      },
      "ToolsFetchResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "url",
          "markdown",
          "title"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "抓取 URL。"
          },
          "markdown": {
            "type": "string",
            "description": "抓取结果的 Markdown 内容;文本与图片按在页面中出现的顺序拼接,\n图片以 `![imageN](url)` 占位符形式嵌入,各段之间以空行分隔。\n"
          },
          "title": {
            "type": "string",
            "description": "页面标题。"
          }
        }
      },
      "ToolsFetchErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ToolsFetchError"
          }
        }
      },
      "ToolsFetchError": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "message",
          "type",
          "code"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "错误说明。"
          },
          "type": {
            "type": "string",
            "description": "机器可读的错误类型(如 `invalid_url`、`security_risk`、`markdown_not_found`、`rate_limited`、`timeout`)。",
            "examples": [
              "invalid_url"
            ]
          },
          "code": {
            "type": "string",
            "description": "机器可读的错误码,与 type 一致。",
            "examples": [
              "invalid_url"
            ]
          }
        }
      }
    }
  }
}
```