Designing an Image Pipeline with Gemini Files API and Cloudflare R2 — Notes from Running a Wallpaper App

Idempotent retries through hash-keyed deduplication

The biggest source of waste in my old setup was retries that re-uploaded the same bytes. Rebuilt, retries now check at two layers:

• Workflow layer: deduplicates job submissions by fileHash
• Upload layer: checks the KV cache before issuing a real PUT to Files API

// src/lib/image-pipeline/worker.ts
type Job = { id: string; bytes: Uint8Array; mime: string };
 
export async function processJob(
  job: Job,
  env: Env,
): Promise<{ caption: string; tags: string[] }> {
  const file = await ensureGeminiFile(
    job.bytes,
    job.mime,
    env.IMG_KV,
    env.IMG_BUCKET,
    env.GEMINI_API_KEY,
  );
 
  // If we already have a Gemini answer for this hash, return it
  const resultKey = `caption:${file.fileHash}`;
  const cached = await env.IMG_KV.get(resultKey, "json");
  if (cached) return cached as { caption: string; tags: string[] };
 
  const genAI = new GoogleGenerativeAI(env.GEMINI_API_KEY);
  const model = genAI.getGenerativeModel({ model: "gemini-2.5-flash" });
  const resp = await model.generateContent([
    { fileData: { fileUri: file.fileUri, mimeType: job.mime } },
    { text: "Return a short caption and five distribution tags as JSON for this wallpaper image." },
  ]);
 
  const json = parseJsonLoosely(resp.response.text());
  await env.IMG_KV.put(resultKey, JSON.stringify(json), { expirationTtl: 90 * 86400 });
  return json;
}

The caption:{hash} cache lives for 90 days. If the same image arrives through another path, no Gemini call is made. In practice, duplicate submissions show up more often than you'd expect; this single cache cut my daily Gemini call count by roughly 22% on its own.

Rate limiting designed for failure, not for the happy path

Gemini API enforces RPM, TPM, and daily caps. With Flash you can still trip 429s if the workload spikes. On my busiest day, an unprotected queue spent 70% of the daily budget in a two-hour window in the afternoon.

The fix was a two-level backpressure setup:

1. Cloudflare Queues paces dispatching at the queue layer
2. The worker tracks in-flight concurrency and waits once on a 429 with exponential backoff

// src/lib/rate/dispatcher.ts
const MAX_INFLIGHT = 6;       // concurrent Gemini calls
const RPM_BUDGET = 480;       // safe RPM ceiling
 
let inflight = 0;
let calledInWindow = 0;
let windowStart = Date.now();
 
export async function withRateLimit<T>(fn: () => Promise<T>): Promise<T> {
  while (inflight >= MAX_INFLIGHT) {
    await sleep(50);
  }
  const now = Date.now();
  if (now - windowStart >= 60_000) {
    windowStart = now;
    calledInWindow = 0;
  }
  if (calledInWindow >= RPM_BUDGET) {
    const wait = 60_000 - (now - windowStart);
    await sleep(Math.max(wait, 100));
  }
  inflight++;
  calledInWindow++;
  try {
    return await fn();
  } catch (e: any) {
    if (e?.status === 429) {
      await sleep(2_000 + Math.random() * 3_000);
      return await fn(); // single extra retry
    }
    throw e;
  } finally {
    inflight--;
  }
}
 
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

This is not sophisticated, but it stopped the cascade of 429-driven duplicate uploads. Re-upload spend dropped from about ¥7,800 in the old pipeline to ¥3,200 in April. Gemini processing cost did not go up; the cache actually pulled it down. The whole delta is wasted retries that no longer happen.

A three-metric dashboard I can actually keep up with

I tried to keep the dashboard small enough that I won't stop looking at it. Three metrics seem to be enough:

Writes go into Cloudflare Analytics Engine. Even with that minimal setup, patterns like "Friday evening error spikes" and "end-of-month cost bumps" became visible.

// src/lib/metrics/report.ts
export async function reportEvent(
  env: Env,
  event: "upload" | "skip" | "gemini_call" | "gemini_429" | "gemini_5xx",
  costYen?: number,
) {
  env.METRICS.writeDataPoint({
    indexes: [event],
    blobs: [new Date().toISOString().slice(0, 13)], // YYYY-MM-DDTHH
    doubles: [costYen ?? 0],
  });
}

I write events at hour-level granularity. Per-day is too coarse for debugging, per-minute blows up storage in a few months. Hour buckets are the sweet spot for me.

A three-month cost recap

Here are the numbers from my own runs, side by side. Monthly downloads were flat across these three months, so the difference reflects the pipeline change.

Per-image processing cost improved roughly 2.4x from February to April. The biggest single contributor was the result cache; the March-to-April delta is almost entirely explained by it.

Lined up against AdMob revenue per image, image-processing cost now sits at about 1.2% of revenue. As an indie developer, that's the headroom that lets me say yes to adding more images without hesitation.

Three potholes the first 30 days exposed

A few things only surfaced once the rebuilt pipeline was carrying real traffic.

The first: don't trust R2 head() too much. R2 is eventually consistent on a short window, and during intense bursts I saw a few head() misses right after a put. Since put is idempotent on the same key, the cleaner fix on hot paths was to skip head() and always put.

The second: don't use a raw hash as the Files API displayName. The first version put the bare SHA-256 there, which made the file list useless for debugging. Switching to <category>-<hash[:8]> made admin scans far easier.

The third, and most painful: a five-minute expiry margin is sometimes too small. During heavy late-night runs, Gemini occasionally queued requests for around 90 seconds, eating into the buffer. Rounding the TTL down to 47 hours instead has held up since, but I'd recommend giving yourself a longer cushion than you think you need.

A small suggestion if you want to try this shape

If you're running a few hundred to a few thousand images per day on an indie or small-team app, this shape should fit you well. The biggest single win, even before adding the KV cache, is putting R2 in front of Files API. That step alone usually moves the upload ratio noticeably.

Coming from a family of temple carpenters, I keep coming back to the same value when I think about engineering: never do the same work twice, and rebuild carefully when you can. The whole point of this pipeline is exactly that. Thanks for reading this far, and I hope these notes help on your own runs.