筛选

筛选仅适用于 /query（多结果搜索）。单结果的 /movie 和 /random 端点不接受筛选条件。

1. 快速开始

每个 /query 请求在搜索词 q 之外还接受四个可选输入：filter、sort、page 和 num（每页数量）。同时适用于 GET（查询字符串）和 POST（JSON 请求体）。

KEY="jvi_..."   # your API key, sent as the x-javinfo-key header

# POST — genre + runtime filter, newest first
curl -s -X POST https://api.javinfo.dev/query \
  -H "x-javinfo-key: $KEY" -H 'content-type: application/json' \
  -d '{
        "q": "ema kisaki",
        "filter": { "genre": "Big Tits", "runtimeMin": 120 },
        "sort": "release",
        "page": 1
      }'

# GET — same thing, flattened into query params
curl -s "https://api.javinfo.dev/query?q=ema%20kisaki&filter[genre]=Big%20Tits&filter[runtimeMin]=120&sort=release" \
  -H "x-javinfo-key: $KEY"

当存在筛选条件时，q 是可选的 — 你可以在没有关键词的情况下浏览整个分类：

# All "creampie" titles, no search term
curl -s -X POST https://api.javinfo.dev/query \
  -H "x-javinfo-key: $KEY" -H 'content-type: application/json' \
  -d '{ "filter": { "genre": "creampie" } }'

既没有 q 也没有筛选条件的请求会被以 400 拒绝 （"provide a search query or at least one filter"）。

无论使用何种筛选条件，每次成功的 /query 调用固定收费 200 单位。 未返回结果（404）或出错的请求是免费的。

2. 输入参数

filter

一个对象。所有字段均为可选。只需设置你需要的字段。

sort

以下之一：relevance（默认）、release、update、rating、views。

• relevance — 文本匹配相关度（省略时的默认值）。
• release — 按发布日期最新优先。
• update — 最近添加/更新优先。
• rating — 评分最高优先。
• views — 保留字段；目前没有提供商支持（始终被拒绝）。

page

从 1 开始的整数。省略即为第 1 页。每页数量由 num 设置。

num

每页返回的结果数量。整数，默认 10，最大 50（超出的值会被截断，而非拒绝；num < 1 → 400）。各提供商尽力而为：javdatabase 仅在站点固定的归档页大小范围内遵循该值（会限制返回的行数）；missav 以其搜索数量为上限。page 偏移量根据 num 计算（num=10 时的第 2 页会跳过前 10 条）。

GET 数字强制转换。 num 会从查询字符串中被强制转换为数字，但 page 和嵌套的 filter[...] 数字目前还不会 — 在 GET 上它们会以 400 "expected number, received string" 被拒绝。在此问题修复之前，请通过 POST JSON 发送 page 和数字类筛选条件。

3. 提供商能力矩阵

/query 会搜索多个提供商。并非每个提供商都支持每一种筛选条件。 这是整个系统的关键 — 在构建查询前请务必阅读。

提供商（及其 ID）：query:fanza、query:dmm（DMM + FANZA 两个店面）、query:missav、query:javdb、 query:javdatabase。

图例：✅ 支持 · ❌ 不支持 · ≈ 接受但表现为默认行为。

注意事项：

• fanza/dmm 仅限有码 — uncensored 筛选条件会将它们排除。
• javdb 没有按字段的筛选（genre/actress 等）。它只提供粗粒度的有码/无码 分类、availability 和丰富的排序。向 javdb 请求任何具名维度都会将其排除。
• javdatabase 仅能组合 genre + maker（类型 ∩ 工作室的归档）； 任何其他组合都会将其排除。
• missav 忽略 page — 它始终返回匹配结果的第一页。
• missav 忽略 sort — 结果仅按相关度排序。

4. 提供商选择的工作方式（瀑布流）

/query 会按顺序尝试各提供商，第一个有效结果胜出：

FANZA → DMM → missav → javdb → javdatabase

提供商无法满足的筛选条件会如何处理，取决于你是否**固定（pin）**了提供商。

未固定（默认）— 跳过并前进

如果你不发送 providers，则每个已注册的提供商都是候选者。任何无法完全满足你 筛选条件的提供商都会被静默跳过，瀑布流会前进到下一个。你会从第一个能够 满足整个请求的提供商获得结果。

# sort=rating is javdb-only → fanza/dmm/missav/javdatabase are skipped,
# javdb answers.
curl -s -X POST https://api.javinfo.dev/query \
  -H "x-javinfo-key: $KEY" -H 'content-type: application/json' \
  -d '{ "q": "ABP", "sort": "rating" }'
# → { "source": "javdb", ... }

如果没有提供商能满足请求，你会收到 422 及说明原因的消息。

固定 — 硬性错误

发送 providers 以强制使用特定提供商（或提供商集合）。如果被固定的提供商无法 满足筛选条件，请求会以 422 失败，并在 message 中指出原因 — 它绝不会被静默丢弃。

# Pin javdb, ask for a genre it can't filter → 422
curl -s -X POST https://api.javinfo.dev/query \
  -H "x-javinfo-key: $KEY" -H 'content-type: application/json' \
  -d '{ "q": "x", "providers": ["query:javdb"], "filter": { "genre": "creampie" } }'
# → 422 { "message": "does not support filter \"genre\"" }

# Pin fanza, ask for uncensored → 422
#   → { "message": "does not support uncensored content" }

providers 接受逗号分隔的列表或数组，可带或不带 query: 前缀： "providers": ["fanza","missav"] 或 "providers": "javdb"。

5. 值会被原样透传（重要）

这是一种 v1 透传设计：你在筛选值中填入的任何内容都会原样发送到该 提供商自己的后端。不存在共享的分类体系，也不存在跨提供商的模糊匹配。在某个 提供商上有效的值，在另一个提供商上往往无法匹配，因为每个数据源存储元数据 的方式各不相同。

你必须为以下后果做好规划：

• 类型因提供商而异。

  • fanza/dmm 和 javdatabase 使用英文类型名称（"Big Tits"、 "creampie"）。
  • missav 的类型是日文（"巨乳"、"フィスト"）。英文类型在 missav 上不会返回任何结果。

• 名称必须完全匹配。 筛选是精确匹配，而非子串匹配。在 DMM + FANZA 索引中， 女优的别名会被写入其名称，例如 "Ema Kisaki (HARUKI, Haruki Kato)"。 在那里筛选 actress: "Ema Kisaki" 会返回零行 — 你需要完整的存储 字符串。（这是 v1 已知的粗糙之处。）

• censored 在不同数据源上含义不同。 在 missav 上没有字面意义的 "censored/uncensored" 标志；API 会将 censored 映射为主流马赛克作品， 将 uncensored 映射为其他所有内容（Caribbeancom、10musume、Tokyo-Hot、 1pondo、FC2、无码流出等）。

• javdatabase 的路径会被转为 slug。 maker: "S1 NO.1 STYLE" 会自动 变成 s1-no-1-style 工作室归档 — 传入人类可读的名称即可，slug 会自动 为你生成。

如果某个值不匹配，你只会从该提供商获得更少/没有结果（并且，如果未固定，瀑布流 会继续前进）。不会有任何错误 — 空匹配不是错误。

6. 响应结构

响应体是获胜提供商返回的结果集：

{
  "q": "ema kisaki",        // your query, echoed
  "source": "fanza",        // which provider answered
  "count": 10,              // results this page (default 10, set by num)
  "results": [
    {
      "id": "118abp00999",          // stable id (content id or dvd id)
      "dvdId": "ABP-999",
      "title": "…",
      "cover": "https://…/…ps.jpg",
      "releaseDate": "2019-01-04",
      "extra": {                    // provider-specific, keys vary by source
        "runtimeMins": 130,
        "maker": "…",
        "categories": ["Big Tits", "…"],
        "actresses": [{ "name": "…", "image": "https://…|null" }],
        "duration": 7800,           // missav (seconds)
        "genres": ["巨乳"],          // missav
        "studio": "…", "url": "…"   // javdatabase
        // …
      }
    }
  ]
}

extra 是一个超集 — 只包含应答提供商实际产生的键。核心字段（id、dvdId、 title、cover、releaseDate）在所有提供商之间保持一致。

响应头携带元数据：X-Response-Time-Ms、X-Balance-Remaining。

7. 各提供商速查表

fanza / dmm（DMM + FANZA 店面）— 最丰富的结构化筛选。

• 所有具名维度，可自由组合。英文类型/名称值。
• runtimeMin/runtimeMax 以分钟为单位。sort: release。支持分页。
• 仅有码目录 — 无 uncensored、无 availability、无发布日期范围。

# Big-tits titles over 120 min, newest first
-d '{ "filter": { "genre": "Big Tits", "runtimeMin": 120 }, "sort": "release" }'

missav — 最广的筛选面，但仅按相关度排序。

• 所有具名维度（类型为日文）、时长和发布日期范围、censored 双向。
• 无 sort（仅相关度）、无真正的分页（仅第 1 页）、无 availability。

# Uncensored titles matching "caribbean"
-d '{ "q": "caribbean", "filter": { "censored": "uncensored" } }'
# Japanese genre browse
-d '{ "q": "SSIS", "filter": { "genre": "巨乳" } }'

javdb — 无字段筛选，但拥有最佳的排序 + availability。

• 仅 censored（双向）、availability 和 sort（relevance/release/update/rating）。
• 支持分页。无 genre/actress/maker 等。

# Playable, highest rated
-d '{ "q": "ABP", "filter": { "availability": "playable" }, "sort": "rating" }'

javdatabase — 按单一维度浏览归档（或 genre ∩ maker）。

• genre、actress、maker、series、director；仅 genre+maker 可组合。有码 + 无码。英文值，自动转为 slug。支持分页。
• 无时长/发布日期范围，无 label/actor，无真正的排序（最新优先）。

# Creampie titles from S1
-d '{ "filter": { "genre": "creampie", "maker": "S1 NO.1 STYLE" } }'

8. 哪些是不可能的（v1）

• 跨提供商的值规范化。 没有统一的类型/女优词汇表 — 你必须使用每个提供商 的方言（英文 vs 日文，精确字符串）。
• sort: views — 保留字段，没有提供商实现它。
• 单一维度的多值。 每个字段只能有一个值（不支持 genre: ["a","b"]）。
• 超出对应提供商的范围。 时长范围仅限 fanza/dmm/missav；发布日期范围仅限 missav。
• 在 javdb 之外的任何地方使用 availability。
• 在 javdb（不支持）或 javdatabase（仅 genre+maker）上组合任意筛选条件。
• 在 missav 上分页/排序。
• 筛选 /movie 或 /random。

当某个组合不可能时：已固定 → 422 并附带原因；未固定 → 跳过该提供商并尝试 下一个。

下一步

• 浏览完整的 API 参考 — /query 操作列出了每个筛选参数，并附带在线调试工具。
• 参阅错误处理了解 400 和 422 的情况。