你将得到什么

• 一个可用的 access key（免费档，无需绑卡）
• 本地文件 example.png（或你指定的 JPEG）
• 理解：一次成功渲染 = 计 1 次截图；失败与缓存命中不计费

课前准备

1. 终端可用 curl（macOS / Linux / WSL 均可）。
2. 能访问 https://curlshot.com/ （注册与 API）。
3. 本课不要把真实 key 贴进聊天、截图或公开仓库。

一、CurlShot 是什么（30 秒）

CurlShot 同时是：

1. 在线工具：打开 https://curlshot.com/ ，粘贴网址下载截图（可免费试用）。
2. HTTP API：GET https://curlshot.com/api/v1/screenshot?... 把 url / html / markdown 渲成 png、jpeg、webp、pdf，或滚动视频（mp4/webm/gif）。

Agent 友好材料：https://curlshot.com/llms.txt 、https://curlshot.com/openapi.json 、各文档页加 .md。

二、注册并复制 access key

按官方 Getting started：

1. 打开 https://curlshot.com/register 创建账号（不需要银行卡）。
2. 确认邮箱——未确认前 key 不可用。
3. 进入仪表盘 API keys，复制 access key。

对照： 把 key 当成密码。网页前端不要硬编码 key；要给公开页面用链接时，用官方文档里的 signed link（本课第二课后可再读 Authentication）。

把 key 放进当前 shell 环境变量（仅本机会话）：

export CURLSHOT_KEY='粘贴你的_access_key_不要提交到git'
# 对照：echo ${#CURLSHOT_KEY} 应大于 0；不要 echo 出完整 key

三、第一条截图请求（可抄）

官方示例（把 YOUR_ACCESS_KEY 换成变量）：

curl "https://curlshot.com/api/v1/screenshot?access_key=${CURLSHOT_KEY}&url=https://example.com" \
  --output example.png

对照结果（成功）

• 终端退出码 0
• 当前目录出现 example.png，可用图片查看器打开，内容为 example.com 首屏
• 文件是真正的 PNG（不是 JSON 报错文本）

快速自检：

file example.png
# 对照结果示例：PNG image data, ... （若显示 ASCII/JSON text，说明保存了错误响应）

若失败，API 不会返回坏图，而是 JSON，例如缺了 https://：

curl "https://curlshot.com/api/v1/screenshot?access_key=${CURLSHOT_KEY}&url=example.com"

典型字段：error_code、error_message、documentation_url。失败请求不计月度配额。完整代码表见 Errors。

四、改选项：整页 + 手机视口 + JPEG

选项就是查询串里多几个 name=value。官方 Getting started 示例：

curl "https://curlshot.com/api/v1/screenshot?access_key=${CURLSHOT_KEY}\
&url=https://en.wikipedia.org/wiki/Eiffel_Tower\
&viewport_device=iphone_15_pro\
&full_page=true\
&block_cookie_banners=true\
&format=jpeg" \
  --output eiffel.jpg

URL 编码： 目标页地址若含 & 或 ?，必须做 percent-encode，否则 curl 会截断。详见 The screenshot URL。

五、配额怎么算（本课必知）

官方价目（llms.txt / Pricing，核验时）：

• 一次成功渲染 = 1 次截图（与像素大小无关）
• 缓存命中与失败渲染不计费
• 查用量（不费截图）：GET https://curlshot.com/api/v1/usage（需带 key）

curl "https://curlshot.com/api/v1/usage?access_key=${CURLSHOT_KEY}"
# 对照：JSON 中可见当前周期配额相关字段（以实际响应为准）

响应头里也会有 X-Quota-Remaining、X-RateLimit-Remaining 等（以官方 Usage and limits 为准）。

六、本课检查清单

• 已确认邮箱且 access key 可用
• example.png 能打开且为 PNG
• 至少试过一次带 format=jpeg 或 viewport_device 的请求
• key 未写入公开仓库

下一课

把同一能力接到 MCP：https://curlshot.com/api/mcp，让 Cursor / Claude 等客户端直接调用 take_screenshot。

官方来源

1. https://curlshot.com/docs/getting-started.md
2. https://curlshot.com/docs/
3. https://curlshot.com/llms.txt
4. https://curlshot.com/pricing.md
5. https://curlshot.com/docs/errors.md