Metadata-Version: 2.4
Name: songzhiyun
Version: 0.1.0
Summary: 松智云 网页截图 API Python SDK
License: MIT
Project-URL: Homepage, https://songzhiyun.com
Project-URL: Repository, https://github.com/xuelb1983/sdk-python
Keywords: screenshot,songzhiyun,api
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25

# 松智云 Python SDK

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

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

## 环境要求

- Python 3.8 或更高版本
- 松智云 API Key（[免费注册获取](https://songzhiyun.com)）

## 安装

```bash
pip install songzhiyun
```

## 快速开始

```python
from songzhiyun import SongzhiClient

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

## 完整选项

```python
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}` |

## 异步模式

```python
# 提交任务（立即返回 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']}")
```

## 错误处理

```python
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 | 服务器内部错误 |

## 相关链接

- [松智云 官网](https://songzhiyun.com)
- [API 文档](https://songzhiyun.com/docs.html)
- [控制台](https://songzhiyun.com/dashboard.html)
- [Java SDK](https://github.com/songzhiyun/sdk-java)
- [Node.js SDK](https://github.com/songzhiyun/sdk-node)
- [CLI 工具](https://github.com/songzhiyun/cli)

## License

MIT
