Skip to main content

Architecture

A Bun and Hono service on Cloud Run. It has no database.

Request flow​

  1. API Gateway forwards /muse/* to the service. Cloud Run only accepts calls from the gateway.
  2. Key check: the service confirms the caller's API key with the gateway's authorizer. If the authorizer can't be reached, the request fails with 503 rather than being let through.
  3. Routes validate the request and call Gemini. Palette generation also reads the color catalog from catalog-api.

Requests have a 10-second limit. Palette generation has 14 seconds and try-on 60, but API Gateway cuts every request off at 15 seconds.

Try-on​

InOut
The customer's photo (JPEG or PNG, base64, up to 7 MB), a product image from cdn.shopify.com, and the customer's Shopify IDThe generated image
ResponseWhen
200An image, as image/png or image/jpeg
400The photo isn't a JPEG or PNG, or the body is invalid
422Gemini returned no image for these photos
429The customer has used their 25 try-ons for the day. Retry-After gives the seconds until UTC midnight
502Gemini failed
503Redis is unavailable, so the cap can't be checked. Try-on never runs uncapped

Palette generation​

InOut
1 to 3 photos (JPEG or PNG, longest side up to 1024px, up to 4 MiB each), as multipart/form-dataA palette name, a description, and 6 to 8 Birdy Grey catalog colors

Gemini picks colors from the photos, then each is matched to the closest catalog color.

ResponseWhen
200The palette
400A photo is outside the limits
422Gemini found no usable colors
502Gemini or the catalog failed

Caching​

WhatKept for
Gemini's colors for a set of photos7 days
The color catalog1 hour
Try-on counts per customerUntil the end of the UTC day

If Redis fails, palette generation still works without the cache. Try-on doesn't, because the cap needs it.