Skip to main content
The Lumenfall API is OpenAI-compatible, meaning you can use existing OpenAI SDKs by simply changing the base URL to https://api.lumenfall.ai/openai/v1.

​
Base URL

​
Authentication

All API requests require a Bearer token in the Authorization header:
Get your API key from the Lumenfall dashboard.

​
Request format

All requests should include:
  • Content-Type: application/json header
  • JSON request body (for POST requests)

​
Response format

All responses follow the OpenAI response format. Successful responses return JSON with the requested data. Error responses include an error object:

​
Error codes

​
Rate limits

Lumenfall does not impose strict per-request rate limits. Your usage is governed by your account balance - requests are processed as long as you have sufficient credits. For prepaid accounts, ensure you have enough balance or enable auto top-up to avoid interruptions.

​
Dry run mode

Add ?dryRun=true to any request to get a cost estimate without executing it. See Cost estimation for details and response format.

​
Record & Replay

Capture a real image or video response once and replay it back for free on later calls, or skip the provider entirely and get an instant mock response in the right shape. Turn it on per request with a header, or set a default on an API key. Two headers control it:
  • X-Lumenfall-Replay sets the activation: record, replay-or-mock, replay-or-error, replay-or-live, replay-or-record, or mock. Omit it (with no key default) to run the request normally.
  • X-Lumenfall-Replay-Match sets how a recording is matched: standard (the default), strict, specific, or pinned.
Replay applies to the image and video generation endpoints, not chat completions. See the full Record & Replay documentation for activations, match strategies, latency simulation, and response signals.

​
Response metadata

All media generation responses include a metadata object with provider routing details and the effective cost of the request. For videos, cost fields update as the job progresses — cost_estimate while in progress, cost once completed. See Billing for details.