제미나이 무료 API, 일일 RPD 게이트, 스트리밍, 유료 전환 | 서버에 붙이는 실습 순서는?

환경 변수 준비 (.env, 깃 제외)
# .env  — .gitignore 에 반드시 추가
GEMINI_API_KEY=여기에_발급받은_키
GEMINI_MODEL=gemini-2.5-flash
# 일일 소프트 캡 (AI Studio 실한도보다 낮게 잡기)
GEMINI_RPD_SOFT_CAP=80
GEMINI_RPM_SOFT_CAP=8

# 셸 1회 로드
set -a; source .env; set +a
echo "key_len=${#GEMINI_API_KEY} model=$GEMINI_MODEL"

# 실수 커밋 여부 (출력되면 즉시 폐기·재발급)
git grep -n "AIza" || echo "no key string in repo (good)"

Python 동기 호출 (requests)
import os, json, urllib.request

API_KEY = os.environ["GEMINI_API_KEY"]
MODEL = os.environ.get("GEMINI_MODEL", "gemini-2.5-flash")
URL = f"https://generativelanguage.googleapis.com/v1beta/models/{MODEL}:generateContent"

body = {
    "contents": [{"parts": [{"text": "한 문장으로 서버 상태 점검 메시지를 써 줘."}]}],
    "generationConfig": {"maxOutputTokens": 128, "temperature": 0.2},
}
req = urllib.request.Request(
    URL,
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Content-Type": "application/json",
        "x-goog-api-key": API_KEY,
    },
    method="POST",
)
with urllib.request.urlopen(req, timeout=60) as res:
    data = json.loads(res.read().decode("utf-8"))

text = data["candidates"][0]["content"]["parts"][0]["text"]
usage = data.get("usageMetadata", {})
print("text:", text.strip())
print("usage:", usage)
# 401/403 → 키·권한 / 404 → 모델 ID / 429 → 한도

Python 스트리밍 (streamGenerateContent)
import os, json, urllib.request

API_KEY = os.environ["GEMINI_API_KEY"]
MODEL = os.environ.get("GEMINI_MODEL", "gemini-2.5-flash")
URL = (
    f"https://generativelanguage.googleapis.com/v1beta/models/{MODEL}"
    f":streamGenerateContent?alt=sse"
)

body = {
    "contents": [{"parts": [{"text": "세 문장으로 배포 체크리스트를 말해 줘."}]}],
}
req = urllib.request.Request(
    URL,
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Content-Type": "application/json",
        "x-goog-api-key": API_KEY,
        "Accept": "text/event-stream",
    },
    method="POST",
)

with urllib.request.urlopen(req, timeout=120) as res:
    buf = b""
    while True:
        chunk = res.read(256)
        if not chunk:
            break
        buf += chunk
        while b"\n" in buf:
            line, buf = buf.split(b"\n", 1)
            line = line.decode("utf-8", errors="ignore").strip()
            if not line.startswith("data:"):
                continue
            payload = line[5:].strip()
            if not payload or payload == "[DONE]":
                continue
            try:
                obj = json.loads(payload)
            except json.JSONDecodeError:
                continue
            parts = (
                obj.get("candidates", [{}])[0]
                .get("content", {})
                .get("parts", [])
            )
            for p in parts:
                t = p.get("text")
                if t:
                    print(t, end="", flush=True)
print()

RPD 소프트 게이트 (Python)
import json, os, time
from datetime import datetime, timezone, timedelta
from pathlib import Path

# 태평양 시간 근사: 서머타임 여부는 zoneinfo 로 교체 권장
PT = timezone(timedelta(hours=-8))
STATE = Path(os.environ.get("GEMINI_QUOTA_FILE", ".gemini_quota.json"))
SOFT_CAP = int(os.environ.get("GEMINI_RPD_SOFT_CAP", "80"))

def pt_day() -> str:
    return datetime.now(PT).strftime("%Y-%m-%d")

def load_state():
    if not STATE.exists():
        return {"day": pt_day(), "count": 0}
    data = json.loads(STATE.read_text(encoding="utf-8"))
    if data.get("day") != pt_day():
        return {"day": pt_day(), "count": 0}
    return data

def save_state(data):
    STATE.write_text(json.dumps(data), encoding="utf-8")

def acquire_slot() -> dict:
    """호출 직전에 호출. allowed=False 면 업스트림 요청 금지."""
    st = load_state()
    if st["count"] >= SOFT_CAP:
        return {
            "allowed": False,
            "count": st["count"],
            "cap": SOFT_CAP,
            "retry_hint": "PT 자정 이후 또는 유료 티어 검토",
        }
    st["count"] += 1
    save_state(st)
    return {"allowed": True, "count": st["count"], "cap": SOFT_CAP}

# 사용 예
slot = acquire_slot()
if not slot["allowed"]:
    raise SystemExit(f"soft RPD cap: {slot}")
# ... 여기서 generateContent / stream 호출 ...
print("quota", slot)

Express 서버 프록시 (RPM + RPD 가드)
// server.mjs  (Node 18+)
import express from "express";
import fs from "fs";
import path from "path";

const app = express();
app.use(express.json({ limit: "32kb" }));

const KEY = process.env.GEMINI_API_KEY;
const MODEL = process.env.GEMINI_MODEL || "gemini-2.5-flash";
const RPM = Number(process.env.GEMINI_RPM_SOFT_CAP || 8);
const RPD = Number(process.env.GEMINI_RPD_SOFT_CAP || 80);
const STATE = process.env.GEMINI_QUOTA_FILE || ".gemini_quota.json";

// 프로세스 메모리 RPM (단일 인스턴스용)
const rpmHits = new Map(); // ip -> timestamps[]

function allowRpm(ip) {
  const now = Date.now();
  const windowMs = 60_000;
  const arr = (rpmHits.get(ip) || []).filter((t) => now - t < windowMs);
  if (arr.length >= RPM) return false;
  arr.push(now);
  rpmHits.set(ip, arr);
  return true;
}

function ptDay() {
  // 간단 근사: UTC-8. 운영에서는 Temporal/ luxon 권장
  const d = new Date(Date.now() - 8 * 3600_000);
  return d.toISOString().slice(0, 10);
}

function takeRpd() {
  let st = { day: ptDay(), count: 0 };
  try {
    st = JSON.parse(fs.readFileSync(STATE, "utf8"));
  } catch {}
  if (st.day !== ptDay()) st = { day: ptDay(), count: 0 };
  if (st.count >= RPD) return { ok: false, st };
  st.count += 1;
  fs.writeFileSync(STATE, JSON.stringify(st));
  return { ok: true, st };
}

app.post("/api/gemini/chat", async (req, res) => {
  const ip = req.headers["x-forwarded-for"]?.toString().split(",")[0] || req.ip;
  if (!KEY) return res.status(500).json({ error: "missing_key" });
  if (!allowRpm(ip)) return res.status(429).json({ error: "rpm_soft_cap" });
  const rpd = takeRpd();
  if (!rpd.ok) return res.status(429).json({ error: "rpd_soft_cap", ...rpd.st });

  const prompt = String(req.body?.prompt || "").slice(0, 2000);
  if (!prompt) return res.status(400).json({ error: "empty_prompt" });

  const url = `https://generativelanguage.googleapis.com/v1beta/models/${MODEL}:generateContent`;
  const r = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-goog-api-key": KEY,
    },
    body: JSON.stringify({
      contents: [{ parts: [{ text: prompt }] }],
      generationConfig: { maxOutputTokens: 512, temperature: 0.3 },
    }),
  });

  const data = await r.json().catch(() => ({}));
  if (!r.ok) {
    // 업스트림 429는 소프트 캡과 구분해 로그
    console.error("upstream", r.status, JSON.stringify(data).slice(0, 400));
    return res.status(r.status === 429 ? 429 : 502).json({
      error: "upstream_error",
      status: r.status,
    });
  }

  const text =
    data?.candidates?.[0]?.content?.parts?.[0]?.text || "";
  res.json({
    text,
    usage: data.usageMetadata || null,
    quota: rpd.st,
  });
});

app.listen(8787, () => console.log("gemini proxy on :8787"));

JSON 모드 골격 (REST generationConfig)
{
  "contents": [{
    "parts": [{
      "text": "다음 이슈를 분류해 JSON만 반환. keys: severity(low|mid|high), summary(80자 이내), actions(문자열 배열 최대 3)."
    }]
  }],
  "generationConfig": {
    "temperature": 0.1,
    "maxOutputTokens": 256,
    "responseMimeType": "application/json"
  }
}

# 호출 후
# obj = json.loads(text)
# assert obj["severity"] in ("low", "mid", "high")

월 비용 시나리오 (USD → 원화, 부가세 가정)
# cost_scenario.py  — 숫자는 예시. 배포 전 공식 Pricing 으로 교체
USD_KRW = 1400          # 조회 시점 환율
VAT_RATE = 0.10         # 카드 명세 기준이 다를 수 있음 → 시나리오용
# 예시: Flash-Lite 계열 근사 (1M 토큰당 USD) — 반드시 공식 표로 교체
PRICE = {
    "flash_lite": {"in": 0.30, "out": 2.50},
    "flash": {"in": 0.50, "out": 3.00},
}

def monthly_usd(model: str, in_tokens: int, out_tokens: int) -> float:
    p = PRICE[model]
    return (in_tokens / 1_000_000) * p["in"] + (out_tokens / 1_000_000) * p["out"]

def to_krw(usd: float, with_vat: bool = True) -> int:
    krw = usd * USD_KRW
    if with_vat:
        krw *= (1 + VAT_RATE)
    return int(round(krw))

# 2주 실측을 30일로 환산한 가정 예
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 model, inn, out in scenarios:
    usd = monthly_usd(model, inn, out)
    print(model, f"USD {usd:.2f}", f"KRW~{to_krw(usd)} (부가세 시나리오 포함)")

# 출력 예시를 스프레드시트에 붙이고, 카드 명세 1회와 대조