A Bun and Hono service on Cloud Run. It has no database.
Request flowβ
- API Gateway forwards
/muse/* to the service. Cloud Run only accepts calls from the gateway.
- 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.
- 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.
| In | Out |
|---|
The customer's photo (JPEG or PNG, base64, up to 7 MB), a product image from cdn.shopify.com, and the customer's Shopify ID | The generated image |
| Response | When |
|---|
200 | An image, as image/png or image/jpeg |
400 | The photo isn't a JPEG or PNG, or the body is invalid |
422 | Gemini returned no image for these photos |
429 | The customer has used their 25 try-ons for the day. Retry-After gives the seconds until UTC midnight |
502 | Gemini failed |
503 | Redis is unavailable, so the cap can't be checked. Try-on never runs uncapped |
Palette generationβ
| In | Out |
|---|
1 to 3 photos (JPEG or PNG, longest side up to 1024px, up to 4 MiB each), as multipart/form-data | A 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.
| Response | When |
|---|
200 | The palette |
400 | A photo is outside the limits |
422 | Gemini found no usable colors |
502 | Gemini or the catalog failed |
Cachingβ
| What | Kept for |
|---|
| Gemini's colors for a set of photos | 7 days |
| The color catalog | 1 hour |
| Try-on counts per customer | Until 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.