Python 调用 SauceNAO API：三个主流第三方库的对比

SauceNAO 官方不维护 SDK，但社区已经有好几个 Python 第三方库帮你封装了 API 调用、限流检查、dbmask 位运算等脏活——直接拿来用就行。

三个主流库对比

安装

pip install pysaucenao
# 或
pip install saucenao-api
# 或
pip install SauceNAO

pysaucenao 示例（推荐）

异步调用，最干净的接口：

import asyncio
from pysaucenao import SauceNao

async def search():
    saucenao = SauceNao(api_key="your_api_key")

    # 搜 URL
    results = await saucenao.search("https://example.com/image.jpg")

    # 或搜本地文件
    # results = await saucenao.search_local("C:/path/to/image.jpg")

    print(f"剩余额度: 30s={results.short_remaining}, 24h={results.long_remaining}")

    for r in results[:3]:
        print(f"相似度: {r.similarity}%")
        print(f"数据库: {r.index_name}")
        print(f"链接: {r.url}")
        print("---")

asyncio.run(search())

saucenao-api 示例（同步）

基于 pysaucenao 的同步包装，适合不想搞 asyncio 的场景：

from saucenao_api import SauceNao

sauce = SauceNao(api_key="your_api_key", db=999, numres=10)

results = sauce.search("https://example.com/image.jpg")

print(f"剩余额度: 30s={results.short_remaining}, 24h={results.long_remaining}")

for r in results[:3]:
    print(f"相似度: {r.similarity}%")
    print(f"数据库: {r.index_name}")
    print(f"作者: {r.author}")
    print(f"链接: {r.url}")

内置的限流保护

三个库都会在每次请求后检查剩余额度——当 short_remaining 降为 0 时自动等待 30 秒再发下一次，long_remaining 为 0 时抛异常。你不用自己写重试逻辑。

dbmask 的处理

库会帮你封装好位运算：

# pysaucenao 用 DB 枚举
from pysaucenao import SauceNao, DB
sauce = SauceNao(api_key=KEY, databases=[DB.PIXIV, DB.DANBOORU, DB.TWITTER])

# saucenao-api 用常量
from saucenao_api import SauceNao, DB
sauce = SauceNao(api_key=KEY, db=DB.ALL)

具体枚举值和常量参考各库文档，版本更新可能会新增数据库常量。

用哪个

• 新项目 / 异步项目 → pysaucenao（异步 + 接口最干净）
• 同步脚本 / 小工具 → saucenao-api（同步调用、上手快）
• 本地图片仓库批量处理 → SauceNAO（高级封装、目录扫描 + 分类整理）

三个库底层都走同一个 SauceNAO API，结果上没区别——挑哪个纯看你项目的技术栈和偏好。