urlshot · 松智云 截图命令行工具

一行命令给网页截图。urlshot 是松智云网页截图 API 的官方 CLI 工具。

环境要求

• Node.js 18 或更高版本
• 松智云 API Key（免费注册获取）

安装

npm install -g urlshot

快速开始

export SONGZHI_API_KEY=sk-xxx

# 基础截图，输出到当前目录
urlshot https://example.com

截图成功后输出 JSON：

{
  "taskId": "d55c14cac3da46deba9edfdf2d0f670e",
  "status": "done",
  "imageUrl": "/screenshots/d55c14ca.png",
  "durationMs": 1317,
  "imageSize": 15542
}

选项

urlshot https://example.com \
  --width 1920 \
  --height 1080 \
  --fullPage \
  --mobile \
  --format png \
  --wait 2000

选项	类型	默认值	说明
--width <px>	number	1280	视口宽度
--height <px>	number	720	视口高度
--fullPage	flag	false	全页长图截图
--mobile	flag	false	移动端 User-Agent + 375 宽视口
--format <fmt>	string	png	输出格式：png / jpeg / webp / pdf
--wait <ms>	number	0	页面加载后额外等待（毫秒）

环境变量

变量	说明
SONGZHI_API_KEY	松智云 API Key（必需）

在松智云控制台创建 API Key。

高级用法

# 输出到文件（重定向 imageUrl 后用 curl 下载）
result=$(urlshot https://example.com --format pdf)
image_url=$(echo "$result" | grep -o '"imageUrl":"[^"]*"' | cut -d'"' -f4)
curl -O "https://api.songzhiyun.com$image_url"

# 批量截图
for url in $(cat urls.txt); do
  urlshot "$url" --width 375 --mobile --format jpeg
done

# CI/CD 中使用（截图并检查 HTTP 状态）
urlshot https://your-site.com --width 1280 || echo "截图失败，请排查"

错误处理

# urlshot 在失败时返回非零退出码
if urlshot "$URL" > screenshot.json 2>/dev/null; then
  echo "截图成功"
else
  echo "截图失败: 检查 API Key 和 URL 是否正确" >&2
fi

相关链接

• 松智云 官网
• API 文档
• 控制台
• Java SDK
• Python SDK
• Node.js SDK

License

MIT