Faceplacer API

Faceplacer is an AI-powered placeholder avatar service, and the core architectural decision is permanent caching. Every avatar is generated once and cached forever. The URL is deterministic: given the same parameters, you always get the same image. This matters for a placeholder service because consumers embed these URLs in their markup and expect them to resolve consistently. If the same URL returned a different face on every request, it would break visual regression tests, design reviews, and any workflow where consistency matters.

The CDN-first architecture means the generation step is a one-time cost per unique parameter combination. A request comes in, the CDN checks its cache, and if the image exists, it serves it directly without hitting the origin. On a cache miss, the origin generates the avatar using fal.ai, stores it permanently, and returns it with aggressive cache headers. After the first request, that avatar is effectively static content. The generation cost is amortized to zero over time as the cache fills. For a service that might get embedded in hundreds of sites, this is the difference between a manageable API bill and a runaway one.

Deterministic URLs are the key design choice that makes everything else work. The URL encodes the parameters: style, seed, size, and any customization options. The same parameters always produce the same hash, which maps to the same cached file. This means developers can use Faceplacer URLs in their code knowing they'll get the same avatar every time, the same way they'd use a static image URL. There's no API key required for reads, no authentication overhead, no rate limiting on cached responses. Generation requests do require authentication and are rate-limited, but the common case of serving cached avatars is completely open and fast.

The lesson from building Faceplacer is that a placeholder service has fundamentally different requirements from a generation service. A generation service optimizes for variety and quality. A placeholder service optimizes for consistency, speed, and zero-friction integration. Developers should be able to drop a URL into an img tag and forget about it. Every architectural decision flows from that principle: deterministic URLs, permanent caching, CDN-first serving, no auth on reads. The AI generation is the interesting part technically, but the caching strategy is what makes it a useful product.