shotanvil

shotanvil-examples

shotanvil 截图 API 的用法示例和实时同步的 OpenAPI 规范副本——1 screenshot = 1 request，真正免费的免费套餐，价格每月 $9 起。

基础 URL：https://api.shotanvil.com

访问方式

GET /take 和 POST /render-html 支持以下三种访问方式，并按此顺序检查：

1. x402 — 发送 X-Payment 标头（按次付费，无需注册，通过测试网结算）。
2. API key — 发送 X-Api-Key: <key> 或 ?access_key=<key>。
3. 无密钥 — 不需要凭据，按 IP 限流，仅在运营方启用了无密钥访问时可用。

无效的 API key 始终会返回 401，绝不会回退到无密钥访问，即使已启用无密钥访问也是如此——付费 key 即使拼写错误，也不会在不提示的情况下悄悄降级到较低套餐。

在 shotanvil.com 获取 API key。

快速入门

截取屏幕截图：

curl "https://api.shotanvil.com/take?url=https://example.com" \
  -H "X-Api-Key: $SHOTANVIL_API_KEY" \
  -o screenshot.png

获取文本和元数据（JSON 格式），而不是原始字节：

curl "https://api.shotanvil.com/take?url=https://example.com&response_format=json" \
  -H "X-Api-Key: $SHOTANVIL_API_KEY"

渲染内嵌 HTML：

curl -X POST https://api.shotanvil.com/render-html \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $SHOTANVIL_API_KEY" \
  -d '{"html": "<html><body><h1>Hello</h1></body></html>"}' \
  -o out.png

更多可运行示例：examples/curl.sh、 examples/node/screenshot.mjs。

常用的 GET /take 参数

参数	类型	说明
url	字符串，必填	目标页面 URL，仅限 http/https。
format	字符串	png（默认）、jpeg、webp 或 pdf。
full_page	布尔值	截取整个可滚动页面，而不只是视口。
viewport_width / viewport_height	整数	320–3840 / 240–2160。
cache_ttl	整数	缓存此精确渲染结果的秒数，范围为 0–86400。
fresh	布尔值	本次请求绕过缓存读取。
block_ads	布尔值	使用基于 EasyList 的屏蔽列表拦截广告网络请求。
block_cookie_banners	布尔值	注入 CSS 隐藏规则，隐藏常见的 Cookie 同意横幅。
dark_mode	布尔值	导航前模拟 prefers-color-scheme: dark。
response_format	字符串	binary（默认）返回原始字节；json 则以 JSON 包装图片（base64）和提取的文本/元数据。

完整参数参考、请求/响应架构以及每个字段的示例见 openapi.json——在任意 OpenAPI 查看器中打开（例如 editor.swagger.io），即可浏览规范。

速率限制

每个 API key 都有每秒速率限制和每日调用上限。GET /usage 会报告当前 key 当天的用量。超出任一限制都会返回 429，并包含 retry_after_s 字段。

保持 openapi.json 同步

此仓库中的 openapi.json 是一份特定时间点的副本，从实时 GET https://api.shotanvil.com/openapi.json 端点获取——它并非手动编写，会随着 API 的演进而逐渐过时。

在将其用于日常浏览以外的用途之前，或在未来更新此仓库之前，请重新获取并比较差异：

curl -sS https://api.shotanvil.com/openapi.json -o /tmp/openapi.latest.json
diff openapi.json /tmp/openapi.latest.json

如果存在差异，请检查差异，将 openapi.json 替换为最新副本并提交——不要直接手动编辑 openapi.json。

许可证

此仓库中的示例采用 MIT 许可证——可自由复制和改编。openapi.json 描述 shotanvil API，仅供参考。