截图 /take

核心截图接口，兼容 ScreenshotOne 风格参数；GET 使用 Query，POST 使用 JSON Body。

端点

GET  /take
POST /take

通过平台边缘网关 https://api.1diff.shop 访问。GET 将所有参数放在 Query String；POST 可将参数放在 JSON Body（与 Query 等效，以实现为准）。

url、html、markdown 三者互斥，必须且只能提供其一。未传 format 时默认为 png。

请求参数

下列表格由代码中的参数目录自动生成，与网关校验逻辑保持一致。

输入源

参数	类型	默认值	说明
url*	string	—	目标页面 URL，须为 http(s) 完整地址，最长 2048 字符
html	string	—	直接渲染的 HTML 字符串；与 url、markdown 互斥
markdown	string	—	直接渲染的 Markdown 字符串；与 url、html 互斥

视口与裁剪

参数	类型	默认值	范围	说明
viewport_width	number	1280	100–7680	视口宽度（像素）
viewport_height	number	720	100–30000	视口高度（像素）
screenshot_element	string	—	—	仅截取指定 CSS 选择器对应元素
selector	string	—	—	与 screenshot_element 类似的元素选择器
crop_element	string	—	—	裁剪区域元素选择器
crop_selector	string	—	—	裁剪区域 CSS 选择器
viewport_device	string	—	—	模拟设备类型（如 iPhone、iPad 等预设）

等待策略

参数	类型	默认值	范围	说明
delay	number	0	0–30000	页面加载后额外等待时间（毫秒）
timeout	number	—	1000–120000	整次截图请求超时（毫秒）
wait_for_still_dom	boolean	false	—	等待 DOM 稳定后再截图
initially_wait_for_still_dom	boolean	false	—	页面打开后先等待 DOM 稳定
wait_until_dom_content_loaded	boolean	false	—	等待 DOMContentLoaded 事件
wait_until_network_is_idle	boolean	false	—	等待网络空闲
wait_for	string	—	—	等待条件表达式
wait_for_selector	string	—	—	等待 DOM 中出现指定选择器
wait_for_event	string	—	—	等待指定浏览器事件
initial_wait	string	—	—	初始等待时间或条件

屏蔽与拦截

参数	类型	默认值	说明
block_ads	boolean	false	屏蔽广告
block_tracking	boolean	false	屏蔽跟踪脚本
block_chats	boolean	false	屏蔽在线客服组件
block_cookie_banners	boolean	false	屏蔽 Cookie 横幅
disable_fonts	boolean	false	禁用自定义字体加载
click_accept_cookies	boolean	false	自动点击接受 Cookie
block_resources	string	—	按模式拦截资源 URL
allow_resources	string	—	按模式放行资源 URL
hide_selector	string	—	截图前隐藏匹配选择器的元素
block_selector	string	—	截图前移除匹配选择器的元素

注入

参数	类型	默认值	说明
css	string	—	注入自定义 CSS
javascript	string	—	注入自定义 JavaScript

输出

参数	类型	默认值	范围	说明
format	string	png	—	输出格式：png, jpeg, webp, gif, tiff, avif, heif, pdf
image_quality	number	80	1–100	仅 jpeg/webp 有效，图像质量 1–100
full_page	boolean	false	—	是否截取完整可滚动页面
retina	boolean	false	—	是否使用 2x 设备像素比
download	boolean	false	—	以附件方式下载
output	string	—	—	输出目标或存储方式
response_type	string	—	—	响应类型（如二进制或 JSON 元数据）

PDF

参数	类型	默认值	说明
pdf_page_size	string	—	PDF 页面尺寸
pdf_margin_top	string	—	PDF 上边距
pdf_margin_bottom	string	—	PDF 下边距
pdf_margin_left	string	—	PDF 左边距
pdf_margin_right	string	—	PDF 右边距
pdf_display_header_footer	string	—	PDF 是否显示页眉页脚

高级

参数	类型	默认值	说明
touch	boolean	false	模拟触摸设备
bypass_heuristic	boolean	false	绕过部分启发式限制
force_async	boolean	false	强制异步渲染
async	boolean	false	异步模式
embed_v2	boolean	false	嵌入模式（v2）
embed	boolean	false	嵌入模式（v1）
cache	boolean	false	启用响应缓存
no_cache	boolean	false	跳过缓存强制重新渲染
request_headers	string	—	自定义请求头（序列化）
cookies	string	—	请求携带的 Cookie（序列化）
locale	string	—	浏览器区域设置（如 zh-CN）
timezone	string	—	时区（如 Asia/Shanghai）
color_scheme	string	—	强制浅色/深色配色（如 light、dark）
cache_key	string	—	自定义缓存键
storage_key	string	—	对象存储键名
notion_oauth_token	string	—	Notion OAuth 令牌（集成场景）

响应

成功（200）

返回二进制图像或 PDF（由 format 决定）。

Header	说明
`Content-Type`	MIME 类型，如 `image/png`
`X-Screenshot-Duration-Ms`	截图耗时（毫秒）
`X-RateLimit-Limit`	每日请求上限
`X-RateLimit-Remaining`	今日剩余配额
`X-RateLimit-Reset`	配额重置时间（Unix 秒）
`X-Cache`	`HIT` 或 `MISS`

错误

常见状态码见错误码。

代码示例

# 基础截图
curl "http://localhost:3200/take?url=https://example.com&access_key=YOUR_KEY" -o screenshot.png

# 自定义视口与全页
curl "http://localhost:3200/take?url=https://example.com&access_key=YOUR_KEY&viewport_width=1920&viewport_height=1080&full_page=true&format=jpeg&image_quality=90" -o screenshot.jpg

const base = 'http://localhost:3200';
const params = new URLSearchParams({
  url: 'https://example.com',
  viewport_width: '1920',
  full_page: 'true',
  format: 'jpeg',
  image_quality: '90',
});

const res = await fetch(`${base}/take?${params}`, {
  headers: { Authorization: 'Bearer YOUR_KEY' },
});
const buffer = await res.arrayBuffer();

import requests

resp = requests.get(
    'http://localhost:3200/take',
    params={
        'url': 'https://example.com',
        'access_key': 'YOUR_KEY',
        'viewport_width': 1920,
        'full_page': True,
        'format': 'jpeg',
        'image_quality': 90,
    },
)
with open('screenshot.jpg', 'wb') as f:
    f.write(resp.content)

在 Playground 中试用