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로 제공 (직접 재호스팅하지 않음)
- 스킬 설명은 최대 레벨 기준으로 렌더링된 텍스트 제공 (원본 템플릿·레벨별 수치도 포함)
| 항목 | 내용 |
|---|---|
| 기본 정보 | 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·버스트의 레벨별(2details.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명이 코스튬 전용 대사 보유) |
메인/이벤트/돌발 스토리 + 호감도(Attractive) 시나리오의 전체 대본. 애장품 스토리 21편도 영상에서 옮긴 대본으로 함께 제공합니다. 게임 데이터에 없는 메신저·유실물·사이드 스토리·서브 퀘스트·이벤트 약 2000편은 library 카테고리에 있습니다. 출처는 Nikke Forbidden Library입니다.
| 항목 | 내용 |
|---|---|
| 분류 | main / event / sudden / attractive / favorite / library 카테고리 + 니케별·이름 검색, 페이지네이션 |
| 대본 | 대사별 화자 코드·이름·텍스트·말풍선 타입 |
| 화자 정보 | 화자 코드·이름 + 아이콘 이미지 URL (NPC 포함) |
| 씬 보이스 | 풀보이스 챕터·이벤트는 대사별 한국어 음성 mp3 URL 제공, 보이스 없는 라인은 voice: null |
| 호감도 씬 | 대상 니케·필요 호감도 레벨 + 배경/BGM 리소스 코드 |
| 항목 | 내용 |
|---|---|
| 기본 정보 | 이름·설명(4개 언어), 레어(R/SR/SSR), 무기 타입, 아이콘·프롭 이미지, 소유 니케(character) |
| 레벨별 스탯 | atk/def/hp/power/grade + 해당 레벨의 컬렉션·소장품 스킬 레벨 |
| 스킬 | 수집 효과 스킬(collection) + 돌파 슬롯별 전용 스킬(item) — 최대 레벨 렌더링 설명 + 원본 수치 |
| 항목 | 내용 |
|---|---|
| 기본 정보 | 이름·설명·획득처(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=도 그대로 동작합니다.
레벨 테이블, 스테이지/타워 목록, 장비 옵션, 아카이브 등 동기화된 게임 데이터 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 변환 |
응답이 큰 엔드포인트에서 필요한 필드만 골라 받을 수 있습니다. 콤마로 여러 개 지정하고, 점(.)으로 중첩 필드를 파고듭니다.
지원 엔드포인트: /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는 안 됨 — 배열 통째로만 선택 가능) - 미지정 시 전체 응답 그대로 (기존과 동일)
모든 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는 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_* 도구가 링크 입력 없이 내 프로필을 바로 조회합니다.
- 인터랙티브 문서 (브라우저에서 바로 테스트) → /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 devnpm 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(하위 경로에 배포할 때).
.github/workflows/pages.yml이 main push 때 프로덕션, 이 레포에서 연 PR마다 미리보기를 배포합니다. 처음 한 번만 설정이 필요합니다.
- Cloudflare 대시보드 → Workers & Pages → 만들기 → Pages → Direct Upload로 프로젝트
nikke-api-docs를 만듭니다(이름을 바꾸면 레포 변수DOCS_PAGES_PROJECT에 그 이름을 넣습니다). 프로덕션 브랜치는main. - API 토큰 만들기 → Cloudflare Pages: Edit 권한 토큰을 발급합니다.
- 레포 Settings → Secrets and variables → Actions에 시크릿
CLOUDFLARE_API_TOKEN,CLOUDFLARE_ACCOUNT_ID를 넣습니다. - 커스텀 도메인을 쓰면 Pages 프로젝트에 연결하고, 레포 변수
DOCS_SITE_URL에 그 주소(예:https://docs.example.com/)를 넣습니다. canonical·sitemap·llms.txt가 이 주소를 씁니다.
시크릿이 없으면 빌드만 하고 배포는 건너뜁니다(포크 PR도 동일).
문의나 요청사항은 leegunwoo0325@gmail.com으로 보내주시거나 Issues 기능을 활용해주시면 감사하겠습니다.