필터링

필터링은 **/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"으로 거부됩니다. 수정될 때까지 page와 숫자 필터는 POST JSON으로 보내세요.

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

제공업체가 충족할 수 없는 필터에 어떤 일이 일어나는지는 제공업체를 고정했는지 여부에 따라 다릅니다.

고정 안 함(기본값) — 건너뛰고 진행

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를 보내세요. 고정된 제공업체가 필터를 충족할 수 없으면 요청은 이유를 명시하는 message와 함께 **422**로 실패합니다 — 절대 조용히 삭제되지 않습니다.

# 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"로 필터링하면 거기서 0개의 행이 반환됩니다 — 저장된 전체 문자열이 필요합니다. (이것은 알려진 v1의 거친 부분입니다.)

• censored는 소스마다 다른 것을 의미합니다. missav에는 문자 그대로의 「censored/uncensored」 플래그가 없습니다; API는 censored → 주류 모자이크 작품, uncensored → 그 외 모든 것(Caribbeancom, 10musume, Tokyo-Hot, 1pondo, FC2, 무검열 유출 등)으로 매핑합니다.

• javdatabase 경로는 슬러그화됩니다. maker: "S1 NO.1 STYLE"은 자동으로 s1-no-1-style 스튜디오 아카이브가 됩니다 — 사람이 읽을 수 있는 이름을 전달하면 슬러그가 대신 생성됩니다.

값이 일치하지 않으면 해당 제공업체로부터 더 적은 행 또는 행을 받지 못할 뿐입니다(그리고 고정하지 않은 경우 워터폴이 계속 진행됩니다). 아무 오류도 발생하지 않습니다 — 빈 일치는 오류가 아닙니다.

6. 응답 형태

본문은 승자 제공업체의 결과 집합입니다:

{
  "q": "ema kisaki",        // your query, echoed
  "source": "fanza",        // which provider answered
  "count": 10,              // 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 — 필드 필터 없음, 하지만 최고의 정렬 + 가용성.

• 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만 결합. 검열본 + 무검열. 영어 값, 자동 슬러그화. 페이지 매김 지원.
• 재생 시간/출시일 범위 없음, 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 사례는 오류를 참조하세요.