snapWONDERS/snapWONDERS-SDK-Python

snapWONDERS — 揭示隐藏之物。隐藏你的所有。 # snapwonders — snapWONDERS API 的 Python 客户端 snapWONDERS API 的官方 Python 客户端：隐写术、取证媒体分析以及 格式转换。该客户端封装了可恢复的 TUS 上传以及 session → job → poll → download 的编排流程，因此只需几行代码即可完成整个作业。 所有 snapWONDERS API 服务均可通过 Clearnet / **Web** 和 Dark Web **Tor** 及 **I2P** 访问。 # 安装与设置 ## snapWONDERS API key 在开始之前，你需要一个 snapWONDERS API key： * 在 [snapWONDERS 注册](https://snapwonders.com/sign-up) 注册并创建一个账号。如果你 希望通过 Tor 或 I2P 创建账号，可以通过 Tor 或 I2P 门户访问 snapWONDERS 来完成。要获取暗网链接，请访问 [安全浏览](https://snapwonders.com/browsing-safely)。 * 在你的账号设置中，生成一个 API key。新 key 以 `sw_` 开头。它会作为 `X-Api-Key` 标头在每次请求中发送——请妥善保密。 ## 安装软件包 ``` pip install snapwonders # once published ``` # 快速开始 ``` from snapwonders import Client client = Client(api_key="sw_your_key_here") # base_url defaults to https://snapwonders.com print(client.status()) # no key needed for status # 将 secret 隐藏在 cover image 中（最后一个文件是 cover）。 job = client.stego.hide(["secret.png", "cover.jpg"], password="Str0ng!Pass") for result in job.results(): result.download("out/") # "out/" is a directory — the server filename is kept # 再次显示它。 job = client.stego.reveal("out/cover-share.avif", password="Str0ng!Pass") job.results()[0].download("recovered/") ``` `client.analyse`（取证分析）和 `client.convert`（媒体转换）遵循相同的结构 — 一次调用输入，结果输出： ``` # Forensic analysis — 对每个文件进行 A-F 评级，收集其生成的 overlay assets。 job = client.analyse.run(["photo.jpg"], face_detection=True) for item in job.results(): print(item.filename, item.grade, item.face_count) for asset in item.assets: # ELA map, face overlay, … asset.download("out/") # Convert media — image format 的 key 为 `image_format` (jpeg/png/webp/avif/heic/jxl)。 job = client.convert.run(["photo.png"], image_format="webp") job.results()[0].download("out/") ``` 想自己控制每个阶段？分步操作的接口也是公开的： `create_session` → `upload(path, step=…)` → `wait_for_uploads()` → `start_job(**opts)` → `wait()` → `results()`。 # 示例 可直接运行的端到端示例位于 [`examples/`](examples/) —— 隐写术、取证分析 和转换，每一个都是包含示例图片的独立脚本： ``` export SNAPWONDERS_API_KEY=sw_your_key_here python examples/hide_and_reveal.py # hide a file in an image, then reveal it python examples/analyse.py # grade an image A–F + download overlay assets python examples/convert.py # JPEG → WebP ``` 请参阅 [`examples/WALKTHROUGH.md`](examples/WALKTHROUGH.md) 以查看真实的输入/输出图片和实时的取证分析 JSON 结果，或者查看 [`examples/README.md`](examples/README.md) 了解如何运行它们。 # 错误 SDK 抛出的每一个错误都是 `SnapwondersError` 的类型化子类，因此你可以根据 错误类型进行分支处理，而无需检查 HTTP 状态码： | 异常 | 触发条件 | |-----------|-------------| | `AuthError` | API key 缺失、格式错误、未知或被撤销 | | `ProRequiredError` | 在免费账号上使用了 Pro 专属选项 | | `SessionExpiredError` | 超过了 24 小时的上传 session 时间窗口 | | `RateLimitError` | 被速率限制 — 当服务器提供时携带 `retry_after` | | `MaintenanceError` | snapWONDERS 因维护而暂时不可用 — 携带 `retry_after` | | `JobFailedError` | 作业以 `failed` 状态结束 — 携带服务器提供的原因 | | `TusUploadError` | 可恢复上传步骤失败 | | `NetworkError` | 无法连接到 API | | `ApiError` | 任何其他非 2xx 响应 | # 运行测试 ``` pip install -e ".[dev]" pytest # offline smoke tests — no API key required # integration tests 需要针对 dev API 设置 SNAPWONDERS_TEST_API_KEY ``` # 文档 有用的文档可在以下位置找到： * 交互式 Swagger UI 和完整的 endpoint 参考： [snapWONDERS API](https://snapwonders.com/api) * 引导式的分步集成指南： [snapWONDERS 开发者](https://snapwonders.com/developers) # 联系方式 ## 安全隐患 如果你发现了任何安全隐患，请通过 [联系 snapWONDERS](https://snapwonders.com/contact) 联系我们，并将主题设置为 **"安全隐患"**，同时提供有关你发现的问题的信息。如果你希望通过 Tor 或 I2P 联系，可以通过 Tor 或 I2P 门户访问 snapWONDERS 来完成。要获取暗网链接，请访问 [安全浏览](https://snapwonders.com/browsing-safely)。 ## 常见问题与解答 你的问题可能已经在 [FAQ](https://snapwonders.com/faq) 中得到解答。请务必先 查看 FAQ 的内容。否则，你可以通过 [联系 snapWONDERS](https://snapwonders.com/contact) 与我们取得联系。 ## 联系作者 使用此链接联系作者 [Kenneth Springer](https://kennethbspringer.au/)。 # 许可证 MIT — 版权所有 (c) 2026 Kenneth Springer @ snapWONDERS。请参阅 [LICENSE](LICENSE)。 **范围。** MIT 许可证**仅涵盖此客户端库**。它不授予与其通信的 snapWONDERS API、服务、数据、模型或算法的任何权利——这些都是**专有的** 并归 Kenneth Springer @ snapWONDERS 所有。此库仅向 API 发送 HTTP 请求；它不包含其任何实现。使用该 API 需要有效的 API key，并 受 [snapWONDERS 服务条款](https://snapwonders.com/terms) 的约束。

标签：API, Python, 媒体分析, 数字取证, 无后门, 格式转换, 自动化脚本, 逆向工具, 隐写术