Base URL
All API requests should be made to:https://api.lumenfall.ai/openai/v1
Authentication
Include your API key in theAuthorization 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"
}'
import requests
import os
response = requests.post(
"https://api.lumenfall.ai/openai/v1/images/generations",
headers={
"Authorization": f"Bearer {os.environ['LUMENFALL_API_KEY']}",
"Content-Type": "application/json"
},
json={
"model": "gemini-3-pro-image",
"prompt": "A serene mountain landscape at sunset with dramatic clouds",
"n": 1,
"size": "1024x1024"
}
)
data = response.json()
print(data["data"][0]["url"])
const response = await fetch(
"https://api.lumenfall.ai/openai/v1/images/generations",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.LUMENFALL_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "gemini-3-pro-image",
prompt: "A serene mountain landscape at sunset with dramatic clouds",
n: 1,
size: "1024x1024",
}),
}
);
const data = await response.json();
console.log(data.data[0].url);
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"os"
)
func main() {
payload := map[string]interface{}{
"model": "gemini-3-pro-image",
"prompt": "A serene mountain landscape at sunset with dramatic clouds",
"n": 1,
"size": "1024x1024",
}
body, _ := json.Marshal(payload)
req, _ := http.NewRequest(
"POST",
"https://api.lumenfall.ai/openai/v1/images/generations",
bytes.NewBuffer(body),
)
req.Header.Set("Authorization", "Bearer "+os.Getenv("LUMENFALL_API_KEY"))
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
data := result["data"].([]interface{})
first := data[0].(map[string]interface{})
fmt.Println(first["url"])
}
<?php
$apiKey = getenv('LUMENFALL_API_KEY');
$ch = curl_init('https://api.lumenfall.ai/openai/v1/images/generations');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
'model' => 'gemini-3-pro-image',
'prompt' => 'A serene mountain landscape at sunset with dramatic clouds',
'n' => 1,
'size' => '1024x1024'
])
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
echo $data['data'][0]['url'];
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"
}'
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"
import requests
import os
response = requests.post(
"https://api.lumenfall.ai/openai/v1/images/edits",
headers={
"Authorization": f"Bearer {os.environ['LUMENFALL_API_KEY']}"
},
files={
"image": open("original.png", "rb")
},
data={
"prompt": "Add a rainbow in the sky",
"model": "gpt-image-1.5",
"size": "1024x1024"
}
)
data = response.json()
print(data["data"][0]["url"])
const formData = new FormData();
formData.append("image", await fs.openAsBlob("original.png"));
formData.append("prompt", "Add a rainbow in the sky");
formData.append("model", "gpt-image-1.5");
formData.append("size", "1024x1024");
const response = await fetch(
"https://api.lumenfall.ai/openai/v1/images/edits",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.LUMENFALL_API_KEY}`,
},
body: formData,
}
);
const data = await response.json();
console.log(data.data[0].url);
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"
{
"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"
}'
{
"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 |
Next steps
API Reference
Explore the full API documentation.
Authentication
Learn more about API key management.