Quickstart

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

A Lumenfall account (sign up)
An API key from your dashboard

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"}
    ]
  }'

from openai import OpenAI

client = OpenAI(
    api_key="your-lumenfall-api-key",
    base_url="https://api.lumenfall.ai/openai/v1"
)

response = client.chat.completions.create(
    model="google/gemini-3-flash-preview",
    messages=[
        {"role": "user", "content": "Tell me a fun fact about capybaras"}
    ]
)

print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "your-lumenfall-api-key",
  baseURL: "https://api.lumenfall.ai/openai/v1",
});

const response = await client.chat.completions.create({
  model: "google/gemini-3-flash-preview",
  messages: [
    { role: "user", content: "Tell me a fun fact about capybaras" },
  ],
});

console.log(response.choices[0].message.content);

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"
  }'

from openai import OpenAI

client = OpenAI(
    api_key="your-lumenfall-api-key",
    base_url="https://api.lumenfall.ai/openai/v1"
)

response = client.images.generate(
    model="gemini-3-pro-image",
    prompt="A serene mountain landscape at sunset with dramatic clouds",
    n=1,
    size="1024x1024"
)

print(response.data[0].url)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "your-lumenfall-api-key",
  baseURL: "https://api.lumenfall.ai/openai/v1",
});

const response = await client.images.generate({
  model: "gemini-3-pro-image",
  prompt: "A serene mountain landscape at sunset with dramatic clouds",
  n: 1,
  size: "1024x1024",
});

console.log(response.data[0].url);

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"

import time
from openai import OpenAI

client = OpenAI(
    api_key="your-lumenfall-api-key",
    base_url="https://api.lumenfall.ai/openai/v1"
)

# Submit the request
video = client.videos.create(
    model="sora-2",
    prompt="A capybara peacefully swimming across a calm river at golden hour",
    seconds=5,
    size="1920x1080",
)

# Poll until ready
while video.status not in ("completed", "failed"):
    time.sleep(5)
    video = client.videos.retrieve(video.id)

print(video.output.url)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "your-lumenfall-api-key",
  baseURL: "https://api.lumenfall.ai/openai/v1",
});

// Submit the request
let video = await client.videos.create({
  model: "sora-2",
  prompt:
    "A capybara peacefully swimming across a calm river at golden hour",
  seconds: 5,
  size: "1920x1080",
});

// Poll until ready
while (video.status !== "completed" && video.status !== "failed") {
  await new Promise((r) => setTimeout(r, 5000));
  video = await client.videos.retrieve(video.id);
}

console.log(video.output.url);

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.

Getting started

Core concepts

Replay

Dashboard

Client libraries

Integrations

Prerequisites

Chat completion

Response

Generate an image

Response

Generate a video

Response

Available models

Estimate costs before generating

Next steps

API Reference

Authentication

Routing

Billing

​Prerequisites

​Chat completion

​Response

​Generate an image

​Response

​Generate a video

​Response

​Available models

​Estimate costs before generating

​Next steps

API Reference

Authentication

Routing

Billing

Prerequisites

Chat completion

Response

Generate an image

Response

Generate a video

Response

Available models

Estimate costs before generating

Next steps