제미나이 무료 API, 쿼터 미터, 구조화 출력, 유료 전환 | 소프트 캡 코드는 어떻게 붙이나?

환경 변수 준비 (.env.local, 깃 제외)
# .env.local  — .gitignore 에 반드시 추가
GEMINI_API_KEY=여기에_발급받은_키
GEMINI_MODEL=gemini-2.5-flash
# 소프트 캡(실한도보다 낮게). 배포 전 Rate Limit 화면 숫자로 덮어쓰기
SOFT_RPD=1200
SOFT_RPM=10

# 1회 로드 (zsh/bash)
export $(grep -v '^#' .env.local | xargs)
echo "key length: ${#GEMINI_API_KEY}"

# 저장소에 키 문자열이 남았는지 확인 (출력되면 즉시 폐기·재발급)
git grep -nE 'AIza[0-9A-Za-z_-]{20,}' || echo "no key string in repo (good)"

패키지 설치
mkdir gemini-free-lab && cd gemini-free-lab
npm init -y
npm install @google/genai dotenv
# Node 18+ 권장. type:module 을 package.json 에 켜 두면 ESM import 가 편합니다.

smoke.mjs — 무료 키로 한 줄 호출
import 'dotenv/config'
import { GoogleGenAI } from '@google/genai'

const apiKey = process.env.GEMINI_API_KEY
const model = process.env.GEMINI_MODEL || 'gemini-2.5-flash'
if (!apiKey) {
  console.error('GEMINI_API_KEY missing')
  process.exit(1)
}

const ai = new GoogleGenAI({ apiKey })

const res = await ai.models.generateContent({
  model,
  contents: '한 문장으로 인사만 해 주세요. 10자 이내.',
})

const text = res.text ?? JSON.stringify(res).slice(0, 200)
console.log('ok', { model, preview: String(text).slice(0, 80) })
// usageMetadata 가 있으면 토큰 추적용으로 로그
if (res.usageMetadata) console.log('usage', res.usageMetadata)

quota-snapshot.md 템플릿 (수동 캡처 후 커밋)
# gemini-quota-snapshot  (배포 전 체크인)
- captured_at_kst: 2026-08-08 10:00
- project_id: your-gcp-project-id
- source: https://aistudio.google.com/rate-limit
- model: gemini-2.5-flash
- rpm: (화면 숫자)
- tpm: (화면 숫자)
- rpd: (화면 숫자)
- soft_rpm: floor(rpm * 0.7)
- soft_rpd: floor(rpd * 0.75)
- notes: 키 N개는 동일 프로젝트 합산 가정

# 운영 규칙
# 1) soft_* 만 코드에 넣는다 (실한도 직전까지 쓰지 않음)
# 2) 모델·티어 바뀌면 이 파일을 먼저 고친다
# 3) 2주마다 usageMetadata 합계를 아래에 붙인다

json-mode.mjs — JSON MIME + 로컬 검증
import 'dotenv/config'
import { GoogleGenAI } from '@google/genai'

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY })
const model = process.env.GEMINI_MODEL || 'gemini-2.5-flash'

const prompt = `다음 이슈를 JSON만 반환.
keys: severity(low|mid|high), summary(80자 이내), actions(문자열 배열 최대 3).
이슈: 배포 후 /api/health 가 간헐적 500.`

const res = await ai.models.generateContent({
  model,
  contents: prompt,
  config: {
    temperature: 0.1,
    maxOutputTokens: 256,
    responseMimeType: 'application/json',
  },
})

const raw = res.text || '{}'
let obj
try {
  obj = JSON.parse(raw)
} catch {
  // 업스트림 재호출 금지: 로컬에서 실패 처리
  console.error('parse_fail', raw.slice(0, 200))
  process.exit(2)
}

const ok =
  ['low', 'mid', 'high'].includes(obj.severity) &&
  typeof obj.summary === 'string' &&
  Array.isArray(obj.actions) &&
  obj.actions.length <= 3

if (!ok) {
  console.error('schema_fail', obj)
  process.exit(3)
}
console.log('structured_ok', obj)

quota-meter.mjs — 분당·일일 소프트 캡
// quota-meter.mjs
const softRpm = Number(process.env.SOFT_RPM || 10)
const softRpd = Number(process.env.SOFT_RPD || 1200)

// 단일 인스턴스 전제. 서버리스면 Redis/Upstash 로 교체
const state = {
  dayKey: '',
  dayCount: 0,
  windowStart: 0,
  windowCount: 0,
}

function ptDayKey(d = new Date()) {
  // RPD 리셋 안내용 키 (운영 로그용). 실제 리셋은 구글 측 기준.
  return d.toLocaleString('sv-SE', { timeZone: 'America/Los_Angeles' }).slice(0, 10)
}

export function assertQuota(n = 1) {
  const now = Date.now()
  const day = ptDayKey()
  if (state.dayKey !== day) {
    state.dayKey = day
    state.dayCount = 0
  }
  if (now - state.windowStart >= 60_000) {
    state.windowStart = now
    state.windowCount = 0
  }
  if (state.windowCount + n > softRpm) {
    const err = new Error('soft_rpm_exceeded')
    err.code = 429
    err.kind = 'soft_rpm'
    throw err
  }
  if (state.dayCount + n > softRpd) {
    const err = new Error('soft_rpd_exceeded')
    err.code = 429
    err.kind = 'soft_rpd'
    throw err
  }
  state.windowCount += n
  state.dayCount += n
  return {
    rpmLeft: softRpm - state.windowCount,
    rpdLeft: softRpd - state.dayCount,
    day,
  }
}

// 사용 예
// assertQuota(1)
// await callGemini(...)
// 업스트림 429 와 soft_* 를 로그 필드로 구분할 것

call-with-meter.mjs — 미터 + 업스트림 호출 뼈대
import 'dotenv/config'
import { GoogleGenAI } from '@google/genai'
import { assertQuota } from './quota-meter.mjs'

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY })
const model = process.env.GEMINI_MODEL || 'gemini-2.5-flash'

export async function generateOnce(userText) {
  const budget = assertQuota(1)
  try {
    const res = await ai.models.generateContent({
      model,
      contents: userText,
      config: { maxOutputTokens: 256, temperature: 0.2 },
    })
    return {
      text: res.text,
      usage: res.usageMetadata || null,
      budget,
      upstream: 'ok',
    }
  } catch (e) {
    // 구글 측 한도/네트워크와 soft 캡을 로그에서 구분
    const status = e?.status || e?.code || 'unknown'
    console.error('gemini_call_fail', { status, message: String(e.message || e), budget })
    throw e
  }
}

// CLI 테스트: node call-with-meter.mjs
if (import.meta.url === `file://${process.argv[1]}`) {
  const out = await generateOnce('무료 티어 한도 테스트. 한 줄만.')
  console.log(out)
}

backoff.mjs — 상한 있는 재시도
function sleep(ms) {
  return new Promise((r) => setTimeout(r, ms))
}

export async function withBackoff(fn, { maxAttempts = 3, baseMs = 800 } = {}) {
  let last
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn(attempt)
    } catch (e) {
      last = e
      const status = e?.status || e?.code
      const soft = e?.kind === 'soft_rpm' || e?.kind === 'soft_rpd'
      if (soft) throw e // 소프트 캡은 재시도 금지
      if (status !== 429 && status !== 503) throw e
      if (attempt === maxAttempts) break
      const jitter = Math.floor(Math.random() * 200)
      const wait = baseMs * 2 ** (attempt - 1) + jitter
      console.warn('retry', { attempt, wait, status })
      await sleep(wait)
    }
  }
  throw last
}

// 사용
// await withBackoff(() => generateOnce(text), { maxAttempts: 3 })

capacity.mjs — 일일 사용자 액션 상한 계산
// capacity.mjs  — 숫자는 연습용. softRpd 는 스냅샷 값으로 교체
const softRpd = Number(process.env.SOFT_RPD || 1200)
const callsPerAction = Number(process.env.CALLS_PER_ACTION || 3)
const reserveForOps = 50 // 관리자·배포 검증용 여유

const userActionsPerDay = Math.floor((softRpd - reserveForOps) / callsPerAction)
const peakUsersIf5Actions = Math.floor(userActionsPerDay / 5)

console.log({
  softRpd,
  callsPerAction,
  userActionsPerDay,
  peakUsersIf5Actions,
  tip: '에이전트 단수를 줄이면 한도가 선형으로 늘어납니다',
})

cost-scenario.mjs — USD → 원화·부가세 시나리오
// cost-scenario.mjs  — 숫자는 예시. 배포 전 공식 Pricing 으로 교체
const USD_KRW = 1400
const VAT_RATE = 0.10 // 카드 명세 기준이 다를 수 있음 → 시나리오용
// 예시: Flash 계열 근사 (1M 토큰당 USD) — 반드시 공식 표로 교체
const PRICE = {
  flash_lite: { in: 0.30, out: 2.50 },
  flash: { in: 0.50, out: 3.00 },
}

function monthlyUsd(model, inTokens, outTokens) {
  const p = PRICE[model]
  return (inTokens / 1e6) * p.in + (outTokens / 1e6) * p.out
}

function toKrw(usd, withVat = true) {
  let krw = usd * USD_KRW
  if (withVat) krw *= 1 + VAT_RATE
  return Math.round(krw)
}

const scenarios = [
  ['flash_lite', 8_000_000, 1_500_000],
  ['flash', 8_000_000, 1_500_000],
  ['flash_lite', 30_000_000, 6_000_000],
]

for (const [model, inn, out] of scenarios) {
  const usd = monthlyUsd(model, inn, out)
  console.log(model, `USD ${usd.toFixed(2)}`, `KRW~${toKrw(usd)} (부가세 시나리오 포함)`)
}
// 출력을 스프레드시트에 붙이고, 카드 명세 1회와 대조