7eyes 서비스 개요

7eyes(SevenEyes)는 AI 기반 비서·창작 서비스입니다. 스타일·아바타·스티커·라이브 아바타·AI 통화를 하나의 계정·크레딧 체계로 제공합니다. 서비스명은 변경될 수 있으며, 본 문서의 API 경로·연동 규약은 동일하게 유지됩니다.

제품 구성

시스템 아키텍처

• 인증 — 카카오/구글 로그인 후 Firebase ID Token을 API 호출 시 Authorization: Bearer 사용(설정 예외 제외).
• 크레딧 — Firestore credits/{uid} 단일 문서. 웹(토스)·안드로이드(구글 인앱) 동일 잔액.
• 라이브 — POST /api/live-avatar/ensure-server로 미디어 서버 기동 후 LiveKit 세션 연결.

연동 환경

모든 경로는 {API_BASE}/api/... 형태입니다. 예: GET {API_BASE}/api/credits/config

사전 점검

curl -s "{API_BASE}/health"

Quickstart (Android)

1. Base URL 확정 (스테이징/운영 빌드 flavor별).
2. 카카오 로그인 → POST /api/kakao-auth → Firebase 커스텀 토큰으로 로그인 → ID Token 확보.
3. 가입·프로필 — POST /api/user/check, 필요 시 POST /api/user/save-profile.
4. 단가·상품 — GET /api/credits/config (인증 없음).
5. 기능 1회 — check → quoteId → 생성 API 호출 → deduct → 실패 시 deduct/rollback.

인증

카카오 → Firebase

POST {API_BASE}/api/kakao-auth
Content-Type: application/json

{ "accessToken": "<카카오 액세스 토큰>" }

// 성공 시 customToken 등 — 앱에서 FirebaseAuth.signInWithCustomToken

크레딧·사용자 API 공통

Authorization: Bearer <Firebase ID Token>

사용자 프로필

크레딧 API (V4.0)

상세 스펙은 팀 내부 크레딧 API 정본 문서(V4.0)를 참고하세요. 아래는 안드로이드 연동용 공개 요약입니다.

표준 흐름

1. POST /api/credits/check     → sufficient, quoteId (TTL 기본 30초)
2. POST /api/credits/deduct      → quoteId 소비, 잔액 차감
3. (비즈니스 실패 시)
   POST /api/credits/deduct/rollback  → refId 또는 quoteId로 원복

주요 엔드포인트

check 요청 예

POST /api/credits/check
Authorization: Bearer <token>
Content-Type: application/json

{
  "userId": "kakao_<카카오숫자ID>",
  "service": "style_premium"
}

deduct 요청 예

POST /api/credits/deduct
{
  "userId": "kakao_<카카오숫자ID>",
  "service": "style_premium",
  "quoteId": "",
  "refId": "<클라이언트 멱등 키, 권장>"
}

rollback 요청 예

POST /api/credits/deduct/rollback
{
  "userId": "kakao_<카카오숫자ID>",
  "quoteId": "<차감에 사용한 quoteId>"
  // 또는 "refId": "<차감 시 사용한 refId>"
}

서비스 코드 (V2 기본값)

카탈로그 & 생성

생성 API 호출 전후 크레딧 순서: check → (생성) → deduct 성공 또는 팀 정책에 맞는 시점. 실패 시 rollback.

모션 비디오

차감: motion_video_per_sec + meta.durationSeconds (루트에만 넣어도 서버가 meta로 병합).

라이브 아바타

1. GET /api/live-avatar/public-avatars — 스톡 아바타 목록(인증 없음).
2. POST /api/live-avatar/ensure-server — 미디어 서버 준비(status: ready, endpoint).
3. 응답 endpoint로 클라이언트 실시간 세션 연결 · LiveAvatar 연동.

외부 SDK·세션 프로토콜: LiveAvatar 공식 문서

POST /api/live-avatar/ensure-server
// 200
{ "status": "ready", "endpoint": "wss://...", "message": "..." }

크레딧: live_avatar (기본 220C). check/deduct에 동일 service 사용.

공지

GET /api/notices
GET /api/notices/:id

API 색인

오류 코드 (크레딧)

Changelog

• 2026-05 — Docs 허브 공개. rollback quoteId 지원. check durationSeconds 병합.
• V4.0 — POST /api/credits/deduct/rollback, history type 필터.
• V3.x — Google Play purchase/google-complete.