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

# Scraping API Overview

> 55 Tech Scraping API — 通过 80 多个地理分布式代理节点路由 HTTP、浏览器渲染、WebSocket 和 AMQP 请求。

## 什么是 Scraping API？

**Scraping API** 由 [55 Tech](https://55-tech.com/) 提供，可将您的 HTTP、浏览器渲染、WebSocket 和 AMQP 请求通过由 80 多个地理分布式代理节点组成的网络进行路由。API 会在数秒内自动识别每个目标最可靠的代理节点，让您的请求立即变得更加成功，无需自行管理代理。

**您可以做什么：**

* **HTTP 抓取** — GET/POST/PUT/PATCH/DELETE，完全控制请求头、请求体和 Cookie
* **浏览器渲染** — 支持 JavaScript 渲染的抓取，包含 Cookie、截图和自定义 JS 执行
* **WebSocket 中继** — 双向帧中继（Socket.IO、SignalR、Centrifugo、GraphQL-WS、原生 WebSocket）
* **AMQP 消费者** — 通过 Server-Sent Events (SSE) 流式传输 RabbitMQ 消息
* **地理定向** — 将请求固定到特定国家或单个代理节点
* **代理链接** — 通过您自己的代理路由请求，获得额外的 IP 灵活性
* **响应验证** — 验证渲染页面中是否存在预期内容，缺失时自动在不同节点重试
* **封锁检测** — 当检测到访问限制时，响应中包含 `meta.blocked` 标志

## 基础 URL

```
https://scraping-api.55-tech.com
```

## 身份验证

通过 `X-API-Key` 请求头或（对于 WebSocket/AMQP）`apiKey` 请求体字段传递您的 API 密钥。详见 [Authentication](/zh/scraping-api/authentication)。

## 端点

| Endpoint                   | Method                        | Auth               | Description                            |
| -------------------------- | ----------------------------- | ------------------ | -------------------------------------- |
| `/fetch`                   | GET, POST, PUT, PATCH, DELETE | Required           | 通过代理网络代理 HTTP 请求                       |
| `/browser`                 | GET                           | Header             | 支持 JavaScript 渲染的抓取（Cookie、截图、JS 执行）   |
| `/browser/stream`          | GET                           | Header             | 实时浏览器会话 — 流式传输网络、WebSocket、DOM 事件（SSE） |
| `/ws`                      | WebSocket                     | In connect message | 双向 WebSocket 中继                        |
| `/amqp`                    | POST                          | In body or header  | AMQP/RabbitMQ 消费者中继（SSE 流）             |
| `/usage`                   | GET                           | Required           | 按密钥的使用指标（请求数、字节数、热门域名）                 |
| `/network/agents`          | GET                           | Required           | 列出所有代理节点及其标识、名称、国家                     |
| `/network/status`          | GET                           | Required           | 网络概况（节点总数、每个国家的节点数）                    |
| `/network/geo`             | GET                           | Required           | 按国家分组的代理节点                             |
| `/network/health/{domain}` | GET                           | Required           | 按代理节点查看域名的健康状态                         |
| `/debug/pick`              | GET                           | Required           | 预览将选择哪个代理节点                            |
| `/healthz`                 | GET                           | No                 | 存活探针                                   |

## 控制请求头

这些请求头用于控制路由，在转发到目标之前会被剥离：

| Header          | Aliases                                         | Description           | Example                        |
| --------------- | ----------------------------------------------- | --------------------- | ------------------------------ |
| `X-Target-URL`  | —                                               | 目标 URL（无需编码，推荐方式）     | `https://example.com/?foo=bar` |
| `X-Geo`         | `X-Geo-CC`, `X-Geo-Strict`, `X-CC`, `X-Country` | 限制到特定国家（逗号分隔的 ISO 代码） | `US,DE,AT`                     |
| `X-Expect-JSON` | —                                               | 提示目标响应为 JSON          | `1`                            |
| `X-Agent`       | —                                               | 通过标识路由到特定代理节点，或逗号分隔列表 | `de1`, `de1,at5,us3`           |
| `X-Timeout`     | —                                               | 覆盖请求超时时间（秒）           | `60`                           |

## 速率限制

速率限制**按 API 密钥**执行：

* 默认：每秒 10 个请求
* WebSocket 连接在建立时消耗 1 个令牌（非按帧计费）

当触发速率限制时，API 返回 `429` 及以下响应头：

```
Retry-After: 1
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
```

使用 `GET /usage` 查看当前使用情况。

## 抓取响应格式

所有 HTTP 抓取响应遵循以下结构：

```json theme={null}
{
  "meta": {
    "status": 200,
    "final_url": "https://example.com/",
    "http_version": "HTTP/2",
    "elapsed_ms": 245,
    "blocked": false,
    "headers": { "content-type": "text/html" },
    "agent": { "id": "scraping-de1" },
    "bytes": 4521
  },
  "raw": "<!DOCTYPE html>...",
  "raw_json": null
}
```

| Field               | Description                           |
| ------------------- | ------------------------------------- |
| `meta.status`       | 目标返回的 HTTP 状态码                        |
| `meta.final_url`    | 重定向后的最终 URL                           |
| `meta.http_version` | 使用的 HTTP 版本（例如 HTTP/2）                |
| `meta.elapsed_ms`   | 往返时间（毫秒）                              |
| `meta.blocked`      | 如果在响应中检测到访问限制则为 `true`                |
| `meta.agent.id`     | 处理请求的节点（例如 `scraping-de1`）            |
| `meta.bytes`        | 响应体大小（字节）                             |
| `raw`               | 响应体文本（非 JSON 时）                       |
| `raw_json`          | 解析后的 JSON 对象（响应为有效 JSON 时，否则为 `null`） |

## 后续步骤

<Columns cols={3}>
  <Card title="Authentication" icon="key" href="/zh/scraping-api/authentication">
    设置您的 API 密钥。
  </Card>

  <Card title="Quickstart" icon="rocket" href="/zh/scraping-api/quickstart">
    发送您的第一个代理请求。
  </Card>

  <Card title="Browser" icon="window" href="/zh/scraping-api/browser">
    使用真实浏览器渲染 JavaScript 页面。
  </Card>
</Columns>