API Key 怎么申请和使用：从零到能调通的最短路径

想在代码里调用 SauceNAO？先注册账户拿到 API Key，然后按正确格式发起请求——整个流程 10 分钟就能跑通。

申请流程

打开 saucenao.com/user.php → 如果没账户先 Register。
登录后，在账户设置页（通常在 user.php 首页或子菜单里）找到 "API Key" 或 "My API Key" 区域。
页面会显示一串字母数字混合的字符串——这就是你的 API Key。
复制保存好，不要硬编码到公开仓库、不要分享到公共论坛。

API Key 怎么用

SauceNAO 的 JSON API 格式：

GET https://saucenao.com/search.php?output_type=2&api_key=<YOUR_KEY>&db=999&url=<IMAGE_URL>

关键参数：

参数	值	说明
`output_type`	`2`	固定值，表示返回 JSON 格式（1 = HTML，0 = 纯文本）
`api_key`	你的 Key	必须传，不传 API 会拒绝
`db`	`999`	搜所有数据库（ALL）；也可以传单个编号
`url`	图片 URL	要搜的图片在线地址

如果要上传本地图片而不是传 URL，用 POST multipart 方式把图片文件发给同一个 endpoint。

一个最小可运行的 Python 示例

import requests

API_KEY = "your_api_key_here"
IMAGE_URL = "https://example.com/your_image.jpg"

resp = requests.get(
    "https://saucenao.com/search.php",
    params={
        "output_type": 2,
        "api_key": API_KEY,
        "db": 999,
        "url": IMAGE_URL,
    },
)

data = resp.json()
results = data.get("results", [])

for r in results[:3]:  # 只看前三条
    print(f"相似度: {r['similarity']}%")
    print(f"数据库: {r['index_name']}")
    print(f"标题: {r.get('title', 'N/A')}")
    print(f"链接: {r.get('url', 'N/A')}")
    print("---")

额度耗尽时会发生什么

免费账户额度用完（8 次/30 秒、200 次/24 小时）时，API 会返回限流错误。不会封你的 Key，等额度恢复就好了。

第三方库（比如 pysaucenao）会在返回结果里包含剩余额度信息：

results.short_remaining  # 30 秒窗口内剩余请求数
results.long_remaining   # 24 小时内剩余请求数

建议你的代码里每次调用后检查这两个值——short_remaining == 0 就等 30 秒再发下一次，long_remaining == 0 就等明天。

Key 泄露了怎么办

SauceNAO 支持随时重新生成 API Key——登录账户设置页找到重置按钮，重新生成后旧 Key 立即失效。记得同步更新你代码里硬编码的 Key。

经验：把 API Key 放进环境变量里读（os.environ.get("SAUCENAO_API_KEY")），不要直接写在源代码里，这样即使代码进了公开仓库也不会泄露。