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

# 同步截图

> `screenshot` 端点运行浏览器会话，执行 JavaScript，并在单次同步请求中返回 base64 编码的图像。

## 入门

### 基础 URL

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

### 请求示例

```bash theme={"system"}
curl -X POST 'https://screenshot.cleariflow.com/v1/screenshot' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_UNIQUE_API_KEY",
    "url": "https://cleariflow.com",
    "capture_full_page": true,
    "export_format": "jpeg"
  }'
```

成功请求会返回 base64 格式的截图及元数据：

<ResponseExample>
  ```json theme={"system"}
  {
    "ok": true,
    "image_base64": "/9j/4AAQSkZJRg...",
    "content_type": "image/jpeg",
    "meta": {
      "elapsed_ms": 4521
    }
  }
  ```
</ResponseExample>

解码 `image_base64` 以获取原始 JPEG 或 PNG 字节。

### 渲染选项

`render` 对象控制浏览器在截图前如何加载页面。所有字段均为可选 — 省略时使用服务器默认值。

```json theme={"system"}
"render": {
  "wait_until": "networkidle",
  "timeout_ms": 60000,
  "post_load_wait_ms": 2000,
  "ignore_https_errors": false,
  "full_page": true,
  "screenshot_format": "jpeg",
  "user_agent": "Mozilla/5.0 ...",
  "viewport": {
    "width": 1365,
    "height": 768
  }
}
```

| 字段                    | 类型      | 默认值                | 说明                                                                                     |
| --------------------- | ------- | ------------------ | -------------------------------------------------------------------------------------- |
| `wait_until`          | String  | `domcontentloaded` | 何时认为导航完成。使用 `domcontentloaded` 获得更快结果；若页面在初始 HTML 后通过 XHR/fetch 加载数据，使用 `networkidle`。 |
| `timeout_ms`          | Integer | `60000`            | 等待页面加载的最长时间（毫秒）。                                                                       |
| `post_load_wait_ms`   | Integer | `0`                | `wait_until` 之后、截图前的额外延迟（毫秒）。适用于动画或懒加载内容。                                              |
| `ignore_https_errors` | Boolean | `false`            | 为 `true` 时忽略目标页面的 TLS 证书错误。                                                            |
| `full_page`           | Boolean | `true`             | 为 `true` 时捕获整个可滚动页面高度。                                                                 |
| `screenshot_format`   | String  | `jpeg`             | 输出格式：`jpeg` 或 `png`。                                                                   |
| `user_agent`          | String  | —                  | 浏览器会话的自定义 User-Agent 字符串。                                                              |
| `viewport`            | Object  | `1365×768`         | 通过像素单位的 `width` 和 `height` 设置 viewport 大小。                                             |

### 便捷字段

这些顶层字段是合并到 `render` 和 `actions` 的别名，用于向后兼容和简化请求：

| 字段                  | 映射到                        | 说明                                           |
| ------------------- | -------------------------- | -------------------------------------------- |
| `capture_full_page` | `render.full_page`         | 全页截图开关。                                      |
| `width` / `height`  | `render.viewport`          | viewport 尺寸（像素）。                             |
| `delay`             | `render.post_load_wait_ms` | 截图前延迟（**秒**）。                                |
| `export_format`     | `render.screenshot_format` | `jpeg` 或 `png`。                              |
| `user_agent`        | `render.user_agent`        | 自定义 User-Agent。                              |
| `css_injection`     | `inject_css` 操作            | 当 `actions` 中没有 `inject_css` 操作时，截图前注入的 CSS。 |

使用扁平字段的示例：

```bash theme={"system"}
curl -X POST 'https://screenshot.cleariflow.com/v1/screenshot' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_UNIQUE_API_KEY",
    "url": "https://cleariflow.com",
    "width": 1280,
    "height": 720,
    "delay": 2,
    "export_format": "png"
  }'
```

### 资源选项

`resources` 对象控制浏览器在截图期间加载哪些资源类型。在视觉保真度允许的情况下，阻止重型资源可加快请求速度。

```json theme={"system"}
"resources": {
  "block": ["images", "fonts", "media"]
}
```

| 值        | 阻止                 |
| -------- | ------------------ |
| `images` | 图片（`<img>`、CSS 背景） |
| `fonts`  | Web 字体             |
| `media`  | 视频和音频流             |

### Legacy GET 端点

`GET /v1/` 返回原始图像字节（JPEG 或 PNG）而非 JSON。参数以查询字符串传递：

```
https://screenshot.cleariflow.com/v1/?api_key=YOUR_UNIQUE_API_KEY&url=https://cleariflow.com&capture_full_page=true&export_format=jpeg
```

支持的查询参数：`url`、`api_key`、`session_id`、`fingerprint`、`capture_full_page`、`width`、`height`、`delay`、`css_injection`、`user_agent`、`export_format`。

### 请求参数

<ParamField body="url" type="String" required>
  要捕获的目标 URL。必须是公开的 HTTP 或 HTTPS URL。对 localhost 和私有 IP 地址的请求会被 SSRF 防护阻止。
</ParamField>

<ParamField body="api_key" type="String" required>
  您的唯一 API 密钥。
</ParamField>

<ParamField body="session_id" type="String">
  可选的会话标识符，用于在多个请求之间复用浏览器状态（Cookie、local storage）。
</ParamField>

<ParamField body="fingerprint" type="String">
  浏览器指纹预设。支持的值：`desktop_en_us`、`desktop_ru_ru`、`mobile_en_us`。
</ParamField>

<ParamField body="render" type="Object">
  浏览器会话的渲染和截图选项。
</ParamField>

<ParamField body="render.wait_until" type="String">
  何时认为导航完成。值：`domcontentloaded`、`networkidle`。默认值：`domcontentloaded`。
</ParamField>

<ParamField body="render.timeout_ms" type="Integer">
  等待页面加载的最长时间（毫秒）。默认值：60000。
</ParamField>

<ParamField body="render.post_load_wait_ms" type="Integer">
  页面加载事件之后、截图前的额外延迟（毫秒）。
</ParamField>

<ParamField body="render.ignore_https_errors" type="Boolean">
  为 `true` 时忽略目标页面的 TLS 证书错误。
</ParamField>

<ParamField body="render.full_page" type="Boolean">
  为 `true` 时捕获整个可滚动页面。默认值：`true`。
</ParamField>

<ParamField body="render.screenshot_format" type="String">
  输出格式：`jpeg` 或 `png`。默认值：`jpeg`。
</ParamField>

<ParamField body="render.user_agent" type="String">
  浏览器会话的自定义 User-Agent。
</ParamField>

<ParamField body="render.viewport" type="Object">
  包含像素单位 `width` 和 `height` 的 viewport 大小。
</ParamField>

<ParamField body="resources" type="Object">
  资源加载控制。
</ParamField>

<ParamField body="resources.block" type="Array">
  要阻止的资源类型。支持的值：`images`、`fonts`、`media`。
</ParamField>

<ParamField body="actions" type="Array">
  截图前执行的浏览器操作有序列表。每个操作是带有 `type` 字段的对象。
</ParamField>

<ParamField body="actions[].type" type="String" required>
  操作类型。支持的值：`wait`、`wait_for`、`click`、`type`、`scroll`、`inject_css`。
</ParamField>

<ParamField body="actions[].selector" type="String">
  `wait_for`、`click` 或 `type` 操作的 CSS 选择器。
</ParamField>

<ParamField body="actions[].text" type="String">
  `type` 操作要输入的文本。
</ParamField>

<ParamField body="actions[].css" type="String">
  `inject_css` 操作的 CSS 字符串。
</ParamField>

<ParamField body="actions[].to" type="String">
  `scroll` 操作的滚动目标（例如 `bottom`）。
</ParamField>

<ParamField body="actions[].wait_ms" type="Integer">
  `wait` 操作的持续时间（毫秒）。
</ParamField>

<ParamField body="cookies" type="Array">
  导航前注入的 Cookie。每个 Cookie 对象需要 `name` 和 `value`；可选字段：`domain`、`path`。
</ParamField>

<ParamField body="capture_full_page" type="Boolean">
  `render.full_page` 的便捷别名。
</ParamField>

<ParamField body="width" type="Integer">
  `render.viewport.width` 的便捷别名。
</ParamField>

<ParamField body="height" type="Integer">
  `render.viewport.height` 的便捷别名。
</ParamField>

<ParamField body="delay" type="Integer">
  截图前延迟（秒）。映射到 `render.post_load_wait_ms`。
</ParamField>

<ParamField body="css_injection" type="String">
  当 `actions` 中尚未存在时，通过 `inject_css` 操作注入的 CSS。
</ParamField>

<ParamField body="export_format" type="String">
  `render.screenshot_format` 的便捷别名。值：`jpeg`、`png`。
</ParamField>

### 响应参数

API 响应以通用轻量 [JSON 格式](https://www.json.org/json-en.html) 返回。

<ResponseField name="ok" type="Boolean">
  截图是否成功完成。
</ResponseField>

<ResponseField name="image_base64" type="String">
  Base64 编码的图像数据。解码以获取原始 JPEG 或 PNG 字节。
</ResponseField>

<ResponseField name="content_type" type="String">
  图像的 MIME 类型（`image/jpeg` 或 `image/png`）。
</ResponseField>

<ResponseField name="meta" type="Object">
  有关截图的元数据，包括耗时（毫秒）。
</ResponseField>

<ResponseField name="error" type="Object">
  当 `ok` 为 `false` 时的错误详情。
</ResponseField>