API 文档
DHTSearch的公开只读 API:搜索本站基于 DHT 网络实时收录的磁力链接,读取种子文件列表与相似推荐,订阅 RSS,或提交游客举报。接口返回 JSON(RSS 除外),支持跨域(Access-Control-Allow-Origin: *)。 下文地址以 https://api.example.com 代指部署的 API 服务地址,替换为实际地址即可。机器可读的 OpenAPI 3 描述文件在 /openapi.yaml。
鉴权与限流
是否需要令牌由部署方设置(PUBLIC_API_REQUIRE_TOKEN,默认关)。关闭时三个门控接口可匿名调用;开启后必须携带令牌。无论开关如何,令牌门控只作用于 /api/search、/api/stats、/api/trending 三个接口;文件列表、相似推荐、RSS、站点信息、健康检查与举报接口不要求令牌。
获取令牌:由站点管理员在管理端「API 令牌」页创建。令牌形如 dht_ 加 64 位十六进制字符(共 68 字符),明文只在创建时显示一次,之后只能看前缀。每个令牌有独立的每分钟配额(创建时默认 600 次/分钟,管理员可逐个修改,0 = 不限)。
携带方式(二选一,不支持查询参数传令牌):
Authorization: Bearer <redacted> # 或 X-API-Key: dht_xxxxxxxx...
鉴权失败按原因区分(响应体均为 {"error": "..."}):
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 401 | 未带令牌 | api token required | 门控开启且请求未携带令牌;同时返回 WWW-Authenticate 头 |
| 401 | 令牌无效 | invalid api token | 令牌不存在或已删除 |
| 403 | 令牌被禁用 | api token disabled | 令牌存在但已被管理员禁用 |
| 429 | 令牌配额用尽 | api token rate limit exceeded | 超过该令牌的每分钟配额;响应带 Retry-After |
| 503 | 公开 API 被关闭 | public api disabled | 部署方关闭了公开 API 总开关,三个门控接口对所有人返回 503 |
全局限流:除令牌配额外,所有公开接口共享按客户端 IP 的限流(默认每秒 3 次、突发 30 次,部署方可调),超限返回 429 rate limit exceeded 并带 Retry-After: 1。带令牌不豁免全局限流。搜索类接口在服务器饱和时可能返回 503 server busy 或 search timed out,稍后重试即可。
接口参考
/api/search受令牌门控关键词搜索。无关键词时为浏览最新收录。没有独立的种子详情接口——搜索结果条目即完整记录(名称、大小、文件预览、磁力链接、做种数据),文件全量列表与相似推荐见下方两个接口。
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| q | string | (空) | 关键词,最长 200 字符(超出截断);空 = 浏览最新 |
| page | int | 1 | 页码,从 1 起;可达深度上限为偏移 10000 条,超出自动钳制 |
| page_size | int | 20 | 每页条数,最大 100 |
| category | string | (全部) | video / audio / image / doc / software / archive / other;非法值 400 |
| sort | string | relevance | relevance(相关性)/ newest(最新)/ size(体积)/ seeders(做种数);非法值 400 |
| hide_dead | string | 0 | 1 或 true 时隐藏 health=likely_dead 的结果;其他取值 400 |
curl "https://api.example.com/api/search?q=shawshank&sort=seeders&page_size=2"
{
"total": 2,
"page": 1,
"page_size": 2,
"category": "",
"sort": "seeders",
"hide_dead": false,
"categories": { "video": 2, "audio": 0, "image": 0, "doc": 0,
"software": 0, "archive": 0, "other": 0 },
"trackers": ["udp://tracker.opentrackr.org:1337/announce", "..."],
"results": [
{
"info_hash": "4cd02e56c0237fcd5190dc9e9430592040431aaa",
"name": "The Shawshank Redemption 1994 2160p UHD BluRay REMUX",
"total_size": 58000000000,
"file_count": 1,
"files": [
{ "path": "The.Shawshank.Redemption.1994.2160p.UHD.BluRay.REMUX.mkv",
"size": 58000000000 }
],
"magnet": "magnet:?xt=urn:btih:4cd0...&dn=...&tr=...(已截短)",
"created_at": 1795236227,
"category": "video",
"seeders": 41, "leechers": 9, "completed": 233,
"scraped_at": 1795235327, "zero_since": 0, "zero_count": 0,
"health": "alive"
}
]
}结果条目字段:files 只内嵌前 100 个文件作预览(全量走文件列表接口);alias 为订阅源发布的别名标题,非空时才出现;seeders / leechers / completed / scraped_at / zero_since / zero_count 是最近一次 tracker 刮削快照,从未被刮削过的种子这些字段为 null(与真实的 0 严格区分);health 是由快照推导的健康度: alive(有做种)/ no_seed(无做种但有人下载)/ likely_dead(连续多次全零、跨度 ≥48 小时)/ suspect(全零但证据不足)/ unknown(无刮削数据)。created_at 为收录时间(Unix 秒)。
/api/torrents/{hash}/files无需令牌分页读取一个种子的完整文件列表。
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| page | int | 1 | 页码,从 1 起 |
| page_size | int | 100 | 每页条数,最大 500 |
| q | string | (空) | 按文件路径子串过滤;total 统计过滤后的条数 |
curl "https://api.example.com/api/torrents/0f09bec639b50b57e0c817048a1eef0bfda69e2e/files?page=1&page_size=2"
{
"info_hash": "0f09bec639b50b57e0c817048a1eef0bfda69e2e",
"total": 3,
"total_all": 3,
"page": 1,
"page_size": 2,
"total_pages": 2,
"files": [
{ "path": "The.Shawshank.Redemption.1994.1080p.BluRay.x264.mkv", "size": 2140000000 },
{ "path": "The.Shawshank.Redemption.1994.1080p.BluRay.x264.srt", "size": 103456 }
]
}total_all 是该种子的文件总数(未过滤);哈希不存在返回 404。
/api/torrents/{hash}/similar无需令牌与指定种子名称相近的推荐,结果条目结构与搜索一致,但 files 为 null。
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| limit | int | 6 | 返回条数,钳制在 1..12 |
curl "https://api.example.com/api/torrents/0f09bec639b50b57e0c817048a1eef0bfda69e2e/similar"
{
"results": [
{
"info_hash": "4cd02e56c0237fcd5190dc9e9430592040431aaa",
"name": "The Shawshank Redemption 1994 2160p UHD BluRay REMUX",
"total_size": 58000000000,
"file_count": 1,
"files": null,
"magnet": "magnet:?xt=urn:btih:4cd0...&dn=...&tr=...(已截短)",
"created_at": 1795236227,
"category": "video",
"seeders": 41, "leechers": 9, "completed": 233,
"scraped_at": 1795235327, "zero_since": 0, "zero_count": 0,
"health": "alive"
}
]
}哈希不存在返回 404。
/api/stats受令牌门控索引与管线统计(服务端缓存约 10 秒)。顶层为累计计数:收录总数、已发现、已抓取与各过滤类别计数;fetch 是元数据抓取结果(含按来源 by_source 拆分与实时队列深度);moderation 是审核计数。部署启用了对应子系统时还会出现 crawler / scraper / feeds 段。
curl "https://api.example.com/api/stats"
{
"torrents": 3,
"seen": 0, "fetched": 0,
"adult_filtered": 0, "spam_filtered": 0,
"size_filtered": 0, "blocked_filtered": 0,
"fetch": {
"fetched": 0, "timed_out": 0, "failed": 0, "prescreen_dropped": 0,
"skipped_stored": 0, "skipped_backoff": 0,
"peer_hint_items": 0, "peer_hint_fetched": 0,
"by_source": [
{ "source": "dht", "attempts": 0, "fetched": 0, "timed_out": 0,
"failed": 0, "prescreen_dropped": 0, "success_rate": 0 }
],
"queue_depth": 0, "backend": "anacrolix"
},
"moderation": { "reviewed": 0, "adult_removed": 0, "spam_removed": 0,
"errors": 0, "pending": 3, "blocked": 0 }
}/api/trending受令牌门控首页榜单数据:豆瓣热门影视标题(英文名为主,日韩剧为中文名)与更新时间(Unix 秒)。
curl "https://api.example.com/api/trending"
{
"movies": ["The Odyssey", "..."],
"tv": ["VisionQuest", "..."],
"tv_jp": ["白色巨塔", "..."],
"tv_kr": ["百日谎言", "..."],
"updated_at": 1795200000
}/api/site无需令牌站点展示配置:名称、主题色与默认外观。
curl "https://api.example.com/api/site"
{ "name": "DHTSearch", "theme_color": "teal", "theme_appearance": "system" }/api/healthz无需令牌健康检查,不受任何门控与限流影响。
curl "https://api.example.com/api/healthz"
# { "ok": true }/rss无需令牌RSS 2.0 订阅:某关键词的最新收录(最多 50 条,按最新排序),无 q 时为全站最新。每条的链接即磁力链接, guid 为 infohash。
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| q | string | (空) | 关键词,最长 200 字符 |
| category | string | (全部) | 同 /api/search 的分类枚举;非法值 400 |
curl "https://api.example.com/rss?q=ubuntu"
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0"><channel>
<title>DHTSearch 搜索:ubuntu</title>
<link>https://api.example.com/</link>
<description>基于 DHT 网络实时收录的磁力链接,已过滤成人内容与垃圾信息。</description>
<item>
<title>Ubuntu 24.04 LTS Desktop amd64</title>
<link>magnet:?xt=urn:btih:a99dfe...&dn=...&tr=...(已截短)</link>
<guid>a99dfe6400d029b848d18a9b6ff1611af03aadf8</guid>
<pubDate>Fri, 21 Nov 2026 05:23:47 +0000</pubDate>
<description>大小 5880.00 MB · 1 个文件</description>
<category>software</category>
</item>
</channel></rss>/api/report无需令牌游客举报一个已收录种子,进入管理员的举报队列。同一客户端对同一种子的举报有频率限制(约 3 次/分钟),超限 429。
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| info_hash | string | (必填) | 40 位十六进制 infohash |
| reason | string | (必填) | adult(成人内容)/ spam(垃圾信息)/ infringement(侵权)/ other(其他) |
| note | string | (空) | 补充说明,最长 500 字符 |
curl -X POST "https://api.example.com/api/report" \
-H "Content-Type: application/json" \
-d '{"info_hash":"0f09bec639b50b57e0c817048a1eef0bfda69e2e","reason":"spam","note":"重复垃圾"}'
# 201 { "ok": true }错误模型
所有 JSON 错误响应体统一为 {"error": "消息"},状态码与常见消息如下:
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 400 | 参数错误 | invalid category / invalid sort / invalid hide_dead / invalid info_hash / invalid reason / bad request | 参数不合法,按消息修正即可 |
| 401 | 未鉴权 | api token required / invalid api token | 见「鉴权与限流」 |
| 403 | 令牌被禁用 | api token disabled | 联系站点管理员 |
| 404 | 不存在 | not found | 哈希对应的种子不存在 |
| 429 | 限流 | rate limit exceeded / api token rate limit exceeded / too many reports for this torrent | 按 Retry-After 等待后重试 |
| 500 | 服务器错误 | search failed / stats failed / report failed / feed failed | 服务端内部错误 |
| 503 | 暂不可用 | public api disabled / server busy / search timed out | 公开 API 被关、服务器饱和或查询超时,稍后重试 |