LumozAI v4 API Documentation

Unified REST endpoint for high-speed model inference, asynchronous background pipelines, and real-time execution status.

FLUX 3 Image ⚡
Text to Image $0.05 / run Popular New

FLUX 3 Image

model_id: flux-3-image 8 Parameters Defined

FLUX 3 is Black Forest Labs' flagship visual model for text-to-image and reference-based editing with up to 10 images, research grounding, a...

AUTHENTICATION

Bearer Token Authentication

All requests to the LumozAI API require authentication using your secret API key. Pass your key in the standard Authorization HTTP header as a Bearer token.

cURL Authorization Header Quickstart
curl -X POST https://lumozai.com/api/v4/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -d "model_id=flux-3-image" \
  -d "prompt=A futuristic cityscape illuminated by neon bioluminescence"
PHP cURL Request
<?php
$apiKey = 'YOUR_API_KEY';

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => 'https://lumozai.com/api/v4/run',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => [
        'model_id' => 'flux-3-image',
        'prompt' => 'A futuristic cityscape illuminated by neon bioluminescence'
    ],
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Authorization: Bearer ' . $apiKey
    ]
]);

$response = curl_exec($curl);
curl_close($curl);

$result = json_decode($response, true);
print_r($result);
POST /api/v4/run

Execute FLUX 3 Image Inference

Submit a synchronous or asynchronous generation job for FLUX 3 Image (flux-3-image). Fast-running image models return the generated asset directly; longer inference pipelines return a request_id for asynchronous polling.

Request Parameters for FLUX 3 Image

10 total fields
Parameter Type Required Default Description / Allowed Values
model_id string Required flux-3-image
Unique model identifier. Must be set to flux-3-image.
prompt
Prompt
string Required —
Text description of the image to generate, or of the edit to apply to reference images.
images
Reference Images
array of URLs Optional —
Up to 10 reference images the prompt edits or draws from. When present, runs as an edit and the first image drives 'auto' aspect ratio.
aspect_ratio
Aspect Ratio
enum Optional auto
Aspect ratio of the generated image. 'auto' picks the ratio from prompt or first reference image.
auto 1:1 16:9 9:16 4:3 3:4 3:2 2:3 21:9 9:21 4:5 5:4 7:5 5:7 2:1 1:2
resolution
Resolution
enum Optional 1k
Resolution of the output image.
768sq 1k 1.5k 2k 4k
grounding
Research Grounding
enum Optional true
Let the model research the prompt with web and image search before generating.
true false
output_format
Output Format
enum Optional webp
Format of the output image.
webp jpg png
output_quality
Output Quality
number Optional 80
Quality when saving output images (0 to 100).
Range: 0 to 100 (step: 1)
safety_tolerance
Safety Tolerance
number Optional 2
Moderation tolerance for inputs and outputs (0 strictest, 4 most permissive).
Range: 0 to 4 (step: 1)
webhook string (URL) Optional — Optional callback URL to receive an HTTP POST when async generation completes.

Model-Specific Integration Code

Copy-paste production snippets configured with flux-3-image and tailored parameter inputs.

cURL POST /api/v4/run (flux-3-image)
curl -X POST https://lumozai.com/api/v4/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -d "model_id=flux-3-image" \
  -d "prompt=A futuristic cybernetic metropolis illuminated by neon bioluminescence, 8k cinematic masterpiece" \
  -d "images[]=https://lumozai.com/samples/sample_input.jpg" \
  -d "aspect_ratio=auto" \
  -d "resolution=1k" \
  -d "grounding=true" \
  -d "output_format=webp" \
  -d "output_quality=80" \
  -d "safety_tolerance=2"
Python requests.post (flux-3-image)
import requests

url = "https://lumozai.com/api/v4/run"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json"
}
payload = {
    "model_id": "flux-3-image",
    "prompt": "A futuristic cybernetic metropolis illuminated by neon bioluminescence, 8k cinematic masterpiece",
    "images": ["https:\/\/lumozai.com\/samples\/sample_input.jpg"],
    "aspect_ratio": "auto",
    "resolution": "1k",
    "grounding": "true",
    "output_format": "webp",
    "output_quality": 80,
    "safety_tolerance": 2
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
PHP cURL POST (flux-3-image)
<?php
$apiKey = 'YOUR_API_KEY';

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => 'https://lumozai.com/api/v4/run',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => [
        'model_id' => 'flux-3-image',
        'prompt' => 'A futuristic cybernetic metropolis illuminated by neon bioluminescence, 8k cinematic masterpiece',
        'images[]' => 'https://lumozai.com/samples/sample_input.jpg',
        'aspect_ratio' => 'auto',
        'resolution' => '1k',
        'grounding' => 'true',
        'output_format' => 'webp',
        'output_quality' => 80,
        'safety_tolerance' => 2
    ],
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Authorization: Bearer ' . $apiKey
    ]
]);

$response = curl_exec($curl);
curl_close($curl);

$result = json_decode($response, true);
print_r($result);
JavaScript fetch async/await (flux-3-image)
const response = await fetch('https://lumozai.com/api/v4/run', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    "model_id": "flux-3-image",
    "prompt": "A futuristic cybernetic metropolis illuminated by neon bioluminescence, 8k cinematic masterpiece",
    "images": ["https:\/\/lumozai.com\/samples\/sample_input.jpg"],
    "aspect_ratio": "auto",
    "resolution": "1k",
    "grounding": "true",
    "output_format": "webp",
    "output_quality": 80,
    "safety_tolerance": 2
  })
});

const data = await response.json();
console.log(data);

Response Structure (200 OK)

JSON Output
{
  "success": true,
  "data": {
    "request_id": 982348712938172,
    "output": "https://lumozai.com/storage/outputs/result_flux-3-image_9823.png",
    "output_type": "image"
  }
}
POST /api/v4/check

Poll Asynchronous Task Status

Poll the current execution state of an asynchronous job using the returned request_id.

Request Parameters

Parameter Type Required Description
request_id integer Required The unique job ID returned when calling /api/v4/run.
JSON Completed Status (200 OK)
{
  "success": true,
  "data": {
    "request_id": 982348712938172,
    "status": "completed",
    "output": "https://lumozai.com/storage/outputs/video_8172.mp4",
    "output_type": "video"
  }
}
JSON In-Progress Status (200 OK)
{
  "success": true,
  "data": {
    "request_id": 982348712938172,
    "status": "processing",
    "progress": 68
  }
}
ERROR HANDLING

Standard Error Codes

The API uses conventional HTTP response codes to indicate success or failure. In general, 2xx indicates success, 4xx indicates client input issues, and 5xx indicates server errors.

Status Error Code Description
401 authentication_failed Missing or invalid Authorization Bearer header.
403 permission_denied Insufficient credits or account tier permissions.
404 model_not_found The specified model_id does not exist or is deprecated.
422 validation_error Missing required parameters or invalid parameter types.
429 rate_limit_exceeded Request rate quota exceeded for your tier.
500 internal_server_error Downstream GPU compute error or worker timeout.
JSON Validation Error Example
{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "The model_id field is required.",
    "details": {
      "model_id": ["The model_id field is required."]
    }
  }
}
RATE LIMITS

Quota & Throughput Limits

Rate limits are enforced per API key to guarantee fair access and consistent low latency across GPU workers. Every API response includes informative headers:

Header Description
X-RateLimit-Limit Maximum number of requests permitted per rolling hour.
X-RateLimit-Remaining Number of remaining requests in the active window.
X-RateLimit-Reset Unix epoch timestamp when the current window refreshes.
Handling 429 Status Codes: When rate-limited, wait for the number of seconds until X-RateLimit-Reset or implement an exponential backoff retry mechanism. Need custom enterprise rate limits? Contact our team.
NEW API /api/v1/memory/*

Serverless Vector Memory & Semantic Search

Store, index, and retrieve vector embeddings with sub-50ms latency. Unlike traditional vector databases that charge $25 to $70 every month just to keep a cluster active, Lumoz offers zero base fees: 5,000 vector memory slots and 10,000 semantic queries per month are included free with any active balance reload.

Core Endpoints

Method Endpoint Description
GET /api/v1/memory/usage Inspect active tier, vector storage meter, and monthly search counters.
POST /api/v1/memory/projects Create an isolated project/namespace (e.g. support-bot).
POST /api/v1/memory/store Embed and index text documents or knowledge chunks.
POST /api/v1/memory/search Cosine similarity search with hybrid keyword weighting.
DELETE /api/v1/memory/{id} Delete an indexed memory item.

Code Examples

cURL 1. Store Knowledge & 2. Semantic Search
# 1. Ingest text into an isolated namespace
curl -X POST "https://lumozai.com/api/v1/memory/store" \
  -H "Authorization: Bearer YOUR_LUMOZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "support-bot",
    "text": "Refunds are processed within 48 hours to original payment method.",
    "metadata": {"category": "billing"}
  }'

# 2. Query vector memory via cosine similarity
curl -X POST "https://lumozai.com/api/v1/memory/search" \
  -H "Authorization: Bearer YOUR_LUMOZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "support-bot",
    "query": "How long do refunds take?",
    "top_k": 3
  }'
Python requests (Vector Store & Search)
import requests

headers = {
    "Authorization": "Bearer YOUR_LUMOZ_API_KEY",
    "Content-Type": "application/json"
}

# Store Knowledge
requests.post("https://lumozai.com/api/v1/memory/store", headers=headers, json={
    "project": "support-bot",
    "text": "Enterprise SLA guarantees 99.99% uptime with dedicated GPU routing.",
    "metadata": {"tier": "enterprise"}
})

# Semantic Search
res = requests.post("https://lumozai.com/api/v1/memory/search", headers=headers, json={
    "project": "support-bot",
    "query": "What is the uptime SLA?",
    "top_k": 2
})
print("Top Matches:", res.json()["results"])

Zero-Code RAG with Lumoz LLM

Pass "memory": {"project": "..."} directly to /api/v1/chat/completions. Lumoz automatically pulls relevant memories into the prompt context without requiring any custom client-side vector code:

Node.js Zero-Code RAG Chat Completion
const response = await fetch("https://lumozai.com/api/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_LUMOZ_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "lumoz-llm-1.0",
    messages: [
      { role: "user", content: "What is your refund policy window?" }
    ],
    memory: {
      project: "support-bot",
      top_k: 3
    }
  })
});

const data = await response.json();
console.log(data.choices[0].message.content);