snapWONDERS — 揭示隐藏之物。隐藏属于你的秘密。
# snapWONDERS Go SDK — snapWONDERS API 客户端
snapWONDERS API 的官方 Go 客户端：提供隐写术、取证媒体分析和格式转换功能。该客户端封装了可恢复的 TUS 上传以及 session → job → poll → download 的编排流程，因此只需几行代码即可完成整个任务。
所有 snapWONDERS API 服务均可通过 Clearnet / **Web** 以及 Dark Web 的 **Tor** 和 **I2P** 访问。
# 安装和设置
## snapWONDERS API 密钥
在开始之前，您需要一个 snapWONDERS API 密钥：
* 在 [snapWONDERS 注册](https://snapwonders.com/sign-up) 注册并创建一个账户。如果您希望通过 Tor 或 I2P 创建账户，可以通过 Tor 或 I2P 门户访问 snapWONDERS。有关暗网链接，请访问 [安全浏览](https://snapwonders.com/browsing-safely)。
* 在您的账户设置下，生成一个 API 密钥。新密钥以 `sw_` 开头。它会作为 `X-Api-Key` 标头发送到每个请求中——请妥善保管。
## 安装包
```
go get github.com/snapWONDERS/snapWONDERS-SDK-Go
```
# 快速开始
```
package main
import (
"fmt"
snapwonders "github.com/snapWONDERS/snapWONDERS-SDK-Go"
)
func main() {
client := snapwonders.NewClient("sw_your_key_here") // base URL defaults to https://snapwonders.com
status, _ := client.Status() // no key needed for status
fmt.Println(status)
// Hide a secret inside a cover image (the last file is the cover).
job, err := client.Stego.Hide([]string{"secret.png", "cover.jpg"}, "Str0ng!Pass")
if err != nil {
panic(err)
}
files, _ := job.Results()
for _, f := range files {
f.Download("out/") // "out/" is a directory — the server filename is kept
}
// Reveal it again.
revealed, _ := client.Stego.Reveal("out/cover-share.avif", "Str0ng!Pass")
rf, _ := revealed.Results()
rf[0].Download("recovered/")
}
```
`client.Analyse`（取证分析）和 `client.Convert`（媒体转换）遵循相同的结构——传入一次调用，输出结果：
```
// Forensic analysis — grade each file A–F, collect the overlay assets it produced.
job, _ := client.Analyse.Run([]string{"photo.jpg"}, snapwonders.WithOption("face_detection", true))
items, _ := job.Results()
for _, item := range items {
fmt.Println(item.Filename, item.Grade, item.FaceCount)
for _, asset := range item.Assets { // ELA map, face overlay, …
asset.Download("out/")
}
}
// Convert media — set the output format with WithOption.
job, _ = client.Convert.Run([]string{"photo.png"}, snapwonders.WithOption("image_format", "webp"))
out, _ := job.Results()
out[0].Download("out/")
```
想自己控制每个阶段？逐步操作接口也是公开的：`CreateSession()` → `Upload(path, step)` → `WaitForUploads()` → `StartJob(...)` → `Wait()` → `Results()`。
# 示例
可运行的端到端示例位于 [`examples/`](examples/) 中——隐写术、取证分析和转换，每个都是一个独立的程序，并附带一个示例图像：
```
export SNAPWONDERS_API_KEY=sw_your_key_here
go run ./examples/hideandreveal # hide a file in an image, then reveal it
go run ./examples/analyse # grade an image A–F + download overlay assets
go run ./examples/convert # PNG → WebP
```
# 错误
SDK 返回的每个失败都是实现了 `SnapwondersError` 标记接口的类型化错误，因此您可以使用 `errors.As` 来匹配失败类型，而无需检查 HTTP 状态码：
```
files, err := job.Results()
var authErr *snapwonders.AuthError
if errors.As(err, &authErr) {
// handle a bad/expired API key
}
```
| 错误 | 返回时机 |
|-------|---------------|
| `*AuthError` | API 密钥缺失、格式错误、未知或被撤销 |
| `*ProRequiredError` | 在免费账户上使用了 Pro 专属选项 |
| `*SessionExpiredError` | 24 小时的上传会话窗口已过 |
| `*RateLimitError` | 触发速率限制——当服务器提供时携带 `RetryAfter` |
| `*MaintenanceError` | snapWONDERS 因维护而暂时不可用——携带 `RetryAfter` |
| `*JobFailedError` | 任务以 `failed` 状态结束——携带服务器的 `Reason` |
| `*TusUploadError` | 可恢复上传步骤失败 |
| `*NetworkError` | 无法连接到 API |
| `*APIError` | 任何其他非 2xx 响应——携带 `StatusCode` 和 `Body` |
# 运行测试
```
go test ./... # offline unit tests — no API key required
```
# 文档
有用的文档可以在以下位置找到：
* 交互式 Swagger UI 和完整的 endpoint 参考：[snapWONDERS API](https://snapwonders.com/api)
* 引导式的分步集成演练：[snapWONDERS 开发者](https://snapwonders.com/developers)
# 联系方式
## 安全问题
如果您发现了任何安全问题，请通过 [联系 snapWONDERS](https://snapwonders.com/contact) 与我们取得联系，并将主题设置为 **"SECURITY CONCERNS"**，同时提供相关问题的详细信息。如果您希望通过 Tor 或 I2P 联系，可以通过 Tor 或 I2P 门户访问 snapWONDERS。有关暗网链接，请访问 [安全浏览](https://snapwonders.com/browsing-safely)。
## FAQ 和问题
您的问题可能已经在 [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 密钥，并受 [snapWONDERS 服务条款](https://snapwonders.com/terms) 约束。