> ## 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.

# Quickstart

> Make your first API call in under 5 minutes

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](https://lumenfall.ai))
* An API key from your [dashboard](https://lumenfall.ai/app)

## Chat completion

Send a message and get a text response. Text models are powered by [OpenRouter](https://openrouter.ai), so you can use any model available there.

<CodeGroup>
  ```bash cURL theme={null}
  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"}
      ]
    }'
  ```

  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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);
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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);
  ```
</CodeGroup>

## Response

The API returns image URLs in the standard OpenAI format:

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  # 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"
  ```

  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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);
  ```
</CodeGroup>

### Response

The initial request returns a `202` with the video object:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](https://lumenfall.ai/models) to see all supported models, or use the [Models API](/api-reference/models/list) 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](/api-reference/cost-estimation) for details and response format.

## Next steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore the full API documentation.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Learn about API keys and authentication.
  </Card>

  <Card title="Routing" icon="route" href="/routing">
    Understand how Lumenfall routes requests to providers.
  </Card>

  <Card title="Billing" icon="credit-card" href="/billing">
    View pricing and manage your account balance.
  </Card>
</CardGroup>