curlshot Skill
通过 CurlShot API 对网页截图。当用户想要某个 URL 的截图、整页截取、移动端或平板视图、PDF 或滚动视频,或想把自己的 HTML 或 Markdown 渲染成图片或 PDF 时使用。需要在 CURLSHOT_API_KEY 环境变量中配置 CurlShot 访问密钥。
安装方式:把技能目录放入 ~/.claude/skills/(Claude Code)或在 claude.ai 设置中启用;也可复制右侧安装命令一键添加。
技能指令原文(SKILL.md)
CurlShot screenshots
Overview
CurlShot renders a web page in a real browser and returns it as an image (PNG, JPEG, WebP), a PDF, or a video of the page scrolling (MP4, WebM, GIF). One HTTP request does it: GET https://curlshot.com/api/v1/screenshot?url=…, or a POST with a JSON body for your own HTML or Markdown.
Prerequisites
curlon the machine and network access tohttps://curlshot.com.- A CurlShot access key in
CURLSHOT_API_KEY. If it is not set, ask the user for it. A free key comes from https://curlshot.com/register: 100 screenshots a month, no card needed. Paid plans start at $19 a month (https://curlshot.com/pricing). - Never print the key, paste it into a file in the repository, or put it in a link you show the user. Send it in the
X-Access-Keyheader (anAuthorization: Bearerheader or anaccess_keyquery parameter also work). - Only public pages work out of the box. Local and private network addresses (localhost, 192.168.x.x, ...) are refused: for a local page, send its HTML instead (see step 4).
Instructions
- Check that
CURLSHOT_API_KEYis set (test -n "$CURLSHOT_API_KEY") without echoing its value. - Take the screenshot with a GET request:
curl -sS -G "https://curlshot.com/api/v1/screenshot" \
-H "X-Access-Key: $CURLSHOT_API_KEY" \
--data-urlencode "url=https://example.com" \
-d format=png \
-D headers.txt \
--output screenshot.png
-G with --data-urlencode keeps the page address correctly encoded.
- Add options as one more
-d name=valueeach (GET) or as fields in a POST JSON body:
| Want | Option |
| --- | --- |
| Whole page, top to bottom | full_page=true |
| Phone or tablet view | viewport_device= (list: https://curlshot.com/docs/devices.md) |
| Window size | viewport_width=1440, viewport_height=900 |
| Retina sharpness | device_scale_factor=2 |
| Dark theme | dark_mode=true |
| One element only | selector= |
| Output format | format=png / jpeg / webp / pdf / mp4 / webm / gif |
| Hide cookie banners and ads | block_cookie_banners=true, block_ads=true |
| Wait for content | wait_until=networkidle, delay=2, wait_for_selector= |
| Reuse a stored copy for free | cache=true |
A misspelled option is rejected with invalid_options and a hint, never ignored. Every option: https://curlshot.com/docs/options.md
- To render your own HTML or Markdown (or a local page), POST JSON:
curl -sS -X POST "https://curlshot.com/api/v1/screenshot" \
-H "X-Access-Key: $CURLSHOT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"html": "<h1>Hello</h1>", "format": "png", "viewport_width": 1200, "viewport_height": 630}' \
--output card.png
Use "markdown": "..." instead of html to render Markdown as a styled page, and "format": "pdf" for a PDF.
- Check the result before you use it (see Output), then tell the user where the file is.
Output
- Success: HTTP
200with aContent-Typeofimage/,video/orapplication/pdf. The body is the file, saved by--output. - Failure: HTTP
400or higher withContent-Type: application/json. Do not keep that file as an image; read it as an error (see Error Handling). - Useful response headers:
X-Quota-RemainingandX-Quota-Reset(screenshots left this period),X-RateLimit-Remaining,X-Concurrency-Remaining,X-Cache(cache hit or miss), andX-Reference-Id(quote it when contacting support). - Billing: one successful render counts as one screenshot, whatever its size. Failed renders and cache hits are free.
Error Handling
An error body looks like this:
{
"error_code": "invalid_options",
"error_message": "fullpage: is not a known option; did you mean `full_page`?",
"documentation_url": "https://curlshot.com/docs/errors#invalid_options",
"errors": [{ "field": "fullpage", "message": "is not a known option; did you mean `full_page`?" }]
}
Branch on error_code, never on error_message.
| Status | Codes | What to do |
| --- | --- | --- |
| 400, 413, 422 | invalid_options, invalid_url, invalid_request, content_too_large, selector_not_found, page_blocked | Do not retry. Fix the request using errors and the hint. |
| 401 | access_key_required, access_key_invalid | Do not retry. Ask the user to check CURLSHOT_API_KEY. |
| 402 | quota_exceeded | Do not retry. Tell the user the quota is used up and show upgrade_url. |
| 403 | host_not_allowed, feature_not_available, email_not_verified | Do not retry. For a private or local address, send the HTML instead. For a plan feature, show upgrade_url. |
| 429 | rate_limited, concurrency_limit, queue_limit, failure_limit | Wait the seconds in Retry-After, then retry once. |
| 500, 502, 503, 504 | internal_error, navigation_failed, timeout, renderer_busy, renderer_unavailable, service_unavailable | Retry once after a short pause. For timeout, drop wait_until=networkidle (the default is load) or lower delay. |
Every code with its cause and fix: https://curlshot.com/docs/errors.md
Examples
Full-page screenshot of a site on an iPhone, cookie banners hidden:
curl -sS -G "https://curlshot.com/api/v1/screenshot" \
-H "X-Access-Key: $CURLSHOT_API_KEY" \
--data-urlencode "url=https://example.com" \
-d viewport_device=iphone_15_pro -d full_page=true -d block_cookie_banners=true \
--output mobile.png
A4 PDF of a page:
curl -sS -G "https://curlshot.com/api/v1/screenshot" \
-H "X-Access-Key: $CURLSHOT_API_KEY" \
--data-urlencode "url=https://example.com/invoice" \
-d format=pdf -d pdf_paper_format=a4 \
--output page.pdf
Markdown rendered to a PDF:
curl -sS -X POST "https://curlshot.com/api/v1/screenshot" \
-H "X-Access-Key: $CURLSHOT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"markdown": "# Release notes\n\n- Faster renders", "format": "pdf"}' \
--output notes.pdf
Check the status before trusting the file:
status=$(curl -sS -G "https://curlshot.com/api/v1/screenshot" \
-H "X-Access-Key: $CURLSHOT_API_KEY" \
--data-urlencode "url=https://example.com" \
-o shot.png -w '%{http_code}')
[ "$status" = 200 ] || { cat shot.png; rm shot.png; }
Resources
- Docs: https://curlshot.com/docs
- Getting started: https://curlshot.com/docs/getting-started.md
- All options: https://curlshot.com/docs/options.md
- Device presets: https://curlshot.com/docs/devices.md
- Errors: https://curlshot.com/docs/errors.md
- OpenAPI description: https://curlshot.com/openapi.json
- Everything in one file: https://curlshot.com/llms-full.txt
- Pricing: https://curlshot.com/pricing
- MCP alternative: agents with MCP support can use the hosted server
https://curlshot.com/api/mcp(streamable HTTP,Authorization: Bearer) with the toolstake_screenshotandlist_devices. Setup per client is in this repository's README.