APIsis 란?

생활 속 다양한 데이터를 API 형태로 제공해주는 openAPI 서비스
API 서버, 키 관리 페이지가 하나의 서버로 실행됩니다
또한 모든게 오픈소스로 도커 파일이 제공되어 API 서버를 로컬에 띄워 내부에서 사용할 수도 있습니다

구성

API

관리중인 API들을 제공하는 서버입니다
API Key를 통해 계정 인증을 하고 라이센스에 맞게 API 별 사용량을 제공합니다

관리 페이지 API

제공용 API가 아닌 내부 관리 페이지 전용 API 입니다
계정 관리와 사용량 통계 및 분석 등 호출에 필요한 키를 관리하는 데 중점인 API 이며, 사용자 입장에선 사용하지 않는 내부용 API입니다

계정의 경우 총 3가지(구글, github, 카카오)의 oauth2 로그인을 지원합니다
이메일 계정이 같을 경우 하나의 계정으로 판별되며 계정 별 라이센스를 가질 수 있습니다

라이센스는 xxxx-xxxx-xxxx-xxxx 형태의 코드를 가지고 있으며, 플랜 별로 만료일과 사용량이 달라집니다
라이센스는 크게 4가지로 나눠져 있으며 EXTRA 플랜을 제외하곤 모두 월별, 연별 만료일 플랜이 존재합니다

• BASIC: 라이센스가 없는 사용량보단 훨씬 많은 사용량을 제공하나 많진 않은 플랜
• PRO: 실 사용에 문제 없는 사용량을 제공하는 플랜
• ENTERPRISE: 대규모 운영 환경 사용에 문제 없는 사용량을 제공하는 플랜
• EXTRA: 무제한 플랜

라이센스는 계정 당 하나만 소유할 수 있고 라이센스 자체를 삭제할 순 없습니다
계정에서 라이센스 해제는 가능하나 다른 계정에서 해당 코드를 적용하면 적용할 수 있는 구조로 설계되어 있습니다

MCP

자체 MCP 서버도 자동 실행되어 SSE 방식으로 MCP 연결이 가능합니다
API 정보들을 AI에게 제공해주어 바이브 코딩 시 API 연결에도 유용하게 사용할 수 있습니다

최초 실행 데이터 세팅 프로세스

APIsis Application 최초 실행 시 데이터베이스에 데이터 세팅이 필요합니다
이를 자동화 하기 위해 자동 데이터 세팅 프로세스가 설계되었으며 서버 실행 시 데이터가 없는 기능에 한하여 실행됩니다

데이터 별로 처리 방식이 모두 다릅니다. 현재까지의 데이터는 아래와 같이 처리됩니다

• 방탈출
  • 방식: 외부(빠방) API 호출
  • 프로세스 시점: 방탈출 table에 데이터가 하나도 없을 경우
  • 시나리오: Application 실행 > 방탈출 table select > (비어있을 경우) > 빠방 API 호출 (Paging) > DB insert > 반복
• 법정동 코드
  • 방식: excel 파싱
  • 프로세스 시점: 법정동 코드 table에 데이터가 하나도 없을 경우
  • 시나리오: Application 실행 > 법정동 코드 table select > (비어있을 경우) > /excel/areacode_01.xlsx 파싱 > DB insert
• 로또
  • 방식: 외부 API 호출
  • 프로세스 시점: 로또 table에 데이터가 하나도 없을 경우
  • 시나리오: Application 실행 > 로또 table select > (비어있을 경우) > 로또 API 호출 > DB insert > 반복

데이터 업데이트 스케줄러

최신 데이터 제공을 위해 특정 데이터들은 스케줄러로 데이터 업데이트를 진행합니다

• 방탈출
  • 데이터 추가
    • 실행주기: 매일 오전 1시
    • 프로세스: 최근 빠방에 등록된 방탈출 카페/테마 insert
  • 데이터 업데이트
    • 실행주기: 매일 오전 3시
    • 프로세스: 매일 500개 치 테마 update. ref_id 기준 1~500, 다음날 501~1000 이런식으로 매일 500개씩 업데이트 하여 별점과 운영 여부 등 데이터를 업데이트
• 로또
  • 실행주기: 매주 토요일 오후 9시
  • 프로세스: 최근 공개된 로또번호 insert

관리 페이지

패키지에 html도 포함되어 있어 서버 실행 시 관리 페이지도 함께 띄워집니다
서버 도메인 경로로 접속 시 랜딩페이지가 표시됩니다

총 3가지의 oauth2 로그인을 지원합니다
(직접 서버 실행 시 별도의 oauth 설정이 필요합니다)

로그인 후 접속하면 대시보드가 표시됩니다
전체적인 통계와 API 키 관리 그리고 여러가지 가이드들이 제공됩니다

• API Key 관리: 대시보드보다 더욱 자세한 키 별 통계도 확인할 수 있습니다
• 놀이터: 서버에 있는 API들을 직접 호출해볼 수 있는 화면입니다. 생성한 API Key로 직접 호출해보며 결과를 바로 확인해보실 수 있습니다 (사용량 소모됨)
• API 목록: 서버에 있는 API들을 찾아볼 수 있는 화면입니다
• 문서: API들의 상세한 request, response 정보를 볼 수 있습니다
• 사용량 통계: API 호출에 추이를 그래프 등 여러 지표로 제공합니다
• 분석: 사용량 통계를 베이스로 AI가 사용 현황 보고서를 작성해줍니다
• 설정: 여러 설정들을 관리합니다. 라이센스, 분석, 데이터 삭제 등 옵션을 제공합니다

마치며

openAPI 서버를 운영해보니 몇몇 개인 프로젝트에도 도입을 해봤습니다
미리 필요한 데이터를 APIsis에 등록해두고 프로젝트에 AI로 연결해달라 하면 뚝딱 연결해주는게 생각보다 편하네요
물론 개인 프로젝트에서 직접 연결해서 써도 되지만, 범용적으로 쓸 수 있게 미리 설계해두면 나중에 유용하게 쓰일 것으로 예상됩니다 (사실상 나만의 API 게이트웨이)

개인 프로젝트 중 완성도 높은 프로젝트가 아닐까 싶습니다
무엇보다 서비스 이름이 너무 마음에 드는것도 한 몫 하네요. API oasis… 헤헤헤헤

추가 기능 (0.2.1 기준)

• Image Generator 추가
• 이미지와 함께 질의응답

지원 버전

(0.1.0 과 동일합니다)

• JVM 8+
• Kotlin 1.9+
• Spring Boot 2.7+
• Spring 5.3+

라이브러리 설정

jitpack을 통해 배포되었습니다
아래와 같이 jitpack.io repository url 정의가 선행되어야 합니다

build.gradle.kts

repositories {
    mavenCentral()
    maven { url = uri("https://jitpack.io") }
}

dependencies {
    implementation("com.github.hyuck0221:kemi:0.2.1")
}

application.yml

kemi:
  gemini:
    api-keys:
      - your-first-api-key
      - your-second-api-key
      - your-third-api-key
    base-url: https://generativelanguage.googleapis.com
    models:
      - gemini-2.5-flash
      - gemini-2.5-flash-lite
      - gemini-2.0-flash
      - gemini-2.0-flash-lite
    image-models: # NEW!
      - gemini-2.5-flash-image
      - gemini-3-pro-image-preview

• image-models (선택)
  • Gemini 이미지 생성 AI Model
  • 사용량 만료 시 다음 model로 자동 fallback
  • 미입력 시 gemini-2.5-flash-image, gemini-3-pro-image-preview 적용

이미지 생성 사용법

Bean에 등록된 Generator를 불러와 호출합니다

import com.hshim.kemi.GeminiImageGenerator
import org.springframework.stereotype.Service

@Service
class ImageService(private val geminiImageGenerator: GeminiImageGenerator) {
    fun generateImage() {
        // 이미지 생성
        val images = geminiImageGenerator.generateImage(
            prompt = "산 위로 지는 아름다운 석양"
        )
    }

    fun generateWithOptions() {
        // 커스텀 종횡비와 해상도로 생성
        val images = geminiImageGenerator.generateImage(
            prompt = "밤의 미래 도시",
            aspectRatio = "16:9",
            imageSize = "4K"
        )
    }

    fun generateWithReferenceImages() {
        // 스타일 가이드를 위한 참조 이미지와 함께 생성
        val referenceImage = ImageData.fromPath("style-reference.jpg")

        val images = geminiImageGenerator.generateImage(
            prompt = "이 예술적 스타일로 산 풍경을 그려주세요",
            aspectRatio = "3:2",
            imageSize = "2K",
            referenceImages = listOf(referenceImage)
        )
    }
}

image-models에 설정된 모델로 이미지를 생성합니다
생성된 이미지는 Base64로 인코딩 된 형태로 전송받습니다

이미지 분석

기본 질의응답에 사용되는 GeminiGenerator와 채팅 형태의 GeminiChatGenerator에서 지원합니다 이미지 분석 및 이해를 위해 질문과 함께 이미지를 askWithImages 함수로 전송할 수 있습니다

import com.hshim.kemi.model.ImageData

@Service
class VisionService(
private val geminiGenerator: GeminiGenerator
) {
fun analyzeImage() {
// 파일에서 이미지 로드
val image = ImageData.fromPath("/path/to/photo.jpg")

        val answer = geminiGenerator.askWithImages(
            question = "이 이미지에 무엇이 있나요?",
            images = listOf(image)
        )
        println(answer)
    }

    fun compareImages() {
        // 여러 이미지를 한 번에 분석
        val image1 = ImageData.fromFile(File("photo1.jpg"))
        val image2 = ImageData.fromFile(File("photo2.png"))

        val answer = geminiGenerator.askWithImages(
            question = "이 두 이미지의 차이점은 무엇인가요?",
            images = listOf(image1, image2)
        )
        println(answer)
    }
}

채팅 대화에서 Vision 사용

@Service
class VisionChatService(
private val geminiChatGenerator: GeminiChatGenerator
) {
fun analyzeImagesInConversation() {
val chat = geminiChatGenerator.createSession()

        // 이미지와 함께 첫 메시지
        val image1 = ImageData.fromPath("diagram.png")
        chat.sendMessageWithImages(
            message = "이 다이어그램은 무엇을 보여주나요?",
            images = listOf(image1)
        )

        // 후속 질문 (AI가 이미지 컨텍스트를 기억함)
        chat.sendMessage("세 번째 구성 요소를 설명해 주실 수 있나요?")

        // 같은 대화에서 다른 이미지
        val image2 = ImageData.fromPath("chart.png")
        chat.sendMessageWithImages(
            message = "이 차트는 이전 다이어그램과 어떤 관련이 있나요?",
            images = listOf(image2)
        )
    }

    fun streamVisionResponse() {
        val chat = geminiChatGenerator.createSession()
        val image = ImageData.fromFile(File("complex-image.jpg"))

        // 이미지 분석을 스트리밍 응답으로 받기
        chat.sendMessageStreamWithImages(
            message = "이 이미지를 자세히 설명해주세요",
            images = listOf(image)
        ) { chunk ->
            print(chunk)  // 분석이 생성되는 대로 출력
        }
    }
}

마치며

개인 프로젝트를 진행하며 이미지 생성이 필요해저 지난번 설계한 kotlin + gemini 라이브러리에 적용 해 봤습니다
kemi 라이브러리의 목적이였던 ‘간단한 AI 호출’ 영역 내에서 이미지 생성까지 지원하게 되니 마음이 한결 편안하네요

이번에 gemini로 이미지 생성을 해보니 이미지 생성은 많이 비싸다는 걸 깨달았습니다
특히 pro 모델은 난발하지 마세요.. (많이 쓰지도 않았는데 금방 10$)

Call It 플러그인이란?

Jetbrains 기반 IDE 에서 사용할 수 있는 AI 변수명 생성 플러그인입니다
Gemini API Key를 입력하여 빠른 변수명 작명이 가능합니다

지원 기능 (1.0 기준)

• 최신 Gemini 모델 사용 가능
• 5가지 다국어 지원
• 프로그래밍 언어 감지하여 맞춤 추천
• 동시 n개 변수명 추천

지원 IDE

Android Studio, AppCode, Aqua, CLion, Code With Me Guest, DataSpell, DataGrip, JetBrains Gateway, GoLand, IntelliJ IDEA, JetBrains Client, MPS, PhpStorm, PyCharm, Rider, RubyMine, RustRover, WebStorm, Writerside

플러그인 다운로드

Jetbrains CallIt Plugin

IDE plugin 화면에서도 찾아보실 수 있습니다

설정

Settings > Tools > CallIt > Gemini API Key 입력 > 확인

• Gemini API Key: google ai studio에서 발급받은 api key
• Gemini Model: 사용 가능한 모델들
• Max Suggestions: 추천 내역 수
  (1로 설정 시 즉시 적용)
• message Language: 설정 언어

사용법

변경하고 싶은 문장 드래그 우클릭 > Suggest Name with CallIt 클릭

원하는 제안 선택 후 OK
(Max Suggestions가 1이면 아래 창은 뜨지 않습니다)

마치며

회사에서 회계 용어들을 변수명으로 지어야 하다 보니 머리를 싸매는 일이 많아졌습니다
이 기능을 하는 플러그인이 이미 많이 존재하겠지만 직접 만들고 싶어 간단하게 구현해본 프로젝트입니다

만들어보면서 플러그인에 구성 방식과 구현 방법 등 어떻게 흘러가는지 알 수 있는 좋은 계기가 되었습니다

Kemi 라이브러리란?

SpringBoot 환경에서 적은 설정으로 쉽고 빠르게 Gemini 호출을 도와줍니다
간편함을 최우선으로 하여 설계되었고, 빠른 설정과 빠른 호출/관리가 필요한 경우 적합합니다

지원 기능 (0.1.0 기준)

• Gemini Auto Configuration 지원
• API key, Model fallback 지원
• Default Prompt 지원
• 응답 Class 매핑과 어노테이션 형태의 프롬프트 작성 지원
• 채팅형 Generator 지원
• stream 응답 지원

지원 버전

• JVM 8+
• Kotlin 1.9+
• Spring Boot 2.7+
• Spring 5.3+

라이브러리 설정

jitpack을 통해 배포되었습니다
아래와 같이 jitpack.io repository url 정의가 선행되어야 합니다

build.gradle.kts

repositories {
    mavenCentral()
    maven { url = uri("https://jitpack.io") }
}

dependencies {
    implementation("com.github.hyuck0221:kemi:0.1.0")
}

application.yml

kemi:
  gemini:
    api-keys: # 필수
      - your-first-api-key
      - your-second-api-key
      - your-third-api-key
    base-url: https://generativelanguage.googleapis.com  # 선택
    models: # 선택
      - gemini-2.5-flash
      - gemini-2.5-flash-lite
      - gemini-2.0-flash
      - gemini-2.0-flash-lite

• api-keys (필수)
  • Google AI Studio에서 발급한 API Key
  • 1개 이상 필수로 등록 필요
  • 사용량 만료 시 다음 key로 자동 fallback
• base-url (선택)
  • Gemini API 기본 url
• models (선택)
  • Gemini AI Model
  • 사용량 만료 시 다음 model로 자동 fallback
  • 미입력 시 gemini-2.5-pro 적용

기본 사용법

Bean에 등록된 Generator를 불러와 호출합니다
Generator는 GeminiGenerator 와 GeminiChatGenerator 로 구분됩니다

import com.hshim.kemi.GeminiGenerator
import com.hshim.kemi.GeminiChatGenerator
import org.springframework.stereotype.Service

@Service
class MyService(
    private val geminiGenerator: GeminiGenerator,
    private val geminiChatGenerator: GeminiChatGenerator,
)

GeminiGenerator

1회성 질문 -> 출력이 필요한 경우 사용합니다

val result = geminiGenerator.ask("너는 어떤 모델이야?")

println(result) // ex. 반가워요! 저는 구글에서 만든 Gemini 2.5 Flash 모델입니다.

GeminiChatGenerator

대화 컨텍스트를 유지해야 할 경우 사용합니다
질문 -> 출력 과정을 모두 하나의 세션에 저장되고 다음 질문에선 세션에 저장된 히스토리를 포함하여 요청합니다

val session = geminiChatGenerator.createSession()

val response1 = session.sendMessage("안녕하세요, 제 이름은 John입니다")
println(response1) // "안녕하세요 John님! 무엇을 도와드릴까요?"

val response2 = session.sendMessage("제 이름이 뭐죠?")
println(response2) // "당신의 이름은 John입니다"

저장, 불러오기를 지원하기 위해 세션 단위로 restore, export가 지원됩니다
세션에서 사용한 api-keys, models, 대화 histories 등 모든 정보가 하나의 object로 관리됩니다

// 세션 저장 과정
val sessionState = session.exportSession()
// ..세션 저장..

// 세션 불러오기 과정
// ..세션 불러오기..
val newSession = geminiChatGenerator.restoreSession(sessionState)

프롬프트 관리

모든 질문에 기본으로 적용되는 정적 시스템 프롬프트와
매 질문마다 적용할 수 있는 동적 시스템 프롬프트 총 두가지로 설정할 수 있습니다

정적 시스템 프롬프트 설정

Configuration 에서 Bean 등록 중 prompt를 지정하여 포함시킵니다

@Configuration
@EnableConfigurationProperties(GeminiProperties::class)
class GeminiConfiguration {

    private val prompt = "무조건 한국어로 답할 것"

    @Bean
    fun geminiGenerator(properties: GeminiProperties): GeminiGenerator {
        return GeminiGenerator(properties, prompt)
    }

    @Bean
    fun geminiChatGenerator(properties: GeminiProperties): GeminiChatGenerator {
        return GeminiChatGenerator(properties, prompt)
    }
}

동적 시스템 프롬프트 설정

GeminiGenerator: 질문 전송 시 질문과 함께 프롬프트를 전송합니다
GeminiChatGenerator: session 생성 시 프롬프트를 지정하여 메세지 전송 마다 프롬프트를 적용시킵니다

// GeminiGenerator
geminiGenerator.ask(
    question = "양자 컴퓨팅에 대해 설명해줘",
    prompt = "너는 친절한 물리학 교수야"
)

// GeminiChatGenerator
geminiChatGenerator.createSession("욕쟁이 할머니처럼 대답해")

Stream 응답

GeminiGenerator: askStream()
GeminiChatGenerator: sendMessageStream()

handler를 통해 응답을 chunk 단위로 돌려받습니다

GeminiGenerator

val result = geminiGenerator.askStream("소설 하나만 만들어줘") { chunk ->
    print(chunk)  // 각 단어가 도착하는 즉시 출력
}

// result 에는 전체 응답 결과가 들어있음

GeminiChatGenerator

session.sendMessageStream("이야기를 들려주세요") { chunk ->
    print(chunk)  // 각 단어가 도착하는 즉시 출력
}

session.sendMessageStream("주인공의 이름이 뭐였죠?") { chunk ->
    print(chunk)
}

Data Class 매핑

geminiGenerator에선 askWithClass 함수로 요청 시 적용한 Class 형태로 역직렬화를 지원합니다
추가로 응답에 적용되는 Class 와 Field에 어노테이션을 통해 각각 프롬프트를 적용할 수 있습니다

• GeminiPrompt: Class 단위에서 적용되는 프롬프트
• GeminiField: Class Field 단위에 적용되는 프롬프트

@GeminiPrompt("전자상거래를 위한 정확하고 현실적인 제품 정보를 생성하세요")
data class Product(
    @GeminiField("제품명, 명확하고 간결해야 함")
    val name: String,

    @GeminiField("USD 가격, 양의 정수여야 함")
    val price: Int,

    @GeminiField("상세한 제품 설명, 2-3문장")
    val description: String,

    @GeminiField("제품 카테고리 (예: 전자제품, 의류, 식품)")
    val category: String
)

val product = geminiGenerator.askWithClass<Product>("프리미엄 스마트폰 제품을 생성해주세요")

Auto Fallback

Google Gemini 사용 정책은 프로젝트 별, 모델 별 사용량 한도가 제한되어 있습니다
여러개의 API key, model들을 미리 설정하여 사용량 한도가 초과된 경우 자동적으로 변경하여 호출합니다

fallback 우선순위는 다음과 같습니다

1. API key 변경
2. model 변경
3. 모두 한도 초과 시 Exception

모든 사용량 한도가 초과될 경우 “All fallback options exhausted.” Runtime Exception이 발생합니다

마치며

개인 프로젝트에서 Kemi 라이브러리를 아주 유용하게 사용하고 있는 입장으로써 특히 class mapping이 진짜 편합니다
보통 json으로 응답할 것을 프롬프트에 따로 기재하고, AI 응답을 직접 역직렬화 하는 작업이 필요한데 솔직히 이 작업.. 너무 귀찮아요
사실상 이 기능 때문에 Kemi 라이브러리 사용할 정도로 아주 편리합니다

블로그의 목표

• 프로젝트 기록: 진행중인 프로젝트 들의 설명과 방향성을 기록
• 학습 기록: 새로운 기술을 배우면서 얻은 인사이트 공유
• 문제 해결: 개발 중 마주친 문제와 해결 과정 정리
• 지식 공유: 다른 개발자들과 경험을 나누고 함께 성장

앞으로의 계획

다양한 주제의 글을 작성할 예정입니다:

1. 개발 경험담: 프로젝트를 진행하며 배운 점들
2. 기술 튜토리얼: 유용한 기술과 도구 사용법
3. 코드 리뷰: 흥미로운 코드 패턴과 베스트 프랙티스
4. 개발 생각: 개발자로서의 고민과 성찰

마치며

이 블로그는 저 자신의 기록이 되어줄 뿐 아니라 모두에게 유용한 도구가 될 수 있었으면 좋겠습니다