> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumenfall.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference for the Lumenfall API - text, image, and video generation

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

```
https://api.lumenfall.ai/openai/v1
```

## Authentication

All API requests require a Bearer token in the `Authorization` header:

```bash theme={null}
Authorization: Bearer lmnfl_your_api_key
```

Get your API key from the [Lumenfall dashboard](https://lumenfall.ai/app).

## 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:

```json theme={null}
{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "AUTHENTICATION_FAILED"
  }
}
```

## Error codes

| Code                      | HTTP Status | Description                                |
| ------------------------- | ----------- | ------------------------------------------ |
| `AUTHENTICATION_FAILED`   | 401         | Invalid or missing API key                 |
| `INSUFFICIENT_BALANCE`    | 402         | Account balance too low (prepaid accounts) |
| `INVALID_REQUEST`         | 400         | Malformed request or invalid parameters    |
| `MODEL_NOT_FOUND`         | 404         | Requested model does not exist             |
| `MODEL_DISABLED`          | 404         | Model is currently disabled                |
| `RATE_LIMITED`            | 429         | Too many requests                          |
| `ALL_PROVIDERS_EXHAUSTED` | 502         | All providers failed to handle the request |
| `UPSTREAM_ERROR`          | varies      | A provider returned an error               |

## 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](/billing#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](/api-reference/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](/replay) 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](/billing#effective-cost-on-responses) for details.