제미나이 무료 API, 키 발급, 분당 한도, 백오프 코드 | AI Studio 첫 호출 따라 하는 법은?

환경 변수 준비 (.env.local 예시, 깃 제외)
# .env.local  — 반드시 .gitignore 에 추가
GEMINI_API_KEY=여기에_발급받은_키

# 셸에서 1회 테스트
export GEMINI_API_KEY="$(grep GEMINI_API_KEY .env.local | cut -d= -f2-)"
echo "key length: ${#GEMINI_API_KEY}"

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

curl 스모크 테스트 (generateContent)
curl -sS "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -d '{
    "contents": [{
      "parts": [{ "text": "한 문장으로 자기소개해 줘" }]
    }]
  }' | head -c 800

# 기대: candidates[0].content.parts[0].text 가 보이는 JSON
# 401/403 → 키·권한 확인
# 404 → 모델 ID 가 계정·시점에 없음 (목록에서 다시 고르기)
# 429 → 한도 초과 (잠시 대기 또는 모델 변경)

Node 최소 호출 (@google/genai 예시)
// npm i @google/genai
import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

export async function draftOneLine(prompt) {
  if (!process.env.GEMINI_API_KEY) {
    throw new Error('GEMINI_API_KEY missing');
  }
  const res = await ai.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: prompt,
  });
  const text = res.text ?? '';
  if (!text) throw new Error('empty model response');
  return text.trim();
}

// node --env-file=.env.local scripts/smoke-gemini.mjs
console.log(await draftOneLine('사이드 프로젝트 소개 문장 하나'));

Next.js Route Handler 스케치 (서버 전용)
// app/api/draft/route.js  (서버에서만 실행)
import { NextResponse } from 'next/server';
import { draftOneLine } from '@/lib/gemini';

export async function POST(req) {
  const body = await req.json().catch(() => ({}));
  const prompt = String(body.prompt || '').slice(0, 2000);
  if (!prompt) {
    return NextResponse.json({ error: 'prompt required' }, { status: 400 });
  }
  try {
    const text = await draftOneLine(prompt);
    return NextResponse.json({ text });
  } catch (e) {
    const msg = e?.message || 'upstream error';
    const status = /429|RESOURCE_EXHAUSTED/i.test(msg) ? 429 : 502;
    return NextResponse.json({ error: msg }, { status });
  }
}

지수 백오프 with 지터 (429 전용)
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/i.test(s);
}

/** maxAttempts 포함 총 시도 횟수. 429만 재시도. */
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;
}

// 사용
// const text = await withBackoff(() => draftOneLine(prompt));

프로세스 내 분당 스로틀 (간단 실습용)
/** 단일 프로세스 한정. 서버리스 다중 인스턴스면 Redis 등으로 공유 필요 */
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); // AI Studio 표보다 여유 있게
export async function draftSafe(prompt) {
  await gate();
  return withBackoff(() => draftOneLine(prompt));
}

일일 호출 카운터 (파일 기반 실습)
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) {
  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 >= 0.7) {
    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;
}