Gemini API × Stripe で組む AI SaaS 課金 — 使用量ベースの本番実装ガイド

# .env.local
# STRIPE_SECRET_KEY=sk_test_...
# stripe-cli を使う場合は事前に stripe login を実行
 
# 1) トークン用の Meter を作成
stripe meters create \
  --display-name "Gemini API Tokens" \
  --event-name "gemini_api_tokens_used" \
  --default-aggregation.formula sum \
  --customer-mapping.event-payload-key stripe_customer_id \
  --customer-mapping.type by_id \
  --value-settings.event-payload-key value

# 2) Pro プランのベース Price（定額）を作成
PROD_PRO=$(stripe products create -d name="Gemini SaaS Pro" -d type=service -j | jq -r '.id')
stripe prices create \
  --product "$PROD_PRO" \
  --unit-amount 98000 \
  --currency jpy \
  --recurring.interval month
 
# 3) Pro プランの従量課金 Price（Meter 紐付け）を作成
# 100,000 トークンあたり ¥150 → 1 トークンあたり ¥0.0015 = 1/1000 円単位で 0.15 銭
# Stripe では「1 単位あたりの価格」を tiered で表現すると分かりやすい
stripe prices create \
  --product "$PROD_PRO" \
  --currency jpy \
  --billing-scheme tiered \
  --tiers-mode graduated \
  --recurring.interval month \
  --recurring.usage-type metered \
  --recurring.meter "$METER_ID" \
  --tiers '[{"up_to":500000,"flat_amount":0},{"up_to":"inf","unit_amount_decimal":"0.0015"}]'

// src/lib/gemini.ts
import { GoogleGenerativeAI, type GenerativeModel } from "@google/generative-ai";
import { recordTokenUsage } from "./usage-store";
 
const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!);
 
export async function generateWithUsage(
  userId: string,
  prompt: string,
  modelName: string = "gemini-2.5-flash"
): Promise<{ text: string; totalTokens: number }> {
  const model: GenerativeModel = genAI.getGenerativeModel({ model: modelName });
 
  try {
    const result = await model.generateContent(prompt);
    // usageMetadata は SDK のバージョンによってフィールド名が異なる
    // 2026 年時点の @google/generative-ai では response.usageMetadata に格納される
    const usage = result.response.usageMetadata;
    const totalTokens = usage?.totalTokenCount ?? 0;
 
    // DB へ非同期で記録（API レスポンスをブロックしないため await しない選択肢もある）
    await recordTokenUsage({
      userId,
      promptTokens: usage?.promptTokenCount ?? 0,
      completionTokens: usage?.candidatesTokenCount ?? 0,
      totalTokens,
      model: modelName,
      occurredAt: new Date(),
    });
 
    return { text: result.response.text(), totalTokens };
  } catch (err) {
    // トークン計測に失敗してもユーザーへの応答は返す方針なら、
    // ここでログに記録するだけにとどめて throw しない選択もある
    console.error("[gemini] generation failed", { userId, err });
    throw err;
  }
}

// src/lib/usage-store.ts
import { sql } from "./db";
 
export type UsageRecord = {
  userId: string;
  promptTokens: number;
  completionTokens: number;
  totalTokens: number;
  model: string;
  occurredAt: Date;
};
 
export async function recordTokenUsage(rec: UsageRecord): Promise<void> {
  await sql`
    INSERT INTO token_usage (
      user_id, prompt_tokens, completion_tokens,
      total_tokens, model, occurred_at, reported_to_stripe
    ) VALUES (
      ${rec.userId}, ${rec.promptTokens}, ${rec.completionTokens},
      ${rec.totalTokens}, ${rec.model}, ${rec.occurredAt}, false
    )
  `;
}
 
// 未報告レコードを取得（バッチジョブ用）
export async function fetchUnreportedUsage(limit: number = 1000) {
  return sql<{ id: string; user_id: string; total_tokens: number; occurred_at: Date }[]>`
    SELECT id, user_id, total_tokens, occurred_at
    FROM token_usage
    WHERE reported_to_stripe = false
    ORDER BY occurred_at ASC
    LIMIT ${limit}
  `;
}
 
export async function markReported(ids: string[]): Promise<void> {
  if (ids.length === 0) return;
  await sql`
    UPDATE token_usage
    SET reported_to_stripe = true, reported_at = NOW()
    WHERE id = ANY(${ids})
  `;
}

// src/jobs/report-usage-to-stripe.ts
import Stripe from "stripe";
import { fetchUnreportedUsage, markReported } from "../lib/usage-store";
import { getStripeCustomerId } from "../lib/customer-store";
 
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2025-09-30.preview",
});
 
export async function reportUsageToStripe(): Promise<{
  reported: number;
  failed: number;
}> {
  const records = await fetchUnreportedUsage(1000);
  if (records.length === 0) return { reported: 0, failed: 0 };
 
  const reportedIds: string[] = [];
  let failed = 0;
 
  // ユーザーごとにまとめて送る（ペイロードを減らすため）
  const grouped = new Map<string, typeof records>();
  for (const r of records) {
    if (!grouped.has(r.user_id)) grouped.set(r.user_id, []);
    grouped.get(r.user_id)!.push(r);
  }
 
  for (const [userId, rows] of grouped) {
    const customerId = await getStripeCustomerId(userId);
    if (!customerId) {
      // Stripe 顧客と紐付いていないユーザーはスキップ（フリーユーザー等）
      reportedIds.push(...rows.map((r) => r.id));
      continue;
    }
 
    const totalTokens = rows.reduce((s, r) => s + r.total_tokens, 0);
 
    try {
      await stripe.billing.meterEvents.create({
        event_name: "gemini_api_tokens_used",
        // identifier を渡すと Stripe 側で重複排除してくれる（Idempotency Key の役割）
        identifier: `usage-${userId}-${rows[0].id}-${rows.at(-1)!.id}`,
        payload: {
          stripe_customer_id: customerId,
          value: String(totalTokens),
        },
        timestamp: Math.floor(rows.at(-1)!.occurred_at.getTime() / 1000),
      });
      reportedIds.push(...rows.map((r) => r.id));
    } catch (err) {
      console.error("[stripe-meter] report failed", { userId, err });
      failed += rows.length;
      // 失敗したバッチは next run でリトライされる（フラグを立てない）
    }
  }
 
  await markReported(reportedIds);
  return { reported: reportedIds.length, failed };
}

// src/app/api/stripe/webhook/route.ts (Next.js App Router)
import Stripe from "stripe";
import { NextResponse } from "next/server";
import { upsertSubscription, downgradeUser, markPaymentFailed } from "@/lib/billing";
 
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2025-09-30.preview",
});
const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!;
 
export async function POST(req: Request): Promise<Response> {
  const sig = req.headers.get("stripe-signature");
  const body = await req.text();
  if (!sig) return new NextResponse("missing signature", { status: 400 });
 
  let event: Stripe.Event;
  try {
    // Cloudflare Workers / Edge では非同期版を使う
    event = await stripe.webhooks.constructEventAsync(body, sig, webhookSecret);
  } catch (err) {
    console.error("[stripe-webhook] signature verify failed", err);
    return new NextResponse("invalid signature", { status: 400 });
  }
 
  // Idempotency: event.id を DB に記録して重複処理を防ぐ
  if (await isAlreadyProcessed(event.id)) {
    return NextResponse.json({ received: true, idempotent: true });
  }
 
  try {
    switch (event.type) {
      case "customer.subscription.created":
      case "customer.subscription.updated": {
        const sub = event.data.object as Stripe.Subscription;
        await upsertSubscription({
          customerId: sub.customer as string,
          subscriptionId: sub.id,
          status: sub.status,
          // items から定額プラン側の Price ID を取り出してティアを判定
          tier: detectTierFromItems(sub.items.data),
          currentPeriodEnd: new Date(sub.current_period_end * 1000),
        });
        break;
      }
      case "customer.subscription.deleted": {
        const sub = event.data.object as Stripe.Subscription;
        await downgradeUser(sub.customer as string);
        break;
      }
      case "invoice.payment_failed": {
        const invoice = event.data.object as Stripe.Invoice;
        await markPaymentFailed({
          customerId: invoice.customer as string,
          attemptCount: invoice.attempt_count ?? 0,
        });
        break;
      }
      default:
        // 想定外のイベントはログだけ残す（200 で返さないと Stripe がリトライし続ける）
        console.log("[stripe-webhook] unhandled event", event.type);
    }
    await markProcessed(event.id);
    return NextResponse.json({ received: true });
  } catch (err) {
    console.error("[stripe-webhook] handler failed", { type: event.type, err });
    // 5xx を返すと Stripe が指数バックオフで自動リトライしてくれる
    return new NextResponse("internal error", { status: 500 });
  }
}

// src/lib/feature-gate.ts
type Tier = "free" | "pro" | "team";
 
type FeatureMatrix = {
  [key in Tier]: {
    allowedModels: string[];
    monthlyTokenIncluded: number;
    visionEnabled: boolean;
    longContextEnabled: boolean; // 1M トークンコンテキストを使えるか
  };
};
 
export const FEATURES: FeatureMatrix = {
  free: {
    allowedModels: ["gemini-2.5-flash-lite"],
    monthlyTokenIncluded: 50_000,
    visionEnabled: false,
    longContextEnabled: false,
  },
  pro: {
    allowedModels: ["gemini-2.5-flash", "gemini-2.5-pro"],
    monthlyTokenIncluded: 500_000,
    visionEnabled: true,
    longContextEnabled: false,
  },
  team: {
    allowedModels: ["gemini-2.5-flash", "gemini-2.5-pro", "gemini-3-pro"],
    monthlyTokenIncluded: 5_000_000,
    visionEnabled: true,
    longContextEnabled: true,
  },
};
 
export class FeatureNotAllowedError extends Error {
  constructor(
    public readonly feature: string,
    public readonly currentTier: Tier,
    public readonly requiredTier: Tier
  ) {
    super(`feature "${feature}" requires "${requiredTier}", but user is on "${currentTier}"`);
  }
}
 
export function ensureModelAllowed(tier: Tier, model: string): void {
  if (!FEATURES[tier].allowedModels.includes(model)) {
    // 上位ティアで使えるかを判定して、UI に「Pro にアップグレードで利用可能」と返せるようにする
    const requiredTier = (Object.keys(FEATURES) as Tier[]).find((t) =>
      FEATURES[t].allowedModels.includes(model)
    );
    throw new FeatureNotAllowedError("model", tier, requiredTier ?? "team");
  }
}

// src/app/api/generate/route.ts
import { auth } from "@/lib/auth";
import { getUserTier } from "@/lib/billing";
import { ensureModelAllowed, FeatureNotAllowedError } from "@/lib/feature-gate";
import { generateWithUsage } from "@/lib/gemini";
 
export async function POST(req: Request) {
  const session = await auth();
  if (!session) return new Response("unauthorized", { status: 401 });
 
  const { prompt, model = "gemini-2.5-flash-lite" } = await req.json();
  const tier = await getUserTier(session.user.id);
 
  try {
    ensureModelAllowed(tier, model);
  } catch (err) {
    if (err instanceof FeatureNotAllowedError) {
      // クライアントが「アップグレードして使う」UI を出せるよう、必要ティアを返す
      return Response.json(
        { error: "upgrade_required", required_tier: err.requiredTier, current_tier: err.currentTier },
        { status: 402 }
      );
    }
    throw err;
  }
 
  const { text, totalTokens } = await generateWithUsage(session.user.id, prompt, model);
  return Response.json({ text, totalTokens });
}