API Documentation
Integrate Elirian's AI design engine into your products. Generate photorealistic room redesigns, virtual staging, and style transfers programmatically.
Introduction
The Elirian API is a REST API that returns JSON. All requests must be made over HTTPS. The base URL for all endpoints is:
https://app.elirian.com/api/v1
API access is available on Pro and higher plans. Each API call consumes the same credits as using the studio directly.
Authentication
Authenticate requests by passing your API key in the Authorization header:
Authorization: Bearer ek_YOUR_API_KEY
API keys are generated in your account dashboard. Keep your key secret - never expose it in client-side code.
Generating a key
Go to Dashboard → API Keys → Create New Key. Choose the scopes your key needs and give it a descriptive name.
Rate Limits
| Plan | Requests / minute | Concurrent jobs |
|---|---|---|
| Pro | 30 | 3 |
| Studio | 60 | 6 |
| Agency | 120 | 12 |
Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Generate Design
Submits a design job. Returns immediately with a token you can use to poll for results.
Request body
| Parameter | Type | Required | Description |
|---|---|---|---|
mode | string | required | Generation mode. See Modes Reference for all 22 available modes. |
image_url | string | *mode-dependent | URL of the source room image (JPEG or PNG, max 10 MB). Required for all modes except freestyle. |
style | string | optional | Style name (e.g. Japandi, Modern Luxury) |
room_type | string | optional | Room type (e.g. Living Room, Bedroom) |
quality | string | optional | standard (1 cr), high (2 cr), ultra (5 cr). Default: high |
prompt | string | optional | Additional text instructions (max 500 chars) |
make_public | boolean | optional | Publish to public gallery on completion. Default: false |
Example
curl -X POST https://app.elirian.com/api/v1/generate \
-H "Authorization: Bearer ek_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image_url": "https://example.com/room.jpg",
"mode": "redesign",
"style": "Japandi",
"room_type": "Living Room"
}'
Response
{
"token": "dsn_abc123xyz",
"status": "queued",
"estimated_seconds": 15,
"credits_charged": 1
}
Generation Modes
Pass one of the following values as the mode parameter. Modes marked img required need an image_url; freestyle generates from a prompt alone.
| Mode | Description | Image | Credits |
|---|---|---|---|
| redesign | Full AI redesign of an existing room in a new style | required | 1-5 |
| style_transfer | Apply a style reference image to your room | required | 1-5 |
| virtual_staging | Furnish and stage an empty or bare room | required | 1-5 |
| sketch2image | Convert a hand-drawn or 2D floor-plan sketch to a render | required | 2-5 |
| sketchup | Render from a SketchUp / CAD model screenshot | required | 2-5 |
| empty_space | Remove all furniture and render a clean empty room | required | 2 |
| outdoor | Transform or redesign outdoor spaces and gardens | required | 1-5 |
| freestyle | Generate a room purely from text description - no image needed | not needed | 1-5 |
| upscale | Upscale and enhance an existing image (2× or 4×) | required | 1-2 |
| wall_painter | Change wall colour(s) without altering furnishings | required | 1-2 |
| lighting_changer | Alter the lighting mood (warm, cool, natural, dramatic) | required | 1-2 |
| color_palette | Extract a colour palette from a room and apply variations | required | 1 |
| furniture_placement | Drop specific furniture pieces into a room photo | required | 1-5 |
| layout_optimizer | AI-suggest optimised furniture arrangements for a floor plan | required | 1-2 |
| room_planner | 2D room planning and layout drawing tool | optional | 1 |
| add_people | Add lifelike people to room renders for lifestyle photography | required | 1-2 |
| product_placement | Insert specific products into a room scene | required | 1-5 |
| lens_lookup | Identify products and materials visible in a room photo | required | 1 |
| compare | Generate a side-by-side or slider before/after comparison | required | 1 |
| 3d_flythrough | Generate a short 3D flythrough video of a room | required | 5-10 |
| vr_walkthrough | Create an interactive 360° VR walkthrough | required | 5-10 |
| batch | Apply the same transformation to multiple images at once | required | per-image |
Check Job Status
Poll this endpoint until status is completed or failed. We recommend polling every 2 seconds.
Response (completed)
{
"token": "dsn_abc123xyz",
"status": "completed",
"output_url": "https://cdn.elirian.com/outputs/...",
"thumbnail_url": "https://cdn.elirian.com/thumbs/...",
"gallery_id": 42,
"created_at": "2026-05-20T14:23:01Z",
"completed_at": "2026-05-20T14:23:18Z"
}
List My Designs
Returns a paginated list of your completed designs.
Query parameters
| Parameter | Default | Description |
|---|---|---|
page | 1 | Page number |
per_page | 24 | Results per page (max 100) |
style | - | Filter by style |
room_type | - | Filter by room type |
Scopes Reference
API keys can be restricted to specific scopes. Grant only the permissions your integration needs.
| Scope | Access granted |
|---|---|
| generate | Submit design jobs and consume credits |
| gallery:read | List and read your design gallery |
| gallery:write | Update visibility / metadata of your designs |
| session:read | Poll job status |
Errors
All errors return a JSON body with message and optional errors array.
| Status | Meaning |
|---|---|
| 400 | Bad request - validation failed |
| 401 | Unauthorized - missing or invalid API key |
| 402 | Payment required - insufficient credits |
| 403 | Forbidden - key lacks required scope |
| 404 | Resource not found |
| 429 | Too many requests - rate limit exceeded |
| 500 | Internal server error |
SDKs & Examples
Official SDKs are in development. Use the REST API directly with any HTTP client. The examples below show a full generate + poll cycle.