X-Lumenfall-Replay(the activation) sets the outcome: what you get on a hit and on a miss.X-Lumenfall-Replay-Match(the match) sets the lookup: how Lumenfall decides whether a recording matches.
replay-or-* activation works with any match strategy.
Activation: X-Lumenfall-Replay
The activation decides what happens, both when a recording is found and when one isn’t.
mock never touches a provider or storage. It synthesizes a well-formed response in the endpoint’s shape (including placeholder media), instantly and for free. Use it to build and demo your app before a real integration exists, to develop offline, or in CI where you just need a valid-shaped response on every call. replay-or-mock is the same synthesis used only as the fallback when a recording isn’t found.Match: X-Lumenfall-Replay-Match
The match strategy decides how Lumenfall looks for a recording. It is consulted only by the replay-or-* activations. off, record, and mock ignore it.
pinned and specific each require their companion header. Omitting it returns 400 (PINNED_MODE_REQUIRES_RECORDING / SPECIFIC_MODE_REQUIRES_FIELDS).
How matching works
When you replay, Lumenfall builds a match key from your request and looks for a recording with the same key.
The first four fields are always part of the key. The match strategy changes how the request hash is computed:
standardhashes the canonical parameters, ignoring fields that don’t change the nature of the request: the prompt, the response/output format, and (for text-to-image and text-to-video) reference media. Changing the prompt still matches; changing something that defines the generation (size, seed, quality) does not.stricthashes the exact request body bytes. Any change, even whitespace, produces a different key and won’t match.specifichashes only the fields you name inX-Lumenfall-Replay-Fields; everything else is ignored.pinnedskips hashing entirely and serves the recording named inX-Lumenfall-Replay-Recording.
Cross-provider matches
standard matching isn’t limited to the provider that created the recording. Because Lumenfall can route the same model to different providers, a recording made against one can satisfy a request that routes to another, as long as both resolve to the same model. Same-provider recordings are preferred; a cross-provider match is used only when there’s no same-provider hit.
This applies to standard only. strict and pinned stay within a single recording. When a cross-provider recording answers, the response carries X-Lumenfall-Provider-Used (whose recording served it) and, if the body was adapted to the requested provider’s shape, X-Lumenfall-Wire-Provider.
Latency simulation
By default a replay returns instantly. SetX-Lumenfall-Replay-Latency (per request, or as a key default) to make a replayed response take as long as the original did. Useful for testing loading states and timeouts.
real is capped at 60 seconds, a safety bound to match typical client timeouts. When the cap applies, the response carries X-Lumenfall-Warning: LATENCY_CLAMPED.Knowing what happened
Every replay-engaged response carries headers describing what happened, so a test can assert it never silently called the provider.
The result values map 1:1 to the activations, so you can assert exactly what happened: a
replay-or-live that hit reports replay; the same request on a miss reports live.
Errors
A
replay-or-error miss returns HTTP 404 with X-Lumenfall-Replay-Result: miss. Branch on that header, not the bare status. A provider’s own “model not found” 404 won’t carry it.
Only replay-or-error (and pinned / specific with a missing companion header) ever errors on a miss. replay-or-mock, replay-or-live, and replay-or-record always produce a response.