songzhiyun 0.1.0

松智云 网页截图 API Python SDK

松智云 Python SDK

松智云网页截图 API 的 Python 客户端库。支持 Python 3.8+。

环境要求

• Python 3.8 或更高版本
• 松智云 API Key（免费注册获取）

安装

pip install songzhiyun

快速开始

from songzhiyun import SongzhiClient

client = SongzhiClient("sk-xxx")
result = client.screenshot("https://example.com")
print(result["imageUrl"])
# → /screenshots/d55c14ca.png

完整选项

from songzhiyun import SongzhiClient

client = SongzhiClient("sk-xxx")

result = client.screenshot(
    "https://example.com",
    width=1920,
    height=1080,
    full_page=True,        # 全页长图
    mobile=True,           # 移动端模拟
    wait_ms=2000,          # 页面加载后额外等待
    format="png",          # png / jpeg / webp / pdf
    quality=95,            # 图片质量 1-100（jpeg/webp）
    ad_block=True,         # 广告拦截
    watermark={
        "text": "机密文档",
        "position": "bottom-right",  # top-left / top-right / center / bottom-left / bottom-right
        "opacity": 50,               # 0-100
    },
)

print(result["imageUrl"])

Python SDK 自动将 snake_case 参数转换为 API 要求的 camelCase。

参数说明

参数	类型	默认值	说明
width	int	1280	视口宽度（像素）
height	int	720	视口高度（像素）
full_page	bool	False	全页截图（长图）
mobile	bool	False	移动端 User-Agent + 375 宽视口
wait_ms	int	0	页面加载后额外等待（毫秒）
format	str	"png"	输出格式：png / jpeg / webp / pdf
quality	int	90	图片质量 1-100（jpeg/webp）
ad_block	bool	True	广告拦截
watermark	dict	None	水印配置 {"text":"...", "position":"...", "opacity":50}

异步模式

# 提交任务（立即返回 taskId，不阻塞）
task = client.submit("https://example.com", width=1280, height=720)
print(f"taskId: {task['taskId']}")

# ... 做其他事情 ...

# 轮询直到完成
result = client.poll(task["taskId"], timeout=60, interval=1)
print(f"imageUrl: {result['imageUrl']}")

错误处理

from songzhiyun import SongzhiClient, SongzhiError

try:
    result = client.screenshot("https://example.com")
except SongzhiError as e:
    print(f"错误码: {e.code}, 消息: {e.message}")

错误码说明：

错误码	说明
1001	参数错误或资源不存在
1002	缺少认证信息
1003	本月配额已用完
1004	并发请求超限
1006	请求过于频繁
5000	服务器内部错误

相关链接

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

License

MIT