Skip to main content

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.

You can integrate Lumenfall with any programming language or tool that supports HTTP requests. This guide shows how to use the API directly without an SDK.

​
Base URL

All API requests should be made to: 
https://api.lumenfall.ai/openai/v1

​
Authentication

Include your API key in the Authorization header: 
Authorization: Bearer lmnfl_your_api_key

​
Generate images

Make a POST request to /images/generations: 
curl https://api.lumenfall.ai/openai/v1/images/generations \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "prompt": "A serene mountain landscape at sunset with dramatic clouds",
    "n": 1,
    "size": "1024x1024"
  }'

​
Response

{
  "created": 1702345678,
  "data": [
    {
      "url": "https://media.lumenfall.ai/abc123.png",
      "revised_prompt": "A serene mountain landscape at sunset with dramatic clouds and golden light"
    }
  ]
}

​
Request parameters

ParameterTypeDefaultDescription
modelstringrequiredModel ID (e.g., gemini-3-pro-image, gpt-image-1.5, flux.2-max)
promptstringrequiredText description of the desired image
ninteger1Number of images to generate (1-10)
sizestring1024x1024Image dimensions
qualitystringstandardImage quality (standard or hd)
response_formatstringurlResponse format (url or b64_json)
stylestringvividImage style (vivid or natural)

​
Get base64 response

curl https://api.lumenfall.ai/openai/v1/images/generations \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1.5",
    "prompt": "A cute robot",
    "response_format": "b64_json"
  }'

​
Passing additional parameters

Include any additional parameters in the JSON request body: 
curl https://api.lumenfall.ai/openai/v1/images/generations \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "prompt": "A capybara relaxing in a hot spring",
    "size": "1024x1024",
    "seed": 12345,
    "custom_provider_param": "value"
  }'
Additional parameters are passed directly to the upstream provider. Check the provider’s documentation for supported parameters.

​
Edit images

Make a POST request to /images/edits with multipart form data: 
curl https://api.lumenfall.ai/openai/v1/images/edits \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -F "image=@original.png" \
  -F "prompt=Add a rainbow in the sky" \
  -F "model=gpt-image-1.5" \
  -F "size=1024x1024"

​
With a mask

Provide a mask to specify which areas should be edited: 
curl https://api.lumenfall.ai/openai/v1/images/edits \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -F "image=@original.png" \
  -F "mask=@mask.png" \
  -F "prompt=A sunlit indoor lounge area with a pool" \
  -F "model=gpt-image-1.5" \
  -F "size=1024x1024"

​
List models

Get all available models: 
curl https://api.lumenfall.ai/openai/v1/models \
  -H "Authorization: Bearer $LUMENFALL_API_KEY"
Response: 
{
  "object": "list",
  "data": [
    {
      "id": "gemini-3-pro-image",
      "object": "model",
      "created": 1702345678,
      "owned_by": "lumenfall"
    },
    {
      "id": "gpt-image-1.5",
      "object": "model",
      "created": 1702345678,
      "owned_by": "lumenfall"
    }
  ]
}

​
Get a specific model

curl https://api.lumenfall.ai/openai/v1/models/gemini-3-pro-image \
  -H "Authorization: Bearer $LUMENFALL_API_KEY"

​
Estimate costs (dry run)

Add ?dryRun=true to get a cost estimate without generating: 
curl "https://api.lumenfall.ai/openai/v1/images/generations?dryRun=true" \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "prompt": "A test prompt",
    "size": "1024x1024"
  }'
Response: 
{
  "estimated": true,
  "model": "gemini-3-pro-image",
  "provider": "vertex",
  "total_cost_micros": 40000,
  "currency": "USD"
}

​
Response headers

Lumenfall includes useful headers in every response:
HeaderDescription
X-Lumenfall-ProviderThe provider that handled the request
X-Lumenfall-ModelThe model that was used
X-Lumenfall-Request-IdUnique request identifier for debugging

​
Error handling

​
Error response format

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "AUTHENTICATION_FAILED"
  }
}

​
HTTP status codes

StatusCodeDescription
400INVALID_REQUESTInvalid request parameters
401AUTHENTICATION_FAILEDInvalid or missing API key
402INSUFFICIENT_BALANCEAccount balance too low
404MODEL_NOT_FOUNDRequested model doesn’t exist
429RATE_LIMITEDToo many requests
502ALL_PROVIDERS_EXHAUSTEDAll providers failed

​
Next steps

API Reference

Explore the full API documentation.

Authentication

Learn more about API key management.