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

# HTTP / cURL

> Make direct HTTP requests to the Lumenfall API

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`:

<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 (requests) theme={null}
  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"])
  ```

  ```javascript JavaScript (fetch) theme={null}
  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);
  ```

  ```go Go theme={null}
  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 PHP theme={null}
  <?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'];
  ```
</CodeGroup>

### Response

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

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

```bash 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 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:

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

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

  ```javascript JavaScript (fetch) theme={null}
  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);
  ```
</CodeGroup>

### With a mask

Provide a mask to specify which areas should be edited:

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

```bash theme={null}
curl https://api.lumenfall.ai/openai/v1/models \
  -H "Authorization: Bearer $LUMENFALL_API_KEY"
```

Response:

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

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

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

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

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

<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 more about API key management.
  </Card>
</CardGroup>