HTTP / cURL

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

Parameter	Type	Default	Description
`model`	string	required	Model ID (e.g., `gemini-3-pro-image`, `gpt-image-1.5`, `flux.2-max`)
`prompt`	string	required	Text description of the desired image
`n`	integer	`1`	Number of images to generate (1-10)
`size`	string	`1024x1024`	Image dimensions
`quality`	string	`standard`	Image quality (`standard` or `hd`)
`response_format`	string	`url`	Response format (`url` or `b64_json`)
`style`	string	`vivid`	Image 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:

Header	Description
`X-Lumenfall-Provider`	The provider that handled the request
`X-Lumenfall-Model`	The model that was used
`X-Lumenfall-Request-Id`	Unique request identifier for debugging

Error handling

Error response format

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

HTTP status codes

Status	Code	Description
400	`INVALID_REQUEST`	Invalid request parameters
401	`AUTHENTICATION_FAILED`	Invalid or missing API key
402	`INSUFFICIENT_BALANCE`	Account balance too low
404	`MODEL_NOT_FOUND`	Requested model doesn’t exist
429	`RATE_LIMITED`	Too many requests
502	`ALL_PROVIDERS_EXHAUSTED`	All providers failed

Getting started

Core concepts

Dashboard

Client libraries

Integrations

Base URL

Authentication

Generate images

Response

Request parameters

Get base64 response

Passing additional parameters

Edit images

With a mask

List models

Get a specific model

Estimate costs (dry run)

Response headers

Error handling

Error response format

HTTP status codes

Next steps

API Reference

Authentication

Getting started

Core concepts

Dashboard

Client libraries

Integrations

​Base URL

​Authentication

​Generate images

​Response

​Request parameters

​Get base64 response

​Passing additional parameters

​Edit images

​With a mask

​List models

​Get a specific model

​Estimate costs (dry run)

​Response headers

​Error handling

​Error response format

​HTTP status codes

​Next steps

API Reference

Authentication

Base URL

Authentication

Generate images

Response

Request parameters

Get base64 response

Passing additional parameters

Edit images

With a mask

List models

Get a specific model

Estimate costs (dry run)

Response headers

Error handling

Error response format

HTTP status codes

Next steps