SauceNAO JSON API 格式：请求与响应完整说明

SauceNAO 的 JSON API 是脚本接入的核心通道——一个 HTTP GET / POST 请求就能拿到结构化的搜索结果。接口非常简单，几个参数就能跑通。

接口地址

GET https://saucenao.com/search.php

只有这一个 endpoint——所有搜索都打到 search.php，靠参数区分行为。

关键参数

参数	类型	必需	说明
`output_type`	int	是	返回格式：2 = JSON，1 = HTML，0 = 纯文本
`api_key`	string	是	你的 SauceNAO API Key
`db`	int	否	搜索单个数据库编号；传 999 = 搜所有（默认）
`dbmask`	int	否	位掩码，指定要搜的多个数据库
`dbmaski`	int	否	位掩码，指定要排除的数据库
`url`	string	否	要搜的图片 URL（和本地上传二选一）
`numres`	int	否	返回几条结果（默认 6，最大 999）
`testmode`	int	否	设为 1 时只返回数据库编号，不做实际匹配（调试用）
`hide`	int	否	隐藏特定类别结果：0 = 不隐藏，1~3 = 隐藏不同等级
`frame`	int	否	视频缩略图模式（对普通图片无影响）

db、dbmask、dbmaski 三个互斥——一次请求只能用其中一个。

本地图片上传

不传 url 参数，改用 POST multipart 方式上传文件：

POST https://saucenao.com/search.php?output_type=2&api_key=YOUR_KEY
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="file"; filename="search.jpg"
Content-Type: image/jpeg

[二进制图片数据]
--boundary--

Python requests 库示例：

with open("search.jpg", "rb") as f:
    resp = requests.post(
        "https://saucenao.com/search.php",
        params={"output_type": 2, "api_key": API_KEY},
        files={"file": f},
    )

返回的 JSON 结构

{
  "header": {
    "user_id": "xxx",
    "account_type": "Free",
    "short_limit": 8,
    "long_limit": 200,
    "short_remaining": 7,
    "long_remaining": 199,
    "status": 0,
    "message": ""
  },
  "results": [
    {
      "similarity": 95.2,
      "thumbnail": "https://img.saucenao.com/...",
      "index_id": 3,
      "index_name": "Pixiv Images",
      "title": "插画标题",
      "author": "作者名",
      "url": "https://www.pixiv.net/artworks/12345678",
      "member_name": "上传者",
      "pixiv_id": 12345678,
      "source": "https://...",
      "character": "角色名",
      "characters": ["角色A", "角色B"]
    }
  ]
}

header 里最该关注的字段

short_remaining：接下来 30 秒窗口内还能发几次请求——每次调用后检查这个值，0 就等 30 秒。
long_remaining：24 小时窗口内剩余请求数——0 就等明天或升级账户。
status：0 = 成功，非 0 = 有错误（配合 message 字段看原因）。

常见错误状态

status	含义	处理
0	成功	正常解析 results
-1	限流（too many requests）	等 short_remaining 恢复或等一天
-2	API Key 无效	检查 Key 有没有拼错、有没有漏传
-3	图片处理失败	图片格式 / 大小有问题，换一张试试
其他	服务器内部错误	稍后重试

output_type 三种格式

值	返回内容	适用场景
0	纯文本	脚本里简单 grep 一下就行，但信息少
1	HTML	拿不到 JSON 时的备选，可以 parse HTML
2	JSON	首选——结构化、信息全、最容易处理

写脚本时永远用 output_type=2，别浪费时间 parse HTML 或纯文本。