Studio

LumixAI Image and Video API Reference

REST API on https://api.lumixai.live/v1: choose an image or video model slug, submit a generation job, poll by job id, then download the generated result.

Note: replace YOUR_LUMIXAI_API_KEY with your dashboard key. The public catalog currently exposes 96 image and video model slugs.

Download implement.md

Base

/v1

Auth

X-API-Key

Mode

image + video

Authentication

Every image endpoint requires X-API-Key. Keep the raw air_live key on your server and send it from backend code only.

Use case	Header	Value	Endpoints
Image APIs	`X-API-Key`	`$LUMIXAI_API_KEY`	`/v1/images/*`
Video APIs	`X-API-Key`	`$LUMIXAI_API_KEY`	`/v1/videos/*`
Public catalogs	`none`	`none`	`/v1/models, /v1/models/catalog, /v1/models/credits, /v1/models/credits/catalog, /v1/videos/models`

Dashboard path

Open Dashboard -> API Keys -> Create key. The raw key appears once.

Backend only

Never expose X-API-Key in browser code.

Model access

Scoped keys only work for allowed model slugs.

Reference images

Send references inline

There is no separate public upload endpoint. Attach reference image data in the same generation request.

POST/v1/images/jobs

Use a data URI or raw base64 value in references[].image. The backend forwards inline references to the Space image-to-image flow as images[] and does not store them on disk.

cURL example

curl --location 'https://api.lumixai.live/v1/images/jobs' \
  -H "X-API-Key: $LUMIXAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-kontext",
    "prompt": "a cute cat catching a mouse",
    "aspectRatio": "1:1",
    "resolution": "2k",
    "references": [
      {
        "image": "data:image/png;base64,$REFERENCE_IMAGE_1_BASE64"
      },
      {
        "image": "data:image/png;base64,$REFERENCE_IMAGE_2_BASE64"
      }
    ]
  }'

Generation

Create async image job

Use async jobs for production. The create call returns an id immediately; poll that id until the job is done or error.

POST/v1/images/jobs

Auth

X-API-Key

Success

202 Accepted

Use

Queue image generation and return job id.

cURL example

curl --location 'https://api.lumixai.live/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"
  }'

Example response

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

Node polling loop

const createJob = await fetch("https://api.lumixai.live/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(`https://api.lumixai.live/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(`https://api.lumixai.live${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));

Polling

Poll image job

The job endpoint returns pending, running, done, or error. When done, use data[0].download_url to stream the generated image through LumixAI.

GET/v1/images/jobs/{id}

Auth

X-API-Key

Success

200 OK

Terminal states

done, error

cURL example

curl --location 'https://api.lumixai.live/v1/images/jobs/$JOB_ID' \
  -H "X-API-Key: $LUMIXAI_API_KEY"

Example 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
  }
}

Downloads

Download generated image

Generated files stream from the backend with Content-Disposition attachment. Download promptly; the API does not store generated images for you.

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

Auth

X-API-Key

Success

200 OK

Output

Binary image stream

cURL example

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

Example response

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

<binary image stream>

Video catalog

List video model capabilities

Use /v1/videos/models for live provider capabilities, then pair it with /v1/models?category=video or /v1/models/catalog for public pricing and display metadata.

GET/v1/videos/models

Auth

none

Success

200 OK

Use

Read video durations, aspect ratios, resolutions, sound, image-to-video, and reference support.

cURL example

curl --location 'https://api.lumixai.live/v1/videos/models'

Example response

{
  "data": [
    {
      "slug": "google-veo3_1-lite",
      "name": "Google Veo 3.1 Lite",
      "api": "google",
      "model": "veo3_1",
      "mode": "veo3_1_lite",
      "resolutions": ["720p", "1080p"],
      "durations": [4, 6, 8],
      "aspectRatios": ["16:9", "9:16"],
      "sound": true,
      "i2v": true,
      "refs": ["startFrame", "endFrame", "reference"]
    }
  ]
}

Video generation

Create async video job

Video generation is async only. Create a job, reserve credits, then poll until done or error. Failed generation returns a public error message and refunds reserved credits automatically.

POST/v1/videos/jobs

Auth

X-API-Key

Success

202 Accepted

Use

Queue text-to-video or image-to-video generation and return job id.

cURL example

curl --location 'https://api.lumixai.live/v1/videos/jobs'   -H "X-API-Key: $LUMIXAI_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "google-veo3_1-lite",
    "prompt": "a cinematic product reveal with soft camera motion",
    "aspectRatio": "16:9",
    "resolution": "720p",
    "duration": 6,
    "withSoundEffects": true
  }'

Example response

{
  "id": "2ff3e6c3-6b6f-4b47-b9f2-d64691712e2a",
  "status": "pending",
  "created": 1778956800,
  "usage": {
    "video_count": 6
  }
}

Image-to-video example

curl --location 'https://api.lumixai.live/v1/videos/jobs'   -H "X-API-Key: $LUMIXAI_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "google-veo3_1-lite",
    "prompt": "animate these product frames with a slow dolly-in",
    "images": [
      "data:image/png;base64,$START_FRAME_BASE64",
      "data:image/png;base64,$SECOND_FRAME_BASE64"
    ],
    "maxRefs": 5,
    "aspectRatio": "16:9",
    "resolution": "720p",
    "duration": 6
  }'

Start/end frame example

curl --location 'https://api.lumixai.live/v1/videos/jobs'   -H "X-API-Key: $LUMIXAI_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "google-veo3_1-lite",
    "prompt": "smooth transition between the two frames",
    "image": "data:image/png;base64,$START_FRAME_BASE64",
    "endImage": "data:image/png;base64,$END_FRAME_BASE64",
    "aspectRatio": "16:9",
    "resolution": "720p",
    "duration": 6
  }'

Video polling

Poll video job

Poll the job endpoint until status is done or error. When done, use data[0].download_url to stream the generated video through LumixAI.

GET/v1/videos/jobs/{id}

Auth

X-API-Key

Success

200 OK

Terminal states

done, error

cURL example

curl --location 'https://api.lumixai.live/v1/videos/jobs/$JOB_ID'   -H "X-API-Key: $LUMIXAI_API_KEY"

Example response

{
  "id": "2ff3e6c3-6b6f-4b47-b9f2-d64691712e2a",
  "status": "done",
  "created": 1778956800,
  "completed": 1778956902,
  "data": [
    {
      "download_url": "/v1/videos/results/2ff3e6c3-6b6f-4b47-b9f2-d64691712e2a/download",
      "web_url": "https://magnific.com/video/example"
    }
  ],
  "usage": {
    "video_count": 6
  }
}

Video downloads

Download generated video

Generated videos stream from the backend with Content-Disposition attachment. Download promptly; provider URLs can expire.

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

Auth

X-API-Key

Success

200 OK

Output

Binary video stream

cURL example

curl --location 'https://api.lumixai.live/v1/videos/results/$JOB_ID/download'   -H "X-API-Key: $LUMIXAI_API_KEY"   -L   -o lumixai-result.mp4

Example response

HTTP/1.1 200 OK
Content-Type: video/mp4
Content-Disposition: attachment; filename="lumixai-2ff3e6c3-6b6f-4b47-b9f2-d64691712e2a.mp4"

<binary video stream>

Sync path

Synchronous generation

Use synchronous generation for scripts or short blocking workflows. Production apps should use async jobs.

POST/v1/images/generations

cURL example

curl --location 'https://api.lumixai.live/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"
  }'

Example response

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

Models

Model and pricing catalogs

Call catalog endpoints before building UI. Use category=image or category=video for flat lists, and catalog endpoints when you need image and video grouped for pricing pages.

GET/v1/models

cURL example

curl --location 'https://api.lumixai.live/v1/models'

Example 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
    }
  ]
}

GET/v1/models/catalog

cURL example

curl --location 'https://api.lumixai.live/v1/models/catalog'

Example response

{
  "data": {
    "image": [
      {
        "slug": "imagen-nano-banana-2-flash",
        "display_name": "Nano Banana 2",
        "modality": "image",
        "resolutions": ["1k", "2k", "4k"],
        "pricing_tiers": [
          { "label": "1k", "resolution": "1k", "billing_unit": "image", "credits": "5", "credits_micros": 5000000 }
        ]
      }
    ],
    "video": [
      {
        "slug": "google-veo3_1-lite",
        "display_name": "Google Veo 3.1 Lite",
        "modality": "video",
        "resolutions": ["720p", "1080p"],
        "pricing_tiers": [
          { "label": "720p", "resolution": "720p", "billing_unit": "second", "credits": "25", "credits_micros": 25000000 }
        ]
      }
    ]
  }
}

GET/v1/models/credits/catalog

cURL example

curl --location 'https://api.lumixai.live/v1/models/credits/catalog'

Example response

{
  "data": {
    "image": [
      {
        "slug": "imagen-nano-banana-2-flash",
        "display_name": "Nano Banana 2",
        "modality": "image",
        "credits": "5",
        "image_credit_micros_per_unit": 5000000
      }
    ],
    "video": [
      {
        "slug": "google-veo3_1-lite",
        "display_name": "Google Veo 3.1 Lite",
        "modality": "video",
        "credits": "25",
        "image_credit_micros_per_unit": 25000000
      }
    ]
  }
}

Resolution cap example

curl --location 'https://api.lumixai.live/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"
  }'

Google

14 models

Imagen 3imagen3Imagen 4imagen4Imagen 4 Fastimagen4-fastImagen 4 Ultraimagen4-ultraNano Bananaimagen-nano-bananaNano Banana 2 Proimagen-nano-banana-2Nano Banana 2 Flashimagen-nano-banana-2-flashNano Banana 2 Liteimagen-nano-banana-2-liteGemini Omni Flashgemini-omni-previewGoogle Veo 3google-veo3Google Veo 3.1google-veo3_1Google Veo 3.1 Fastgoogle-veo3_1-fastGoogle Veo 3.1 Litegoogle-veo3_1-liteGoogle Veo 3 Fastgoogle-veo3-fast

OpenAI

7 models

GPT Image 1.5 HQgpt-1-5-highGPT Image 1.5gpt-1-5-mediumGPT Image 2gpt-2GPT Image HQgpt-highGPT Imagegpt-mediumOpenAI Sora 2 Proopenai-sora2-proOpenAI Sora 2openai-sora2-standard

Kling

10 models

Kling 2.1kling-21Kling 2.1 Masterkling-21-masterKling 2.5kling-25Kling 2.6kling-26Kling 3.0kling-30Kling 3.0 Turbokling-30-turboKling 2.6 Motion Controlkling-motion-controlKling 3.0 Motion Controlkling-motion-control-30Kling O1kling-omni1Kling 3.0 Omnikling-omni3

Wan

8 models

Happy Horsehappy-horse-1Happy Horse 1.1happy-horse-1-1Happy Horse Edithappy-horse-1-editWan 2.2wan-2-2Wan 2.2 Animate Movewan-2-2-animateWan 2.5wan-2-5Wan 2.6wan-2-6Wan 2.7wan-2-7

ByteDance

5 models

Omni Human 1.5bytedance-omnihuman-lipsyncSeedance 2.0 Fastbytedance-seedance-fast-2.0Seedance 2.0 Minibytedance-seedance-mini-2.0Seedance 1.5 Probytedance-seedance-pro-1.5Seedance 2.0bytedance-seedance-pro-2.0

Runway

4 models

Runway Gen4runway-gen4Runway Act Tworunway-act-twoRunway Gen-4.5runway-gen45Runway Gen 4runway-std

MiniMax

4 models

MiniMax Live Illustrationsminimax-video-01-live2dMiniMax Hailuo 02minimax-video-02MiniMax Hailuo 2.3minimax-video-2_3MiniMax Hailuo 2.3 Fastminimax-video-2_3-fast

PixVerse

2 models

PixVerse 5.5pixverse-5-5PixVerse 6pixverse-6

LTX Studio

2 models

LTX 2 Fastltx-ltx2-fastLTX 2 Proltx-ltx2-pro

Black Forest Labs

11 models

Flux.1 FastfluxFlux.2 Proflux-2Flux.2 Flexflux-2-flexFlux.2 Kleinflux-2-kleinFlux.2 Maxflux-2-maxFlux.2 Turboflux-2-turboFlux.1 Devflux-devFlux.1 Kontext Proflux-kontextFlux.1 Kontext Maxflux-kontext-highFlux.1.1 Proflux-pro-plusFlux.1 Realismflux-realism

Seedream

5 models

Seedream 4seedream-4Seedream 4 4Kseedream-4-4kSeedream 4.5seedream-4-5Seedream 5 Liteseedream-5-liteSeedream 5 Proseedream-5-pro

Alibaba

2 models

QwenqwenZ-Image Turboz-image

Freepik

7 models

Mystic 1.0mysticMystic 2.5mystic-2-5Mystic Editorial Portraitsmystic-2-5-editorialMystic 2.5 Flexiblemystic-2-5-flexibleMystic 2.5 Fluidmystic-2-5-fluidMystic Super Realmystic-2-5-super-realMystic Zenmystic-2-5-zen

Veed

3 models

Veed Fabric 1.0veed-fabric-1.0Veed Fabric 1.0 Fastveed-fabric-1.0-fastVeed Sync 2.0veed-sync-2-v2v

xAI

3 models

GrokgrokGrokgrok-defaultGrok Imagine 1.5grok-imagine-video-1-5

LumixAI

4 models

CinematiccinematicKrea 2krea-2Luma Uni 1luma-uni-1MAI Image 2.5mai-image-2-5

Recraft

3 models

Recraft V4recraft-v4Recraft V4.1recraft-v4-1Recraft V4 Prorecraft-v4-pro

Ideogram

2 models

IdeogramideogramIdeogram 4ideogram-4

Schemas

Request and response fields

Use these tables as the implementation contract. 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. Up to 5 inline reference objects such as { image: dataURI } or { imageUrl: url }. Forwarded to Spaces img2img as images[] or imageUrls[].
`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.

VideoGenerationRequest

Field	Type	Notes
`model`	`string`	Required. Video model slug, for example google-veo3_1-lite.
`prompt`	`string`	Required for text-to-video. Natural language prompt for the video.
`aspectRatio`	`string`	Optional. Common values include 16:9, 9:16, or 1:1. Read supported values from /v1/videos/models and /v1/models?category=video.
`resolution`	`string`	Optional. Common values include 720p or 1080p when supported by the model.
`duration`	`integer`	Optional. Duration in seconds. Read supported values from /v1/videos/models.
`withSoundEffects`	`boolean`	Optional. Request sound effects when the selected model supports sound.
`image`	`string`	Optional. Data URI or base64 source image for image-to-video.
`imageUrl`	`string`	Optional. Remote source image URL for image-to-video.
`refCreationId`	`string`	Optional. Existing upstream creation id to use as the start frame.
`images`	`string[]`	Optional. Multiple data URI source images for image-to-video, up to 5.
`imageUrls`	`string[]`	Optional. Multiple remote source image URLs for image-to-video, up to 5 total references.
`refCreationIds`	`string[]`	Optional. Multiple upstream creation ids for image-to-video, up to 5 total references.
`endImage`	`string`	Optional. Data URI or base64 end frame for models whose refs include endFrame.
`endImageUrl`	`string`	Optional. Remote end frame URL for models whose refs include endFrame.
`endRefCreationId`	`string`	Optional. Existing upstream creation id to use as the end frame.
`maxRefs`	`integer`	Optional. Start/reference cap. Must be between 0 and 5; end frame is separate.
`spaceId`	`string`	Optional. Magnific Space UUID. If omitted, backend uses env or active Space context.
`folderRef`	`string`	Optional. Folder reference in Magnific.
`timeoutMs`	`integer`	Optional. Provider wait timeout in milliseconds.

VideoJobStatusResponse

Field	Type	Notes
`id`	`string`	Video job id used by GET /v1/videos/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 video file.
`data[].web_url`	`string`	Optional upstream web URL when returned by the provider.
`data[].preview_url`	`string`	Optional upstream preview URL when returned by the provider.
`error`	`string`	Human-readable error message when status is error. Reserved credits are refunded automatically on failed generation.
`usage.video_count`	`number`	Video seconds charged or reserved.

Endpoint map

Method	Path	Auth	Use
`GET`	`/v1/models`	none	List public active models. Optional category=image, video, or all.
`GET`	`/v1/models/catalog`	none	List public active models grouped by image and video.
`GET`	`/v1/models/credits`	none	List public model credit costs. Optional category=image, video, or all.
`GET`	`/v1/models/credits/catalog`	none	List model credit costs grouped by image and video.
`GET`	`/v1/videos/models`	none	List live video model capabilities such as durations, aspect ratios, resolutions, sound, and image-to-video support.
`POST`	`/v1/images/generations`	X-API-Key	Synchronous Magnific Spaces generation.
`POST`	`/v1/images/quote`	X-API-Key	Quote image generation cost before creating a job.
`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.
`POST`	`/v1/videos/jobs`	X-API-Key	Create an async video generation job.
`GET`	`/v1/videos/jobs/{id}`	X-API-Key	Poll an async video job.
`GET`	`/v1/videos/results/{id}/download`	X-API-Key	Stream generated video file through LumixAI.

Errors

Read error.type first

Errors return JSON with error.type and error.message. Provider internals are normalized before returning to 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`	Request rate limit exceeded.
`503`	`service_unavailable`	Provider or upstream generation service is unavailable.

Example response

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

Test full flow in Playground

Playground uses the same inline reference, async job, polling, and download flow shown here.

Open playground