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

# 网站截图 API

> Cleariflow 网站截图 API 通过现代化的 RESTful JSON 接口，以 SSRF 防护、viewport 控制和浏览器自动化选项，捕获任意公开 URL 的 pixel-perfect 图像。

## 入门

<Card title="同步截图" icon="camera" href="screenshot/screenshot">
  `screenshot` 端点运行浏览器会话，并在 JSON 中返回 base64 编码的图像 — 适合程序化集成和 API Tester。
</Card>

<Card title="异步任务" icon="clock" href="screenshot/jobs">
  `jobs` 端点将截图任务入队，并允许轮询状态和结果 —— 适合高并发或加载较慢的页面。
</Card>

### REST 架构

网站截图 API 遵循 REST 原则，采用可预测的资源导向 URL 和标准 HTTP 状态码，实现无缝集成与错误处理。

### HTTPS 安全

所有 API 通信均使用 TLS 1.2 或更高版本加密，确保数据完整性和隐私。

### API 版本

网站截图 API 通过版本控制保持向后兼容，当前运行于 Version 1。

### 身份验证

API 密钥是访问网站截图 API 的唯一凭证。每个 Cleariflow 服务都需要独立的密钥。在 JSON 请求体中以 `api_key` 传递，或在 legacy GET 端点中作为查询参数传递。

### 基础 URL

```
https://screenshot.cleariflow.com
```

### 页面渲染

页面在真实的无头浏览器中渲染。截图前 JavaScript 会完全执行。内置 SSRF 防护会阻止对 localhost 和私有 IP 范围的请求。

## 响应与错误码

请求失败时，API 返回带有特定代码和描述的结构化 JSON 错误响应，便于排查问题。

| 代码  | 类型                    | 详情                             |
| --- | --------------------- | ------------------------------ |
| 200 | OK                    | 截图已成功捕获。                       |
| 202 | Accepted              | 异步任务已成功入队。                     |
| 400 | Bad request           | 错误请求 — 无效 URL、被阻止的目标或格式错误的负载。  |
| 401 | Unauthorized          | 请求不可接受。通常是因为 API 密钥缺失或不正确。     |
| 422 | Quota reached         | 因 API 积分不足，请求已中止。（免费套餐）        |
| 429 | Too many requests     | 已达到每秒允许的请求数上限。免费套餐限制为每秒 1 次请求。 |
| 500 | Internal server error | 由于服务器端错误，无法完成请求。               |