제미나이 무료 API, 스튜디오 한도, Vertex, 원화 부가세 | 유료 전환 손익은 어떻게 잡나?

환경 변수 준비와 유출 스모크 (.env.local)
# .env.local  | 반드시 .gitignore 에 추가
GEMINI_API_KEY=여기에_발급받은_키
GEMINI_MODEL=gemini-2.5-flash

# 셸 1회 로드
export GEMINI_API_KEY="$(grep '^GEMINI_API_KEY=' .env.local | cut -d= -f2-)"
export GEMINI_MODEL="$(grep '^GEMINI_MODEL=' .env.local | cut -d= -f2-)"
echo "key length: ${#GEMINI_API_KEY}"

# 실수로 커밋했는지 확인 (출력되면 즉시 폐기·재발급)
git grep -nE 'AIza[0-9A-Za-z_-]{20,}' || echo "no key string in repo (good)"

limits.snapshot.js | 대시보드에서 적어 둔 한도
/** 배포 전 AI Studio Rate Limit 화면 값을 그대로 덮어쓴다 */
export const LIMITS = {
  // 예시 값 | 실제 계정 수치로 교체 필수
  'gemini-2.5-flash': { rpm: 10, tpm: 250000, rpd: 250 },
  'gemini-2.5-pro': { rpm: 5, tpm: 250000, rpd: 100 },
};

export function pickModel(prefer = 'gemini-2.5-flash') {
  if (!LIMITS[prefer]) throw new Error('unknown model in LIMITS: ' + prefer);
  return { model: prefer, ...LIMITS[prefer] };
}

// node -e "import('./limits.snapshot.js').then(m=>console.log(m.pickModel()))"
console.log(pickModel(process.env.GEMINI_MODEL || 'gemini-2.5-flash'));

capacity.js | 일일 필요 요청·분당 피크 추정
/**
 * side project capacity estimate
 * reqPerUserAction: 한 사용자 행동당 API 호출 수 (에이전트면 3~8 흔함)
 * dailyActiveUsers: 하루 활성 (또는 내부 배치 대상 건수)
 * batchJobs: 크론·배치 추가 호출
 * peakShare: 피크 1분에 몰리는 일일 비율 가정 (0.02 = 2%)
 */
export function estimateDemand({
  reqPerUserAction = 1,
  dailyActiveUsers = 50,
  batchJobs = 20,
  retryFactor = 1.15,
  peakShare = 0.02,
} = {}) {
  const daily = Math.ceil(
    (reqPerUserAction * dailyActiveUsers + batchJobs) * retryFactor
  );
  const peakRpm = Math.ceil(daily * peakShare);
  return { daily, peakRpm };
}

export function fitsFreeTier(demand, limits, safety = 0.75) {
  const rpdOk = demand.daily <= limits.rpd * safety;
  const rpmOk = demand.peakRpm <= limits.rpm * safety;
  return {
    rpdOk,
    rpmOk,
    ok: rpdOk && rpmOk,
    headroomRpd: Math.floor(limits.rpd * safety - demand.daily),
    headroomRpm: Math.floor(limits.rpm * safety - demand.peakRpm),
  };
}

// 예시: 글 요약 1회/사용자, DAU 40, 배치 30
const demand = estimateDemand({
  reqPerUserAction: 1,
  dailyActiveUsers: 40,
  batchJobs: 30,
});
const limits = { rpm: 10, tpm: 250000, rpd: 250 };
console.log({ demand, fit: fitsFreeTier(demand, limits) });

budget.js | 일일 호출 카운터 (KST 일자)
import fs from 'node:fs';
import path from 'node:path';

const FILE = path.join(process.cwd(), '.data', 'gemini-daily.json');

function todayKey() {
  return new Date().toLocaleString('sv-SE', { timeZone: 'Asia/Seoul' }).slice(0, 10);
}

export function bumpDaily(limit = 200, warnRatio = 0.7) {
  fs.mkdirSync(path.dirname(FILE), { recursive: true });
  let state = { day: todayKey(), count: 0 };
  try {
    state = JSON.parse(fs.readFileSync(FILE, 'utf8'));
  } catch {}
  if (state.day !== todayKey()) state = { day: todayKey(), count: 0 };
  state.count += 1;
  fs.writeFileSync(FILE, JSON.stringify(state));

  const ratio = state.count / limit;
  if (ratio >= warnRatio) {
    console.warn(
      `[gemini] daily ${state.count}/${limit} (${Math.round(ratio * 100)}%)`
    );
  }
  if (state.count > limit) {
    const err = new Error('local daily budget exceeded');
    err.code = 429;
    throw err;
  }
  return state;
}

rpm-gate.js | 프로세스 내 분당 스로틀
/** 단일 프로세스 한정. 다중 인스턴스면 공유 저장소 필요 */
export function createRpmGate(maxPerMinute = 8) {
  const stamps = [];
  return async function acquire() {
    const now = Date.now();
    while (stamps.length && now - stamps[0] > 60_000) stamps.shift();
    if (stamps.length >= maxPerMinute) {
      const wait = 60_000 - (now - stamps[0]) + 50;
      await new Promise((r) => setTimeout(r, wait));
      return acquire();
    }
    stamps.push(Date.now());
  };
}

// const gate = createRpmGate(8); // 대시보드 RPM보다 20~30% 낮게
// await gate(); await callGemini(...);

call.js | 예산 게이트 후 호출 + 백오프
import { bumpDaily } from './budget.js';
import { createRpmGate } from './rpm-gate.js';

const gate = createRpmGate(Number(process.env.GEMINI_RPM_SOFT || 8));

function sleep(ms) {
  return new Promise((r) => setTimeout(r, ms));
}

function isRateLimited(err) {
  const s = String(err?.status || err?.code || err?.message || '');
  return /429|RESOURCE_EXHAUSTED|rate.?limit|daily budget/i.test(s);
}

export async function withBackoff(fn, { maxAttempts = 4, baseMs = 800 } = {}) {
  let last;
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      last = err;
      if (!isRateLimited(err) || attempt === maxAttempts) throw err;
      const exp = baseMs * 2 ** (attempt - 1);
      const jitter = Math.floor(Math.random() * 200);
      await sleep(exp + jitter);
    }
  }
  throw last;
}

/** 공식 SDK 표면은 버전에 따라 다를 수 있음 | 설치 후 문서 예제와 대조 */
export async function generateText(prompt, { dailyLimit = 180 } = {}) {
  bumpDaily(dailyLimit);
  await gate();
  return withBackoff(async () => {
    // 의사코드: 실제로는 @google/genai 등 공식 클라이언트로 교체
    const key = process.env.GEMINI_API_KEY;
    if (!key) throw new Error('GEMINI_API_KEY missing');
    const model = process.env.GEMINI_MODEL || 'gemini-2.5-flash';
    const url =
      'https://generativelanguage.googleapis.com/v1beta/models/' +
      model +
      ':generateContent';
    const res = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-goog-api-key': key,
      },
      body: JSON.stringify({
        contents: [{ parts: [{ text: prompt }] }],
      }),
    });
    if (!res.ok) {
      const err = new Error('gemini http ' + res.status);
      err.status = res.status;
      throw err;
    }
    const data = await res.json();
    return data?.candidates?.[0]?.content?.parts?.[0]?.text || '';
  });
}

// node --input-type=module -e "import {generateText} from './call.js'; console.log(await generateText('한 문장 자기소개'))"

cost-krw.js | 월 예상 비용 (USD → 원 · VAT)
/**
 * rates: Pricing 표에서 가져온 USD / 1M tokens
 * usdKrw: 계산 시점 환율 (예: 1380)
 * vat: 부가세율 기본 0.10
 * fxFee: 해외결제 수수료 가정 (없으면 0)
 */
export function monthlyCostKrw({
  inputTokens = 2_000_000,
  outputTokens = 500_000,
  inputPer1M = 0.15, // 예시 | Pricing으로 교체
  outputPer1M = 0.6, // 예시 | Pricing으로 교체
  usdKrw = 1380,
  vat = 0.1,
  fxFee = 0.02,
} = {}) {
  const usd =
    (inputTokens / 1e6) * inputPer1M + (outputTokens / 1e6) * outputPer1M;
  const krw = usd * usdKrw;
  const withVat = krw * (1 + vat);
  const withFee = withVat * (1 + fxFee);
  return {
    usd: Number(usd.toFixed(4)),
    krw: Math.round(krw),
    krwWithVat: Math.round(withVat),
    krwAllIn: Math.round(withFee),
  };
}

// Flash 예시 단가로 월 2M in / 0.5M out
console.log(
  monthlyCostKrw({
    inputTokens: 2_000_000,
    outputTokens: 500_000,
    inputPer1M: 0.15,
    outputPer1M: 0.6,
  })
);
// → { usd, krw, krwWithVat, krwAllIn }

decide.js | 전환 경로 추천 (규칙 기반)
/**
 * freeFit: fitsFreeTier() 결과
 * daysHit70: 최근 14일 중 일일 70% 경고 일수
 * needVpcOrSla: 조직 VPC·SLA·고객 데이터 계약 필요 여부
 * monthlyBudgetKrw: 사이드 월 AI 예산
 * paidAllInKrw: monthlyCostKrw().krwAllIn
 */
export function decidePath({
  freeFit,
  daysHit70 = 0,
  needVpcOrSla = false,
  monthlyBudgetKrw = 30000,
  paidAllInKrw = 0,
} = {}) {
  if (needVpcOrSla) {
    return {
      path: 'vertex',
      reason: '조직 보안·SLA 요건 → Vertex 견적·할당량 확인',
    };
  }
  if (freeFit?.ok && daysHit70 < 3) {
    return {
      path: 'stay_free',
      reason: '한도 여유 + 경고 드묾 → 무료 유지, 캐시만 강화',
    };
  }
  if (paidAllInKrw > 0 && paidAllInKrw <= monthlyBudgetKrw) {
    return {
      path: 'ai_studio_tier1',
      reason: '청구 연동(Tier1) 검토 | 예산 안, 한도 확장 우선',
    };
  }
  return {
    path: 'reduce_usage',
    reason: '유료 상한이 예산 초과 → 요청 합치기·캐시·모델 다운그레이드',
  };
}

// 예시
console.log(
  decidePath({
    freeFit: { ok: false },
    daysHit70: 5,
    needVpcOrSla: false,
    monthlyBudgetKrw: 30000,
    paidAllInKrw: 12000,
  })
);