Skip to main content
This guide walks you through making your first API call using Lumenfall. You can generate text with chat completions, create images, or generate videos - all through the same OpenAI-compatible API.

​
Prerequisites

​
Chat completion

Send a message and get a text response. Text models are powered by OpenRouter, so you can use any model available there. 
curl https://api.lumenfall.ai/openai/v1/chat/completions \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3-flash-preview",
    "messages": [
      {"role": "user", "content": "Tell me a fun fact about capybaras"}
    ]
  }'

​
Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1702345678,
  "model": "google/gemini-3-flash-preview",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Capybaras are the world's largest rodents and can hold their breath underwater for up to five minutes!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 24,
    "total_tokens": 39
  }
}

​
Generate an image

Lumenfall uses an OpenAI-compatible API, so you can use any OpenAI SDK or make direct HTTP requests. 
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

The API returns image URLs in the standard OpenAI format: 
{
  "created": 1702345678,
  "data": [
    {
      "url": "https://..."
    }
  ]
}

​
Generate a video

Video generation is asynchronous. You submit a request and get back an ID, then poll for the result. 
# Submit the video generation request
curl -X POST https://api.lumenfall.ai/openai/v1/videos \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A capybara peacefully swimming across a calm river at golden hour",
    "seconds": 5,
    "size": "1920x1080"
  }'

# Poll for the result (replace VIDEO_ID with the id from the response)
curl https://api.lumenfall.ai/openai/v1/videos/VIDEO_ID \
  -H "Authorization: Bearer $LUMENFALL_API_KEY"

​
Response

The initial request returns a 202 with the video object: 
{
  "id": "video_abc123",
  "object": "video",
  "created_at": 1702345678,
  "status": "queued",
  "model": "sora-2",
  "seconds": "5",
  "size": "1920x1080"
}
Once completed, the GET response includes the output: 
{
  "id": "video_abc123",
  "object": "video",
  "created_at": 1702345678,
  "completed_at": 1702345720,
  "status": "completed",
  "model": "sora-2",
  "seconds": "5",
  "size": "1920x1080",
  "output": {
    "url": "https://media.lumenfall.ai/video_abc123.mp4",
    "content_type": "video/mp4",
    "size_bytes": 8388608
  }
}

​
Available models

Lumenfall routes your requests to the best available provider. Browse our full model catalog to see all supported models, or use the Models API to list available models programmatically.

​
Estimate costs before generating

Add ?dryRun=true to any request to get a cost estimate without generating the image. The response includes pricing in micros (1/1,000,000 of a dollar). See Cost estimation for details and response format.

​
Next steps

API Reference

Explore the full API documentation.

Authentication

Learn about API keys and authentication.

Routing

Understand how Lumenfall routes requests to providers.

Billing

View pricing and manage your account balance.