> ## 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 Authentication

> 使用 X-API-Key 请求头对 Scraping API 请求进行身份验证。速率限制、密钥格式和按密钥配置。

所有 Scraping API 端点（除 `GET /healthz` 外）都需要身份验证。

## 传递 API 密钥

根据端点使用以下方法之一传递您的 API 密钥：

**HTTP 请求头（用于 `/fetch`、`/usage`、`/network/*`、`/debug/pick`）：**

```bash theme={null}
curl -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Target-URL: https://example.com" \
  https://scraping-api.55-tech.com/fetch
```

**JSON 请求体字段（用于 `/browser`、WebSocket `/ws` 和 AMQP `/amqp`）：**

```json theme={null}
{
  "apiKey": "YOUR_API_KEY",
  "url": "https://example.com"
}
```

对于 `/browser`、`/ws` 和 `/amqp`，密钥从 JSON 请求体字段 `apiKey`（或 `key`）或 `X-API-Key` 请求头中读取。

## 错误响应

| Status | Meaning  |
| ------ | -------- |
| `401`  | API 密钥缺失 |
| `403`  | API 密钥无效 |

## 速率限制

每个 API 密钥有可配置的速率限制：

| Setting                   | Default      |
| ------------------------- | ------------ |
| Requests per second (RPS) | 10           |
| Burst capacity            | Equal to RPS |

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

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

请实现指数退避策略：等待 1 秒、2 秒、4 秒，依此类推。

检查当前速率限制和使用情况：

```bash theme={null}
curl -H "X-API-Key: YOUR_API_KEY" \
  https://scraping-api.55-tech.com/usage
```

响应包含您的剩余令牌数：

```json theme={null}
{
  "rate_limit": {
    "rps": 10.0,
    "burst": 10,
    "remaining": 9.3
  }
}
```

## 公开端点

以下端点**无需**身份验证：

| Endpoint       | Description          |
| -------------- | -------------------- |
| `GET /`        | API 概述和状态            |
| `GET /healthz` | 存活探针（`{"ok": true}`） |

## 获取密钥

联系 [contact@55-tech.com](mailto:contact@55-tech.com) 获取根据您的使用场景配置速率限制的 API 密钥。