截图 API v1

以下内容说明了 POST /api/v1/screenshots.

身份验证

请在 Authorization 请求头中传入您的 API 密钥：

Authorization: Bearer <api_key>

创建截图

接口地址: POST /api/v1/screenshots

请求体: JSON

最小请求示例

curl -X POST "https://api.page-ops.com/api/v1/screenshots" \
  -H "Authorization: Bearer $SCREENSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

同步请求（在允许时）

curl -X POST "https://api.page-ops.com/api/v1/screenshots" \
  -H "Authorization: Bearer $SCREENSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "mode": "sync",
    "timeoutMs": 8000,
    "fullPage": false
  }'

如果同步等待窗口在任务完成前耗尽，API 将返回 status=processing. 请继续使用以下接口轮询： GET /api/v1/screenshots/{jobId}.

关键参数

url

必填。要截图的目标 URL。

mode

可选。 async （默认）或 sync.

timeoutMs

在 sync. 时必填。取值必须 > 0 且 < 10000.

fullPage

可选。对于 sync 模式，它必须为 false.

同步模式约束

即使你请求了 mode=sync, ，服务端也会回退到 async，除非满足：

mode == "sync"

timeoutMs != null

0 < timeoutMs < 10000

fullPage == false

参数参考（完整）

字段	类型	必需	默认值	说明
url	string	是	-	目标 URL。
mode	string	否	async	接受 async 或 sync （不区分大小写）。;
timeoutMs	int?	否	-	仅用于 sync。取值必须满足 0 < timeoutMs < 10000.
fullPage	bool	否	false	sync 要求 false.
viewport	object?	否	-	覆盖默认视口。
format	string?	否	-	当前仅支持 png 。其他格式保留到未来版本。
quality	int?	否	-	当前会被忽略（未来仅用于 jpeg/webp）。
waitUntil	string?	否	-	建议值： load, domcontentloaded, networkidle.
delayMs	int?	否	-	在 waitUntil 后额外增加的延迟。
selector	string?	否	-	仅截取特定元素。
headers	object?	否	-	额外请求头字典。
cookies	array?	否	-	注入的 Cookie 列表。
javascript	string?	否	-	要注入的自定义 JS（取决于实现）。;
css	string?	否	-	要注入的自定义 CSS（取决于实现）。;
device	string?	否	-	建议值： desktop/iphone/ipad/pixel.
strictDevice	bool?	否	-	如果为 true，不支持的设备应直接失败（取决于实现）。;
colorScheme	string?	否	-	建议值： light/dark/no-preference.
proxy	string?	否	-	保留给未来版本，当前会被忽略。
trace	bool?	否	-	保留给未来版本，当前会被忽略。
har	bool?	否	-	保留给未来版本，当前会被忽略。
returnDom	bool?	否	-	保留给未来版本，当前会被忽略。
returnNetwork	bool?	否	-	保留给未来版本，当前会被忽略。
priority	int?	否	-	保留给未来版本，当前会被忽略。

viewport

字段	类型	必需	说明
viewport.width	int	否	视口宽度。
viewport.height	int	否	视口高度。

cookies[]

字段	类型	必需	说明
cookies[].name	string	是	Cookie 名称。
cookies[].value	string	是	Cookie 值。
cookies[].domain	string?	否	Cookie 域名。
cookies[].path	string?	否	Cookie 路径。

响应示例

异步（默认）

{ "jobId": "<guid>", "status": "pending" }

同步（已完成）

{ "jobId": "<guid>", "status": "completed", "result": { "url": "https://..." } }

同步（失败）

{ "jobId": "<guid>", "status": "failed", "errorMessage": "..." }

同步（超时）

{ "jobId": "<guid>", "status": "processing" }

对于异步调用（或同步超时），请使用 GET /api/v1/screenshots/{jobId} 检查状态。可能的取值包括： pending, processing, completed, failed, expired.

错误说明

HTTP	触发场景	请求体
400	请求体缺失，或 url 缺失/为空	BadRequest
401	API 密钥无效或缺失	中间件返回
402	配额超出	{ "error": "quota_exceeded", "operationKey": "screenshot.capture", ... }
429	触发速率限制	{ "error": "rate_limited", "operationKey": "screenshot.capture", ... }
404	任务不存在	NotFound

实战示例

适用于常见集成场景的实用示例。

传递目标站点认证令牌（通过 headers）

如果你要截图的页面受保护（Bearer/JWT/session token），可通过以下方式转发： headers:

{
  "url": "https://example.com/dashboard",
  "headers": {
    "Authorization": "Bearer <target_site_token>"
  }
}

设置 Cookie（基于会话的登录）

如果网站使用 Cookie 做身份验证，请通过以下方式传入： cookies:

{
  "url": "https://example.com/account",
  "cookies": [
    { "name": "session", "value": "<cookie_value>", "domain": "example.com", "path": "/" }
  ]
}

自定义请求头（User-Agent / locale）

{
  "url": "https://example.com",
  "headers": {
    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "Accept-Language": "en-US,en;q=0.9"
  }
}

视口 + 格式 + 质量

{
  "url": "https://example.com",
  "viewport": { "width": 1280, "height": 720 },
  "format": "jpeg",
  "quality": 85
}

等待页面加载 + 添加延迟

{
  "url": "https://example.com",
  "waitUntil": "networkidle",
  "delayMs": 500
}

截取指定元素（selector）

{
  "url": "https://example.com/pricing",
  "selector": "#pricing"
}

获取状态

轮询任务：

GET /api/v1/screenshots/{jobId}