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

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