KaCa

Appearance

基础内容 ​

url ​

需要截图的网站的 URL。或 html 参数中必须有一个。 带有示例请求 URL 的示例如下： url=https://www.baidu.com/

html ​

你可以直接指定 HTML 内容，进行渲染 html=<h1>Hello, world!</h1>

format ​

输出的图片或者 pdf 格式。 可选的值如下:

  • png
  • jpeg
  • webp
  • pdf

默认值 jpeg.

参数参考例子 format=jpeg

selector ​

一个类似 CSS 的选择器，用于指定要截图的元素。这是可选的。

参数参考例子 selector=.content:

PDF 渲染 ​

如果您希望生成的 PDF 尽可能接近完整页面截图，请使用以下选项组合：

format=pdf&media_type=screen&pdf_print_background=true&pdf_fit_one_page=true

pdf_print_background ​

设置为 true 以打印背景图形。默认值为 false。

pdf_fit_one_page ​

默认值为 false。

当选项设置为true时，API 将尝试将网站适应一页。这是最接近完整页面截图的 PDF，而不会分成多页。

pdf_landscape ​

设置为 true 以将 PDF 方向设置为横向。默认值为 false。

pdf_paper_format ​

指定 PDF 输出的纸张格式。可用选项有：

  • “a0”: ISO A0 纸张尺寸 (841 x 1189 mm)
  • “a1”: ISO A1 纸张尺寸 (594 x 841 mm)
  • “a2”: ISO A2 纸张尺寸 (420 x 594 mm)
  • “a3”: ISO A3 纸张尺寸 (297 x 420 mm)
  • “a4”: ISO A4 纸张尺寸 (210 x 297 mm) - 默认值
  • “a5”: ISO A5 纸张尺寸 (148 x 210 mm)
  • “a6”: ISO A6 纸张尺寸 (105 x 148 mm)
  • “legal”: 法律纸张尺寸 (8.5 x 14 英寸)
  • “letter”: 信纸尺寸 (8.5 x 11 英寸)
  • “tabloid”: 小报尺寸 (11 x 17 英寸)

如果未指定，默认纸张格式为“a4”。

完整页面 ​

full_page ​

要截取完整页面的屏幕截图，请设置 full_page=true。

默认值为false。

当 full_page 设置为 true 时，full_page_scroll会自动设置为 true，直到您覆盖它。这是为了确保所有懒加载的图片都被请求和渲染。

full_page_scroll ​

如果设置为 true，则会滚动到页面底部然后返回顶部。默认值为 false。

当full_page设置为 true 时，full_page_scroll会自动设置为 true，直到您覆盖它。这是为了确保所有懒加载的图片都被请求和渲染。

请求 URL 的示例：

full_page_scroll_delay ​

默认值为 400 微秒。用它来指定您希望页面滚动到底部的速度。

一些网站需要大于 400 微秒的值来触发懒加载图片的加载。

与full_page_scroll_by结合使用以找到最佳解决方案。

full_page_scroll_by ​

默认值为视口的高度。用它来指定您希望页面滚动到底部的速度。

一些网站需要小于视口高度的值来触发懒加载图片的加载。尝试在 100 到 500 之间的值。然而，不要犹豫尝试可能对您有效的任何值。

与full_page_scroll_delay结合使用以找到最佳解决方案。

full_page_max_height ​

默认值未设置。用它来限制完整页面屏幕截图的高度。还可以处理和修复与无限滚动相关的问题。

视口 ​

viewport_device ​

默认值未设置。

instead of manually specifying viewport parameters like width and height, you can specify a device to use for emulation. In addition, other parameters of the viewport, including the user agent, will be set automatically.

The viewport_device option sets the next options for you: viewport_width, viewport_height, device_scale_factor, viewport_mobile, viewport_has_touch, viewport_landscape. You can change these options and override the ones set by the viewport_device option.

Use the list of devices for available values. Use the id property of the device as viewport_device, e.g. viewport_device=galaxy_s9+_landscape.

WARNING

API 不使用实际设备来截图。它是大多数情况下都有效的模拟。

带有viewport_device=Galaxy S8 landscape的请求 URL 示例：

viewport_width ​

viewport_height ​

WARNING

如果设置了 viewport_device 选项，此参数将覆盖它！

浏览器视口的宽度（像素）。

浏览器的视口是您可以查看网页内容的车窗区域。

viewport_width 默认值为 1280。 viewport_height 默认值为 1024。

带有viewport_width=1920和viewport_height=1080的请求 URL 示例：

device_scale_factor ​

WARNING

如果设置了 viewport_device 选项，此参数将覆盖它！

该参数影响截图的分辨率和清晰度,默认值是 1，如果需要更高清晰度可以设置为 2，或更高。 设置设备比例因子，可以将其视为 DPR（设备像素比）。可接受的值范围在 1 到 5 之间，包括小数，如 2.25。

如果您需要以更高的像素密度渲染屏幕截图，如 Apple 的 Retina Display，请设置为 2。

此参数可以覆盖 viewport_device 选项设置的值。

带有device_scale_factor=2的请求 URL 示例：

viewport_landscape ​

WARNING

如果设置了 viewport_device 选项，此参数将覆盖它！

默认值为 false。如果视口是横向模式，请设置为 true。

此参数可以覆盖 viewport_device 选项设置的值。

带有viewport_landscape=true的请求 URL 示例：

图片 ​

image_quality ​

以指定质量渲染图片。对于以下格式可用：

jpeg 允许的范围在 0 到 100 之间。默认值为 80。

带有image_quality=10的请求 URL 示例：

omit_background ​

为图片渲染透明背景。只有在网站未定义背景颜色时才有效。对于 png,webp 响应格式可用： 默认值为false。

设置 omit_background=true 以截取具有透明背景的屏幕截图。

模拟 ​

media_type ​

如果您希望请求的页面支持渲染为打印机，请指定print。如果页面默认渲染为打印机，而您希望它渲染为屏幕，请使用screen。

带有media_type=print的请求 URL 示例：

自定义 ​

hide_selector ​

hide_selector选项允许在截图之前隐藏元素。您可以使用 css 选择器规则，所有匹配每个选择器的元素将通过将 display 样式属性设置为 none !important 来隐藏。

带有hide_selector=.a hide_selector=a,img的请求 URL 示例：

scripts ​

scripts 参数允许注入自定义 JavaScript 并自定义页面行为。

带有scripts=document.body.innerHTML="Hello, world!"或scripts=https://xx.xx.com/xx.js的请求 URL 示例：

styles ​

styles 参数允许注入自定义样式并自定义页面。它可能有助于为 Open Graph 协议生成美丽的图片。

带有styles=h1{color: red !important;}的请求 URL 示例：

阻塞 ​

block_requests ​

通过指定 URL、域或甚至一个简单的模式来阻塞请求，如block requests=.*.example.com/.*。您可以通过block_requests=example.com&block_requests=http://.*多次指定参数。阻塞规则是 js RegExp。

通过 URL 或域阻塞请求可以用来测试当资源不可用时网站如何响应。或者它可能用来加速页面加载。

或者，例如，通过block_requests=.*carbonads.com&block_requests=.*google-analytics.com阻塞广告和跟踪器：

block_resources ​

按类型阻塞加载资源。可用的资源类型有：

  • document
  • stylesheet
  • image
  • media
  • font
  • script
  • texttrack
  • xhr
  • fetch
  • eventsource
  • websocket
  • manifest
  • other

阻塞资源可能有助于在截图之前优化页面加载速度。

您可以通过block_resources=stylesheet&block_resources=image指定多个值：

地理位置 ​

geolocation_latitude ​

geolocation_longitude ​

geolocation_accuracy ​

为请求设置地理位置纬度。如果设置了其中一个，则两者都需要设置。 您还可以以米为单位设置地理位置精度。

从埃菲尔铁塔拍摄精度为 50 米的屏幕截图geolocation_latitude=48.858184&geolocation_longitude=2.294720&geolocation_accuracy=50：

请求 ​

user_agent ​

WARNING

如果设置了 viewport_device 选项，此参数将覆盖它！

请求的用户代理。默认值是 Puppeteer 使用的浏览器的最新版本。

带有user_agent='Mozilla/6.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/113.0.0.0 Safari/537.36'的请求 URL 示例：

authorization ​

为请求设置 Authorization 头。

当您想通过基本身份验证或令牌截图受保护的页面时，设置 authorization 头是适当的。

例如，如果使用基本身份验证和凭据，如 username:password，将其编码为 Base64 格式dXNlcm5hbWU6cGFzc3dvcmQ=，然后像authorization=Basic+dXNlcm5hbWU6cGFzc3dvcmQ=一样设置 authorization 头的值。

cookies ​

为请求设置 cookies，格式为<cookie-name>=<cookie-value>; Domain=<domain-value>; Secure; HttpOnly。您可以指定多个 cookies。

Set-Cookie: <cookie-name>=<cookie-value>
// 如果省略，此属性默认为当前文档URL的主机，不包括子域。
Set-Cookie: <cookie-name>=<cookie-value>; Domain=<domain-value>
Set-Cookie: <cookie-name>=<cookie-value>; Expires=<date>
Set-Cookie: <cookie-name>=<cookie-value>; Path=<path-value>
Set-Cookie: <cookie-name>=<cookie-value>; HttpOnly
Set-Cookie: <cookie-name>=<cookie-value>; Secure

Set-Cookie: <cookie-name>=<cookie-value>; SameSite=Strict
Set-Cookie: <cookie-name>=<cookie-value>; SameSite=Lax
Set-Cookie: <cookie-name>=<cookie-value>; SameSite=None; Secure

// 多个属性也是可能的，例如：
Set-Cookie: <cookie-name>=<cookie-value>; Domain=<domain-value>; Secure; HttpOnly

转义的查询字符串可能如下所示：cookies=name1=val1;Domain=example.com;Secure;HttpOnly&cookies=name2=val2;+Domain=example.com;+Secure;+HttpOnly

headers ​

为请求设置额外的头，格式为 Header-Name:Header-Value

头可以覆盖所有其他先前隐式设置的头，如 cookies 或 authorization。

您一次可以指定多个头headers=X-Header-1:Value-1&headers=X-Header-2:Value-2：

time_zone ​

为请求设置时区。可用的时区有：

  • America/Belize
  • America/Cayman
  • America/Chicago
  • America/Costa_Rica
  • America/Denver
  • America/Edmonton
  • America/El_Salvador
  • America/Guatemala
  • America/Guayaquil
  • America/Hermosillo
  • America/Jamaica
  • America/Los_Angeles
  • America/Mexico_City
  • America/Nassau
  • America/New_York
  • America/Panama
  • America/Port-au-Prince
  • America/Santiago
  • America/Tegucigalpa
  • America/Tijuana
  • America/Toronto
  • America/Vancouver
  • America/Winnipeg
  • Asia/Kuala_Lumpur
  • Asia/Shanghai
  • Asia/Tashkent
  • Europe/Berlin
  • Europe/Kiev
  • Europe/Lisbon
  • Europe/London
  • Europe/Madrid
  • Pacific/Auckland
  • Pacific/Majuro

带有time_zone=Asia/Shanghai的请求 URL 示例：

bypass_csp ​

在少数情况下，尤其是当您尝试向网站添加[自定义脚本]时，您需要绕过网站的内容安全策略。您需要将 bypass_csp 简化为 true，默认值为 false。

等待 ​

在渲染网站屏幕截图时，这些是其中一个最棘手的参数。如果您想了解如何等待页面准备就绪，请继续阅读。或直接使用这些等待选项。

wait_until ​

使用wait_until等待事件发生后再截图或渲染 HTML 或 PDF。

wait_until的默认值是['networkidle2']。允许的值有：

  • load：当 load 事件被触发时，导航成功；
  • domcontentloaded：当 DOMContentLoaded 事件被触发时，导航完成；
  • networkidle0：当网络连接数不超过 0 且持续至少 500ms 时，导航完成；
  • networkidle2：当网络连接数不超过 2 且持续至少 500ms 时，考虑导航完成。 参数接受多个值。这意味着屏幕截图将在所有事件都发生后再进行。

带有wait_until=networkidle2&wait_until=domcontentloaded的请求示例：

delay ​

指定延迟选项（以秒为单位）以在截图或渲染 HTML 或 PDF 之前等待。

当wait_until选项对您不起作用，并且您希望确保一切准备就绪时，这是合适的。

默认值为 0。

延迟值必须是一个介于 0 和timeout值之间的整数。

带有delay=5的请求示例：

timeout ​

指定超时（以秒为单位），如果截图或渲染仍然不可能，将在何时中止请求。默认值和最大值是 50。

带有timeout=20的请求示例：

储存 ​

当缓存选项设置为 true 时，仅在缓存未命中时才会触发上传。这意味着，如果您想随时上传截图，请将缓存选项设置为 false。

您可以使用任何与 S3 兼容的存储将屏幕截图、呈现的 HTML 或 PDF 存储到配置的 S3 存储桶中。

如果您不关心获取实际情况而只想将渲染结果上传到存储，请指定 response_type=empty。

请求示例如下 response_type=empty：

store ​

默认值为 空。用于 store=aliyun 触发将截取的屏幕截图、渲染后的 HTML 或 PDF 上传到配置的 阿里云 存储桶。请确保已配置对的访问权限。

可选值为 aliyun 请求示例如下 store=aliyun：

storage_path ​

设置 存储路径,不要指定扩展名 如果设置了 store 参数，则该参数默认是 kaca。 您还可以在路径部分指定“子目录”。

请求示例如下 storage_path=latest/example：

storage_endpoint ​

设置 阿里云的 endpoint

storage_access_key_id ​

设置 存储访问密钥 ID 访问密钥 ID。它将覆盖仪表板配置中指定的密钥 ID。

storage_secret_access_key ​

设置 存储秘密访问密钥,秘密访问密钥。它将覆盖仪表板配置中指定的密钥。

storage_bucket ​

设置 存储桶 您可以覆盖您配置的默认存储桶 storage_bucket=bucketname。

storage_class ​

设置 存储类别 默认值为 standard。

storage_acl ​

设置 存储访问控制列表 未设置默认值。

上传文件时指定 ACL 值。

storage_return_location ​

设置 存储返回位置 您可以要求返回 OSS 存储后 返回的文件位置。 请求示例如下 storage_return_location=true：

您将以 Header 形式接收位置，X-Kaca-Store-Location 或者将其设置 response_type=json 为 JSON 的属性 store.location。

Released under the MIT License.

Copyright © 2025-present