Developer API reference

LumixAI Image API Reference.

Endpoints, auth headers, request bodies, response examples, model slugs, and implementation flow for developers.

POST /v1/images/jobs

curl -X POST /api/backend/v1/images/jobs \
  -H "X-API-Key: $LUMIXAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-nano-banana-2-flash",
    "prompt": "premium product render on glass, studio lighting",
    "aspectRatio": "16:9",
    "resolution": "2k"
  }'

Quickstart

First image in three steps.

This is the exact flow a backend developer should implement. Get an API key from the dashboard, keep it server-side, then call image endpoints with X-API-Key.

Get API key

Open Dashboard -> API Keys, create a key, then store the raw air_live key as LUMIXAI_API_KEY.

Pick model

Call GET /v1/models. Send exact slug in model field, for example imagen-nano-banana-2-flash.

Create and poll job

POST /v1/images/jobs. Poll GET /v1/images/jobs/{id}, then download the file from data[].download_url.

Base URL

Use the backend API base URL for server-side calls. The local default is shown below.

/api/backend

Use async by default

Prefer POST /v1/images/jobs for production apps. Use sync /v1/images/generations only when your request path can wait for completion.

Authentication

Use X-API-Key for image endpoints.

This public docs page only documents generation APIs. Create and manage API keys in the dashboard, then send the raw air_live key in X-API-Key from your backend.

Use case	Header	Value	Endpoints
Image APIs	`X-API-Key`	`$LUMIXAI_API_KEY`	`/v1/images/*`
Public model catalog	`none`	`none`	`/v1/models`

Dashboard path

Open Dashboard -> API Keys -> Create key. Raw air_live key appears once.

Backend only

Store the key as an environment variable. Never expose it in browser code.

Model access

If the key is scoped, requests only work for allowed model slugs.

Endpoints

Image generation endpoints.

Use async jobs for production. Each endpoint shows method, path, auth, request example, and response shape.

POST/v1/images/jobs

Create async image job

Queues generation and returns an id. Poll with GET /v1/images/jobs/{id}.

Auth: X-API-Key
Success: 202 Accepted

Request

curl -X POST /api/backend/v1/images/jobs \
  -H "X-API-Key: $LUMIXAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-nano-banana-2-flash",
    "prompt": "premium product render on glass, studio lighting",
    "aspectRatio": "16:9",
    "resolution": "2k"
  }'

Response

{
  "id": "9f5b5e70-839b-46f5-a31c-6cf7d7e92a30",
  "status": "pending",
  "created": 1778956800,
  "usage": {
    "image_count": 1
  }
}

GET/v1/images/jobs/{id}

Poll image job

Returns pending, running, done, or error. When done, data[0].download_url streams the file through LumixAI. Upstream CDN URLs are not returned.

Auth: X-API-Key
Success: 200 OK

Request

curl /api/backend/v1/images/jobs/$JOB_ID \
  -H "X-API-Key: $LUMIXAI_API_KEY"

Response

{
  "id": "9f5b5e70-839b-46f5-a31c-6cf7d7e92a30",
  "status": "done",
  "created": 1778956800,
  "completed": 1778956842,
  "data": [
    {
      "download_url": "/v1/images/results/9f5b5e70-839b-46f5-a31c-6cf7d7e92a30/download"
    }
  ],
  "usage": {
    "image_count": 1
  }
}

GET/v1/images/results/{id}/download

Download generated image

Streams the image file from the backend with Content-Disposition attachment. Download promptly because generated images are not stored for you.

Auth: X-API-Key
Success: 200 OK

Request

curl /api/backend/v1/images/results/$JOB_ID/download \
  -H "X-API-Key: $LUMIXAI_API_KEY" \
  -L \
  -o lumixai-result.png

Response

HTTP/1.1 200 OK
Content-Type: image/png
Content-Disposition: attachment; filename="lumixai-9f5b5e70-839b-46f5-a31c-6cf7d7e92a30.png"

<binary image stream>

POST/v1/images/generations

Synchronous generation

Blocks until image generation finishes. Good for scripts; async jobs are safer for apps.

Auth: X-API-Key
Success: 200 OK

Request

curl -X POST /api/backend/v1/images/generations \
  -H "X-API-Key: $LUMIXAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-nano-banana-2-flash",
    "prompt": "premium product render on glass",
    "aspectRatio": "1:1",
    "resolution": "1k"
  }'

Response

{
  "created": 1778956800,
  "data": [
    {
      "download_url": "/v1/images/results/9f5b5e70-839b-46f5-a31c-6cf7d7e92a30/download"
    }
  ],
  "usage": {
    "image_count": 1
  }
}

GET/v1/models

List public models

Returns available model slugs and public model metadata.

Auth: none
Success: 200 OK

Request

curl /api/backend/v1/models

Response

{
  "data": [
    {
      "slug": "imagen-nano-banana-2-flash",
      "display_name": "Nano Banana 2",
      "modality": "image",
      "aspect_ratios": ["1:1", "2:3", "3:2", "4:3", "3:4", "5:4", "4:5", "16:9", "9:16", "21:9"],
      "default_aspect_ratio": "1:1",
      "resolutions": ["1k", "2k", "4k"],
      "default_resolution": "1k",
      "max_resolution": "2k",
      "group": "Google",
      "timing": "~29s",
      "unlimited": true,
      "max_n": 1,
      "image_credit_micros_per_unit": 5000000,
      "public": true,
      "active": true
    }
  ]
}

Node implementation loop

Server-side example: create job, poll every two seconds, throw on error, then download the generated file through LumixAI.

const createJob = await fetch("/api/backend/v1/images/jobs", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.LUMIXAI_API_KEY
  },
  body: JSON.stringify({
    model: "imagen-nano-banana-2-flash",
    prompt: "premium product render on glass, studio lighting",
    aspectRatio: "16:9",
    resolution: "2k"
  })
});

const job = await createJob.json();

let result = job;
while (result.status === "pending" || result.status === "running") {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  const poll = await fetch(`/api/backend/v1/images/jobs/${job.id}`, {
    headers: { "X-API-Key": process.env.LUMIXAI_API_KEY }
  });
  result = await poll.json();
}

if (result.status === "error") throw new Error(result.error);
const download = await fetch(`/api/backend${result.data[0].download_url}`, {
  headers: { "X-API-Key": process.env.LUMIXAI_API_KEY }
});

if (!download.ok) throw new Error("download failed");
const file = Buffer.from(await download.arrayBuffer());
await import("node:fs/promises").then((fs) => fs.writeFile("lumixai-result.png", file));

Model options

Read aspect_ratios, resolutions, default_resolution, and max_resolution from /v1/models before building UI. Requests above a model max are capped before pricing and upstream generation.

Nano Banana Pro max 2k

curl -X POST /api/backend/v1/images/jobs \
  -H "X-API-Key: $LUMIXAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-nano-banana-2",
    "prompt": "premium product render on glass, studio lighting",
    "aspectRatio": "9:16",
    "resolution": "2k"
  }'

References

Send references inline.

There is no separate public reference-upload endpoint. Attach reference image data in the same generation request. The backend uploads each reference upstream during that request and does not store it on the filesystem.

Generate with inline reference

curl -X POST /api/backend/v1/images/jobs \
  -H "X-API-Key: $LUMIXAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-kontext",
    "prompt": "@img1 in a cinematic product scene",
    "aspectRatio": "1:1",
    "resolution": "2k",
    "references": [
      {
        "image": "data:image/png;base64,$REFERENCE_IMAGE_BASE64",
        "label": "img1"
      }
    ]
  }'

Schemas

Request and response fields.

Use these tables as the contract for implementation. Optional fields can be omitted unless your workflow needs them.

ImageGenerationRequest

Field	Type	Notes
`model`	`string`	Required. Model slug, for example imagen-nano-banana-2-flash.
`prompt`	`string`	Required. Natural language prompt. Prompt-only requests use Spaces T2I.
`aspectRatio`	`string`	Optional. 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9, or 9:21.
`resolution`	`string`	Optional. 1k, 2k, or 4k when supported by the model. Nano Banana 2, Nano Banana Pro, and Flux.2 variants are capped to 2k.
`references`	`array`	Optional. One inline reference object such as { image: dataURI, label: "img1" } for Spaces flow. Multiple references are rejected in v1.
`spaceId`	`string`	Optional. Magnific Space UUID. If omitted, backend uses env or the active Magnific Space tab context.
`timeoutMs`	`integer`	Optional. Magnific Spaces render wait timeout in milliseconds.
`seed`	`integer`	Optional. Repeatable generation seed when provider supports it.

ImageJobStatusResponse

Field	Type	Notes
`id`	`string`	Job id used by GET /v1/images/jobs/{id}.
`status`	`string`	pending, running, done, or error.
`created`	`number`	Unix timestamp for job creation.
`completed`	`number`	Unix timestamp when terminal, returned when available.
`data[].download_url`	`string`	LumixAI download endpoint for streaming the generated image file.
`error`	`string`	Human-readable error message when status is error.
`usage.image_count`	`number`	Number of generated images charged or reserved.

API reference

Endpoint map.

This public map only includes model discovery and image generation endpoints. Auth, API-key management, user, billing, metrics, and admin endpoints are intentionally not documented here.

Method	Path	Auth	Use
`GET`	`/v1/models`	none	List public active models.
`POST`	`/v1/images/generations`	X-API-Key	Synchronous Magnific Spaces generation.
`POST`	`/v1/images/jobs`	X-API-Key	Create an async Magnific Spaces generation job.
`GET`	`/v1/images/jobs/{id}`	X-API-Key	Poll an async job.
`GET`	`/v1/images/results/{id}/download`	X-API-Key	Stream generated image file through LumixAI.

List public models

curl /api/backend/v1/models

Models

39 model slugs available.

Pass one of these slugs as the model field. The list is grouped by provider and generated from the same catalog used by the site menu.

Google

7 models

Nano Banana 2

imagen-nano-banana-2-flash

Fast Google image generation model for creative iteration, product concepts, and reference-aware workflows.

Nano Banana Pro

imagen-nano-banana-2

Google image generation model for high-fidelity prompts, polished brand assets, and production-grade visual output.

Nano Banana

imagen-nano-banana

Google image model for reliable prompt following, clean compositions, and everyday visual generation.

Imagen 4 Ultra

imagen4-ultra

Premium Imagen 4 API option for detailed scenes, typography-aware layouts, and high-quality image generation.

Imagen 4

imagen4

Balanced Imagen 4 generation for crisp commercial imagery, concept art, and product content.

Imagen 4 Fast

imagen4-fast

Lower-latency Imagen 4 model for teams that need quick generations without leaving the Imagen family.

Imagen 3

imagen3

Stable Imagen 3 image API model for realistic prompts, clean lighting, and dependable image creation.

Black Forest Labs

10 models

Flux.2 Max

flux-2-max

Top Flux.2 model for premium detail, strong prompt adherence, and demanding production renders.

Flux.2 Pro

flux-2

Flexible Flux.2 API model for product, people, editorial, and creative image generation.

Flux.2 Flex

flux-2-flex

Flux.2 model variant for controlled production workflows with stronger creative flexibility.

Flux.2 Klein

flux-2-klein

Lean Flux.2 option for fast drafts, prompt exploration, and lower-cost visual iteration.

Flux.1 Kontext Max

flux-kontext-high

Reference-aware Flux Kontext model for image editing, subject preservation, and precise transformations.

Flux.1 Kontext Pro

flux-kontext

Flux Kontext API model for edits that use references, style transfer, and controlled visual changes.

Flux.1

flux-dev

Flux.1 image generation model for broad creative output and reliable prompt-to-image workflows.

Flux.1.1

flux-pro-plus

Flux 1.1 model for refined prompt adherence, commercial imagery, and production iteration.

Flux.1 Realism

flux-realism

Flux model tuned for realistic scenes, natural lighting, and believable generated photography.

Flux.1 Fast

flux

Fast Flux API model for quick ideation, low-cost experiments, and visual batch generation.

Seedream

4 models

Seedream 5 Lite

seedream-5-lite

Lightweight Seedream image model for quick visual exploration, lifestyle scenes, and concept art.

Seedream 4.5

seedream-4-5

Seedream 4.5 API model for crisp composition control, rich portraits, and commercial visuals.

Seedream 4

seedream-4

Seedream 4 image generation model for multi-style prompts, clean aesthetics, and production content.

Seedream 4 4K

seedream-4-4k

4K-oriented Seedream 4 model for large-format visuals, detailed artwork, and hero assets.

OpenAI

3 models

GPT

gpt-medium

GPT image API option for practical generation, prompt reasoning, and everyday product visuals.

GPT 1 - HQ

gpt-high

Higher-quality GPT image model for polished assets, stronger instruction following, and detail-heavy prompts.

GPT 1.5

gpt-1-5-medium

Efficient GPT Image 1.5 style API page for teams seeking low-cost AI image generation.

Alibaba

2 models

Z-Image

z-image

Z-Image API model for posters, illustration, expressive graphics, and campaign-ready creative assets.

Qwen

qwen

Qwen image model for efficient text-to-image generation, multilingual prompts, and creative variations.

Freepik

4 models

Mystic 2.5

mystic-2-5

Mystic image generation for stylized concepts, expressive compositions, and creator-friendly visual output.

Mystic 2.5 Flexible

mystic-2-5-flexible

Flexible Mystic preset for quick style exploration and adaptable creative image prompts.

Mystic 2.5 Fluid

mystic-2-5-fluid

Fluid Mystic preset for smooth compositions, artistic images, and fast creative production.

Mystic 1.0

mystic

Classic Mystic model for accessible image generation, creator workflows, and low-cost drafts.

LumixAI

4 models

Auto

auto

Automatic model routing for teams that want one image API endpoint to pick a strong default.

Cinematic

cinematic

A production preset tuned for dramatic framing, rich contrast, and storyboard-friendly generated images.

Classic Fast

fast

Fast classic image generation preset for low-cost drafts and quick creative feedback loops.

Classic

classic

Classic image API preset for simple prompts, dependable outputs, and budget-conscious generation.

Recraft

2 models

Recraft V4

recraft-v4

Recraft V4 API model for design assets, brand graphics, product mockups, and vector-style visuals.

Recraft V4.1

recraft-v4-1

Recraft V4.1 model for refined design generation, consistent brand visuals, and production assets.

Ideogram

1 models

Ideogram

ideogram

Ideogram API model for campaign concepts, typography-aware compositions, and text-friendly image output.

Runway

1 models

Runway

runway-gen4

Runway Gen-4 style image API option for cinematic frames, story-led production, and visual consistency.

xAI

1 models

Grok

grok

Grok image API option for fast creative generation, social-first visuals, and conversational prompt workflows.

Errors

Read error.type first.

Errors return JSON with error.type and error.message. Provider internals are normalized to service_unavailable for public callers.

HTTP	Type	Meaning
`400`	`validation_error`	Request body or path parameter is invalid.
`401`	`authentication_error`	Missing or invalid API key.
`402`	`insufficient_credits_error`	Workspace does not have enough available credits.
`403`	`permission_denied_error`	API key exists but cannot access the resource.
`404`	`resource_not_found_error`	Resource does not exist or is not visible to this workspace.
`409`	`idempotency_conflict`	Duplicate request conflict.
`429`	`rate_limit_error`	API key exceeded configured RPM limit.
`503`	`service_unavailable`	Provider or upstream generation service is unavailable.

Error response format

{
  "error": {
    "type": "insufficient_credits_error",
    "message": "insufficient credits"
  }
}

Ready

Test the request in Playground.

The dashboard playground uses the same inline reference, /v1/images/jobs, polling, and download flow shown in these docs.

Open playground