Skip to content
leegunwooooPublic

Repository files navigation

nikke-api

Warning

저작권 고지 — 반드시 읽어주세요

본 프로젝트는 비공식·비상업적 팬 프로젝트입니다. 이 API를 통해 제공되는 모든 게임 데이터, 캐릭터 정보, 이미지, 텍스트 등 콘텐츠의 저작권 및 지적재산권은 © SHIFT UP / Level Infinite에 있습니다.

본 프로젝트는 SHIFT UP 및 Level Infinite와 아무런 관련이 없으며, 공인·후원·승인받은 서비스가 아닙니다. 기본 데이터는 공개된 BlablaLink CDN 리소스를 참조합니다. 다음 데이터는 별도 공개 자료에서 가져옵니다.

  • content/favorite-stories/의 애장품 스토리: 공개 영상 화면에서 옮겨 적어 이 저장소에 보관합니다.
  • library 카테고리의 스토리: 커뮤니티 기록 Nikke Forbidden Library에서 가져와 API 형식으로 변환해 제공합니다. 단, content/library-stories/의 대본은 공개 영상 화면에서 옮겨 적어 이 저장소에 보관합니다.
  • 버스트 컷신: ArtHub의 공개 Spine 리소스를 참조합니다. 검증된 URL 메타데이터를 보관하며, 뷰어는 배경과 캐릭터를 하나의 컷신으로 재생합니다. 원본 게임 파일은 저장소에 포함하지 않고, 뷰어 요청 시 목록에 있는 파일만 중계·캐시합니다.

상업적 이용을 금지하며, 권리자의 요청이 있을 경우 즉시 서비스를 중단합니다.


소개

승리의 여신: 니케(GODDESS OF VICTORY: NIKKE) 게임 데이터를 제공하는 REST API입니다.

BlablaLink(공식 위키 도구)의 CDN 데이터를 매일 동기화합니다. 데이터 변경이 감지될 때만 자동 배포되어 항상 최신 상태를 유지합니다.

전체가 Cloudflare 위에서 동작합니다 — Cloudflare Worker가 API를 직접 서빙하고, 데이터는 nikke-api-data Pages 프로젝트의 정적 파일로 읽습니다(빌드 산출물은 백업 겸 로컬 개발용으로 data-latest 릴리즈 artifact로도 올립니다). GitHub Actions의 일일 리프레시는 sync+build 후 변경분을 Pages로 배포해 즉시 반영합니다.

라이브 주소: https://nikke-api.pages.dev 문서 사이트: https://nikke-api-docs.pages.dev

  • 4개 언어 지원: 한국어 ko / 영어 en / 일본어 ja / 중국어 번체 zh-TW
  • 이미지·음성은 BlablaLink CDN URL로 제공 (직접 재호스팅하지 않음)
  • 스킬 설명은 최대 레벨 기준으로 렌더링된 텍스트 제공 (원본 템플릿·레벨별 수치도 포함)

제공 데이터

캐릭터 — 206종

항목 내용
기본 정보 ID, 이름(4개 언어), 레어도, 클래스, 버스트 스텝, 기업, 속성, 무기/공격 타입
이미지 아이콘 / 미디엄 / 전신 일러스트 (CDN URL), 등급·클래스·속성 아이콘, 스킬 아이콘
버스트 컷신 burstCutscene: 외형별 Spine 리소스, playback 합성 정보, 외형별 버스트 대사·음성(voice)과 배경·캐릭터·음성을 함께 재생하는 뷰어. 코스튬 전용 컷신이 없으면 기본 외형으로 대체하고, 캐릭터 미수록은 null
코스튬 스킨 캐릭터별 코스튬 목록 + 각 코스튬 이미지 세트. /api/costumes/:id는 그 코스튬 전용 대사+음성(voices)도 함께 제공
스킬 슬롯별(skill1/skill2/burst) 이름·설명(최대 레벨 렌더링) + 원본 템플릿·레벨별 수치, 버스트 쿨타임
스탯 레벨별 공격력/방어력/HP 배열 (Lv1~최대)
전투 정보 치명타 확률·피해, 사거리 보정, 버스트 지연·지속시간 등
무기 스펙 캐릭터별 무기 메카닉 (details.shot) — 샷 대미지·차지 시간·연사·재장전·명중률 서클·샷당 버스트 게이지·타겟 우선순위
돌파·코어 보너스 한계돌파 1단계당 + 코어 강화 1단계당 스탯 보너스 (details.statEnhance) — 레어도별 공통 테이블
스킬 강화 비용 스킬1·스킬2·버스트의 레벨별(210) 재료 — 스킬/버스트 매뉴얼 IIII, 기업별 코드 매뉴얼 (details.skillCosts)
스토리 정보 배경 스토리(4개 언어), 소속 스쿼드, 성우(CV), 호감도 씬 연결(details.attractiveScenarios[].sceneGroupId → /api/scenes/:groupId), 애장품 스토리 연결(details.favoriteStory), 팀원 목록(캐릭터 이름·이미지로 해석)
보이스 캐릭터 대사 목록 (details.voices) — 로비 터치, 전투 진입·승리, 호감도 대사 등. 대사별 label(종류)·text(대사) 4개 언어 + voice 음성 mp3 ko/en/ja 3종. conditionAttractiveLevel로 해금 조건, costumeIndex로 코스튬별 대사 구분 (66명이 코스튬 전용 대사 보유)

스토리 씬 — 5,342개 (한국어)

메인/이벤트/돌발 스토리 + 호감도(Attractive) 시나리오의 전체 대본. 애장품 스토리 21편도 영상에서 옮긴 대본으로 함께 제공합니다. 게임 데이터에 없는 메신저·유실물·사이드 스토리·서브 퀘스트·이벤트 약 2000편은 library 카테고리에 있습니다. 출처는 Nikke Forbidden Library입니다.

항목 내용
분류 main / event / sudden / attractive / favorite / library 카테고리 + 니케별·이름 검색, 페이지네이션
대본 대사별 화자 코드·이름·텍스트·말풍선 타입
화자 정보 화자 코드·이름 + 아이콘 이미지 URL (NPC 포함)
씬 보이스 풀보이스 챕터·이벤트는 대사별 한국어 음성 mp3 URL 제공, 보이스 없는 라인은 voice: null
호감도 씬 대상 니케·필요 호감도 레벨 + 배경/BGM 리소스 코드

소장품 — 33종

항목 내용
기본 정보 이름·설명(4개 언어), 레어(R/SR/SSR), 무기 타입, 아이콘·프롭 이미지, 소유 니케(character)
레벨별 스탯 atk/def/hp/power/grade + 해당 레벨의 컬렉션·소장품 스킬 레벨
스킬 수집 효과 스킬(collection) + 돌파 슬롯별 전용 스킬(item) — 최대 레벨 렌더링 설명 + 원본 수치

하모니 큐브 — 18종

항목 내용
기본 정보 이름·설명·획득처(4개 언어), 클래스
레벨별 스탯 atk/def/hp/power + 해당 레벨의 스킬 레벨
스킬 큐브 스킬 이름·설명(최대 레벨 렌더링) + 원본 수치

유저 프로필

BlablaLink 공유 링크(https://www.blablalink.com/user?openid=...)로 유저의 프로필을 조회합니다. API 사용자는 링크만 붙이면 되고, 조회는 서버의 계정으로 이뤄집니다.

항목 내용
프로필 (/api/user) 닉네임, 레벨, 대표 아이콘(캐릭터 이름·이미지로 해석), 팀 전투력, 캠페인/타워 진행도(스테이지명으로 해석), 기업별 보유 수, 오버클럭 기록, 대표 스쿼드
전진기지 (/api/user) 인프라 코어, 싱크로 레벨, 리사이클 룸 연구, 메모리얼 수집 수
보유 니케 (/api/user/<blablaid>/nikke) 전투력순 목록 — 니케 이름/이미지, 레벨, 코어·돌파. 필터: id(id·resourceId·nameCode 정확 매칭)·name(전 언어 부분 일치, q는 동일 별칭)·element·class·burst·corporation·weapon·rarity
니케 여러 명 상세 (/api/user/<blablaid>/nikke-builds?names=, 전원은 ?all=1) 쉼표로 구분한 이름이나 id, 최대 50개. 찾지 못한 이름은 notFound, 후보가 여럿이면 ambiguous
니케 상세 (/api/user/<blablaid>/nikke/:nameOrId) 이름(부분 일치) 또는 id로 지정 — /api/nikkes/:id와 같은 방식. 단일 매칭 시 스킬 레벨, 호감도, 착용 코스튬(이름 포함), 장비(부위별 이름·티어·옵션 수치), 큐브·소장품 반환. 복수 매칭 시 목록 반환
GET /api/user/<blablaid>                          # 프로필·전진기지 (또는 ?blablaid=)
GET /api/user/<blablaid>/nikke                    # 보유 목록 (경량)
GET /api/user/<blablaid>/nikke?name=아니스         # 아니스 계열 필터 (목록)
GET /api/user/<blablaid>/nikke?id=201601           # id/nameCode로 필터
GET /api/user/<blablaid>/nikke?element=Iron&burst=III   # 속성·버스트 필터 (도감과 동일)
GET /api/user/<blablaid>/nikke/아니스 : 스타         # 단일 상세 (장비·큐브 등)
GET /api/user/<blablaid>/nikke/아니스               # 부분 일치 → 매칭 목록 반환

<blablaid>는 BlablaLink 공유 링크의 openid 값입니다. 이름에 공백·콜론이 있으면 URL 인코딩이 필요합니다. ?blablaid= 쿼리 형태와 구형 ?openid=·?url=도 그대로 동작합니다.

원본 테이블 — 37종

레벨 테이블, 스테이지/타워 목록, 장비 옵션, 아카이브 등 동기화된 게임 데이터 JSON을 가공 없이 그대로 제공.

엔드포인트

엔드포인트 설명
GET /api/nikkes 캐릭터 목록 — ?q= 이름 검색(전 언어 부분 일치), ?family= 이격 포함 확장 검색, ?element= ?class= ?burst= ?corporation= ?weapon= ?rarity= 필터 (AND 결합), ?limit=/?offset=/?page= 페이지네이션 (미지정 시 전체, 최대 500, limit=0은 400 — count는 잘라내기 전 전체 개수). 공백뿐인 ?q=는 결과 없음
GET /api/nikkes/:id 캐릭터 상세 — 스킬/스탯/배경/CV/보이스 등 details 포함. :id는 캐릭터 ID·resourceId·이름(부분 일치) 모두 가능
GET /api/nikkes/:id/burst 버스트 컷신 리소스·뷰어 링크 — 기본 외형과 각 코스튬. burstCutscene.gif에 미리 렌더된 컷신 GIF(jsDelivr). 정확한 이름 우선, 복수 부분 일치 시 후보 목록
GET /api/nikkes/:id/burst.gif 버스트 컷신 GIF로 302 리다이렉트 — ?skin= 코스튬 선택
GET /api/nikkes/:id/spine 스탠딩·사격·엄폐 Spine 리소스와 burstCutscene — 기본 외형과 각 코스튬. stand.gif/stand.gifs에 미리 렌더된 로비 애니메이션 GIF 링크(jsDelivr)
GET /api/nikkes/:id/spine.gif 로비 애니메이션 GIF로 302 리다이렉트 — ?skin= 코스튬 선택, ?anim= 애니메이션(idle 대기, action 터치 리액션)
GET /api/scenes 씬 목록 — ?category=(main/event/sudden/attractive/favorite/library) ?nikke= ?q= ?limit=/?offset=/?page=
GET /api/scenes/:groupId 씬 대본 — 대사별 화자/아이콘/보이스
GET /api/lines 대사 전문 검색 — ?q=(구두점 무시) 또는 ?speaker= 필수, ?category= ?nikke= ?family= ?limit=(기본 50, 최대 500)/?offset=/?page=
GET /api/nikkes/:id/appearances 캐릭터 등장 씬 — 대사 많은 순, 이벤트별 롤업 포함, ?category=
GET /api/events 스토리 이벤트 목록 — event_* 씬 그룹 묶음, ?q= ?limit=/?offset=/?page=
GET /api/events/:id 이벤트 상세 — 에피소드별 씬 목록
GET /api/events/:id/script 이벤트 전체 대본 — 에피소드 단위 페이지네이션
GET /api/story/route 스토리 감상 순서 — 메인 챕터 사이에 이벤트·호감도를 끼워 넣은 커뮤니티 가이드 순서
GET /api/story/next 다음 볼 스토리 추천 — ?chapter= ?after= ?done= ?required= ?limit=(기본 5, 최대 20, 양의 정수만)
GET /api/stages 캠페인 스테이지 목록 — ?chapter= ?mode= ?q= ?limit=/?offset=/?page=
GET /api/stages/:id 스테이지 상세 — 권장 전투력·시나리오 키
GET /api/costumes 코스튬 목록 — ?q= ?grade= ?nikke= ?limit=/?offset=/?page=
GET /api/costumes/:id 코스튬 상세 — tid 또는 이름(부분 일치), 소유 니케·이미지·storyScenes·voices(그 코스튬 전용 대사+음성) 포함
GET /api/equips 장비 목록 — ?q= ?class= ?rare= ?slot= ?limit=/?offset=/?page=. 기본 스탯·옵션슬롯 확률·재련비용·설명 포함
GET /api/equips/options 장비 옵션 목록 — ?q= ?groupId= ?rank= ?limit=/?page=
GET /api/equips/options/:id 장비 옵션 상세
GET /api/equips/:id 장비 상세
GET /api/avatars 아바타 아이콘 목록 — ?q= ?resourceId= ?orphans= ?limit=/?offset=/?page=
GET /api/avatars/:iconId 아바타 상세 — 소유 캐릭터·아이콘 이미지
GET /api/favorites 소장품 목록 — ?q= ?rare= ?nikke= ?limit=/?offset=/?page=
GET /api/favorites/:id 소장품 상세 — 레벨별 스탯, 컬렉션·전용 스킬
GET /api/cubes 하모니 큐브 목록 — ?q= ?limit=/?offset=/?page=
GET /api/cubes/:id 큐브 상세 — 레벨별 스탯, 큐브 스킬
GET /api/user/<blablaid> 유저 프로필·전진기지 조회 — BlablaLink 공유 ID (?blablaid=도 가능)
GET /api/user/<blablaid>/nikke 유저 보유 니케 목록 — ?id=(id·resourceId·nameCode)·?name=(전 언어 부분 일치, q 동일)·element·class·burst·corporation·weapon·rarity 필터, 경량
GET /api/user/<blablaid>/nikke/<nameOrId> 보유 니케 상세 — <nameOrId>는 이름(부분 일치) 또는 id·resourceId·nameCode. 단일 매칭 시 상세, 복수 매칭 시 목록
GET /api/user/<blablaid>/roster 보유 니케 전원 일괄 — 업스트림 원시 형태(characters·details·stateEffects·outpost), 5개 서버 순회·?area=로 지정. 비공개 시 404 reason=private
GET /api/archives / GET /api/archives/:id 기록실(아카이브) 앨범 계층 — 이벤트·기간·씬 목록, ?type=·?fields=·?lang=
GET /api/relics 유실물(lost relic) 씬 목록 + 컬렉션별 롤업 — ?category=lost_relics|event_lost_relics·?collection=·?q=
GET /api/tables / GET /api/tables/:file 원본 테이블 목록/조회 — 배열 테이블은 ?offset=&limit= 페이지네이션·?fields= 지원
GET /api/meta/filters 사용 가능한 필터 값 목록 (니케·스테이지·코스튬·장비 전부)
GET /api/cdn?path= CDN 리소스 경로 → URL 변환

공통 기능

필드 선택 — ?fields=

응답이 큰 엔드포인트에서 필요한 필드만 골라 받을 수 있습니다. 콤마로 여러 개 지정하고, 점(.)으로 중첩 필드를 파고듭니다.

지원 엔드포인트: /api/nikkes, /api/nikkes/:id, /api/favorites, /api/favorites/:id, /api/scenes, /api/scenes/:groupId, /api/events, /api/events/:id, /api/stages, /api/stages/:id, /api/costumes, /api/costumes/:id, /api/equips, /api/equips/options, /api/equips/options/:id, /api/equips/:id, /api/avatars, /api/avatars/:iconId, /api/cubes, /api/cubes/:id, /api/user/:blablaid/nikke, /api/user/:blablaid/nikke/:nameOrId, /api/user/:blablaid/roster (구형 ?blablaid=·?openid= 쿼리 경로도 동일하게 적용)

GET /api/nikkes?fields=id,name.ko,images.icon
GET /api/nikkes/201601?fields=name,details.skills,details.squad.name
GET /api/favorites?fields=id,name.ko,images.icon
GET /api/scenes?category=attractive&fields=groupId,name,nikke
GET /api/scenes/d_ex_armory_01?fields=groupId,lines
GET /api/cubes/1000301?fields=id,name,stats
GET /api/user/<blablaid>/nikke?fields=character.name,combat

응답 예시 — GET /api/nikkes?q=라피&fields=id,name.ko:

{
  "count": 2,
  "offset": 0,
  "characters": [
    { "id": 201001, "name": { "ko": "라피" } },
    { "id": 201601, "name": { "ko": "라피 : 레드 후드" } }
  ]
}
  • 목록 응답은 count 등 래퍼 필드는 그대로 두고 항목(characters[], scenes[] 등)만 잘라냅니다
  • 존재하지 않는 필드를 넣어도 에러가 아니라 그냥 빠집니다
  • 배열 안쪽의 필드는 지정할 수 없습니다 (예: details.voices.text는 안 됨 — 배열 통째로만 선택 가능)
  • 미지정 시 전체 응답 그대로 (기존과 동일)

언어 선택 — ?lang=

모든 JSON 응답에 붙일 수 있습니다 (파일 그대로 내려주는 상세 엔드포인트 포함). name·description·descriptions 등 {ko,en,ja,zh-TW} 형태의 다국어 객체가 지정한 언어의 문자열 하나로 평탄화됩니다.

GET /api/nikkes?lang=ko        → "name": "라피"
GET /api/nikkes?lang=en        → "name": "Rapi"
GET /api/favorites/200101?lang=ja

지원 값: ko·en·ja·zh-TW. 그 외 값이나 미지정 시 기존 4개 언어 객체 그대로 반환. 해당 언어가 없는 필드는 ko→en→첫 번째 값 순으로 폴백합니다.

캐시

모든 200 응답에 Cache-Control: public, max-age=3600, s-maxage=86400과 ETag가 붙습니다. If-None-Match로 재요청하면 304로 응답 본문을 생략합니다 — 응답은 배포 시에만 바뀌므로 캐시해도 안전합니다. 엣지 캐시 키와 ETag에는 데이터 버전과 워커 번들의 내용 해시가 함께 들어가, 데이터나 코드 중 하나만 배포해도 새 응답을 받습니다. 단 /burst-assets/<revision>/…는 경로에 ArtHub 리비전이 고정돼 있어 버전 없이 경로로만 캐시합니다. 304는 실제 200 응답에만 적용되며, 없는 경로는 항상 404입니다.

단 /api/user/*는 실시간 조회라 캐시하지 않습니다 (Cache-Control: no-store, ETag 없음).

MCP (ChatGPT / Claude 연결)

/mcp는 MCP 서버입니다. ChatGPT, Claude, Cursor 같은 AI 클라이언트에 아래 URL을 넣으면 이 API를 도구로 쓸 수 있습니다. 인증은 필요 없습니다.

https://nikke-api.pages.dev/mcp

클라이언트별 연결 방법, 도구 목록, 문제 해결은 docs/mcp.md에 있습니다.

자기 BlablaLink 공유 링크를 POST /mcp/register에 한 번 등록하면 개인 커넥터 URL(/mcp/u/<key>)을 받습니다 — 그 주소로 연결하면 get_user_* 도구가 링크 입력 없이 내 프로필을 바로 조회합니다.

API 문서

  • 인터랙티브 문서 (브라우저에서 바로 테스트) → /docs
  • 요청/응답 형식 전체 문서 → API.md
  • Postman 컬렉션 → nikke-api.postman_collection.json (Import 후 blablaid 변수만 설정하면 /api/user/*도 바로 사용 가능)

문서 사이트

문서 사이트 → https://nikke-api-docs.pages.dev (MCP 연결 가이드 + 인터랙티브 API 레퍼런스, Cloudflare Pages)

AI 어시스턴트용으로 /llms.txt와 /llms-full.txt도 함께 배포됩니다.

로컬에서 실행하려면:

cd site && npm i && npm run dev

npm run dev/build는 먼저 실제 앱 응답 예시가 들어간 openapi.json과 llms.txt 등을 생성합니다(site/scripts/). 데이터는 NIKKE_DATA_DIR(없으면 data/dist, 그다음 test/fixtures/dist)을 쓰므로, 실데이터로 빌드하려면 npm run fetch:data를 먼저 실행하세요. 빌드 환경변수: VITE_API_BASE(API 주소, 기본은 엣지), VITE_SITE_URL(canonical 기준 주소), VITE_BASE(하위 경로에 배포할 때).

배포 (Cloudflare Pages)

.github/workflows/pages.yml이 main push 때 프로덕션, 이 레포에서 연 PR마다 미리보기를 배포합니다. 처음 한 번만 설정이 필요합니다.

  1. Cloudflare 대시보드 → Workers & Pages → 만들기 → Pages → Direct Upload로 프로젝트 nikke-api-docs를 만듭니다(이름을 바꾸면 레포 변수 DOCS_PAGES_PROJECT에 그 이름을 넣습니다). 프로덕션 브랜치는 main.
  2. API 토큰 만들기 → Cloudflare Pages: Edit 권한 토큰을 발급합니다.
  3. 레포 Settings → Secrets and variables → Actions에 시크릿 CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID를 넣습니다.
  4. 커스텀 도메인을 쓰면 Pages 프로젝트에 연결하고, 레포 변수 DOCS_SITE_URL에 그 주소(예: https://docs.example.com/)를 넣습니다. canonical·sitemap·llms.txt가 이 주소를 씁니다.

시크릿이 없으면 빌드만 하고 배포는 건너뜁니다(포크 PR도 동일).

문의

문의나 요청사항은 leegunwoo0325@gmail.com으로 보내주시거나 Issues 기능을 활용해주시면 감사하겠습니다.

Releases

Packages

Contributors

Languages