Sign In Get Started

LumozAI API Documentation

Integrate LumozAI's powerful AI models into your applications with our simple and robust API.

Authentication
Run Model
Check Status
Error Handling
Rate Limits

Authentication

All API requests require authentication using your API key. You can find your API key in your account settings.

API Key Authentication

LumozAI uses Bearer Token authentication. Include your API key in the Authorization header for all API requests.

Example Request (cURL) 
curl -X POST https://lumozai.com/api/v4/run \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json" \
-d "model_id=hidream-l1" \
-d "prompt=A beautiful sunset over mountains"
PHP Example 
$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' => 'hidream-l1',
        'prompt' => 'A beautiful sunset over mountains'
    ],
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Authorization: Bearer ' . $apiKey
    ]
]);

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

$result = json_decode($response, true);

Run Model

Use this endpoint to run a model and generate outputs.

POST /api/v4/run

Request Parameters

Parameter Type Required Description
model_id string Required The ID of the model to run (e.g., hidream-l1)
webhook string Optional URL to receive a callback when processing is complete
Additional parameters vary by model. See the Models pages for model-specific parameters.

Response

Success Response (200 OK) 
{
    "success": true,
    "data": {
        "request_id": 212121212121212, 
        "output": "https://lumozai.com/storage/outputs/image_12345.jpg",
        "output_type": "image"
    }
}
Note: If the model requires significant processing time, the response will contain only the request_id, and you can use the /check endpoint to poll for results.
Example Request (hidream-l1 model) 
curl -X POST https://lumozai.com/api/v4/run \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json" \
-d "model_id=hidream-l1" \
-d "prompt=A beautiful sunset over mountains" \
-d "negative_prompt=blurry, low quality" \
-d "guidance_scale=7.5" \
-d "num_inference_steps=30"

Check Request Status

Use this endpoint to check the status of a model run by its request ID.

POST /api/v4/check

Request Parameters

Parameter Type Required Description
request_id integer Required The request ID returned from a previous run model call

Response

Success Response - Processing (200 OK) 
{
    "success": true,
    "data": {
        "request_id": 212121212121212,
        "status": "processing",
        "progress": 45
    }
}
Success Response - Completed (200 OK) 
{
    "success": true,
    "data": {
        "request_id": 212121212121212,
        "status": "completed",
        "output": "https://lumozai.com/storage/outputs/image_12345.jpg",
        "output_type": "image"
    }
}
Error Response - Failed (200 OK) 
{
    "success": false,
    "data": {
        "request_id": 212121212121212,
        "status": "failed",
        "error": "Model execution failed due to invalid parameters"
    }
}
Example Request 
curl -X POST https://lumozai.com/api/v4/check \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json" \
-d "request_id=212121212121212"

Error Handling

Here are common errors you might encounter while using the LumozAI API.

Error Responses

HTTP Status Code Error Code Description
401 authentication_failed Invalid or missing API key
403 permission_denied You don't have permission to access this resource
404 model_not_found The requested model does not exist
422 validation_error Invalid parameters provided
429 rate_limit_exceeded You've exceeded your rate limit
500 internal_server_error An unexpected error occurred on our servers

Error Response Format

Error Response 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

LumozAI API has rate limits to ensure fair usage for all users.

Rate Limit Information

Rate limits vary based on your subscription plan. Each API response includes headers that provide information about your current rate limit status:

Header Description
X-RateLimit-Limit The maximum number of requests you're allowed to make per hour
X-RateLimit-Remaining The number of requests remaining in the current rate limit window
X-RateLimit-Reset The time at which the current rate limit window resets (Unix timestamp)
Important: If you exceed your rate limit, you'll receive a 429 Too Many Requests response. Implement exponential backoff in your applications to handle rate limiting gracefully.

For higher rate limits or custom requirements, please contact our sales team.