Luma AI's Dream Machine is one of the more visually distinctive AI video tools out there, known for photorealistic lighting and smooth camera motion. But before you start integrating, there's a nuance worth knowing upfront: the consumer app and the developer API aren't always running the same model version. This guide covers what's actually available through the developer API today, not just what's in the web app.
What Is the Luma Dream Machine API?
Dream Machine is Luma's video generation platform, built on Luma's Ray series of models. On the consumer web app, Luma has moved fast: Ray3 shipped in September 2025 as what Luma called the first "reasoning" video model with native HDR support, and by mid-2026 the app was running Ray3.14 and then Ray3.2, each adding faster generation, higher resolution, and more creative controls like multi-keyframe support.
The developer-facing Dream Machine API, at api.lumalabs.ai, is a separate surface with its own versioning, and for most of the past year it lagged behind the consumer app: it only exposed Ray 2 and Ray 2 Flash, accessed through a single /generations endpoint. That gap closed in June 2026, when Luma opened up Ray3.2 through a new, separate product called the Luma Agents API. It exposes the full Ray3.2 control surface (multi-keyframe direction with up to 16 keyframes per clip, native HDR generation, 16-bit EXR export for professional color pipelines) alongside a new image model called Uni-1, but it's a distinct integration from the Dream Machine API this guide is about: its own keys, its own billing, its own request format.
This guide focuses on the original Dream Machine API (Ray 2 and Ray 2 Flash), since that's still what most existing integrations, including Apiframe's, are built on. If Ray3.2's frame-level control and HDR output are specifically what you're after, look at the Luma Agents API directly; the rest of this guide doesn't apply there.
Ray 2 itself is still a capable model: text-to-video, image-to-video, start/end keyframes, video extension, looping, and camera motion control are all supported.
Key Features
Ray 2 Video Generation
Ray 2 generates videos at up to 1080p (the API defaults to 720p unless you request otherwise), in 5 or 9 second clips. It handles camera motion through a concepts parameter, a large library of named camera moves (pan, orbit, dolly zoom, aerial, handheld, and dozens more) that you attach to a generation request instead of trying to describe camera movement purely through the prompt.
Text-to-Video and Image-to-Video Modes
You can generate from a text prompt alone, or anchor the generation with a start image, an end image, or both (keyframes), which is useful for things like transitioning between two specific scenes or animating a static product photo. Ray 2 also supports extending an existing generated video forward or backward, and interpolating between two separate generations.
Luma API Pricing
Pricing here depends on which surface you're using, and this is where a lot of confusion comes from.
Dream Machine web app (consumer): the free tier gives roughly 80 credits per day, enough for about one short clip every 24 hours, capped at 720p, watermarked, and unused credits don't roll over. Paid consumer plans start in the low $20s per month for entry-level 1080p access, running up to around $150 to $300 a month for the top individual tiers with 4K and higher monthly allotments. Exact tier names and prices shift fairly often, so treat these as ballpark figures and check Luma's own pricing page for the current lineup.
Developer API (Dream Machine, Ray 2 / Ray 2 Flash): web app credits do not carry over here. This API is billed separately as pay-as-you-go per generation, with reported per-clip pricing around $0.60 for a 5-second Ray 2 Flash clip at 720p, up to roughly $0.95 to $1.05 for a 5-second Ray 2 clip at 1080p or 4K. Exact current rates are best confirmed on your account's billing dashboard, since per-model pricing gets adjusted as new model versions roll out.
Luma Agents API (Ray3.2), separate product: pricing here is structured differently, per second rather than per clip, and scales with resolution and dynamic range. As of this writing, a 5-second 1080p standard-dynamic-range generation runs about $1.20, with HDR output priced at roughly 2x that and HDR-plus-EXR at roughly 3x. There's also a Provisioned Throughput tier for production workloads that need guaranteed capacity and a latency SLA, billed monthly per unit of reserved throughput instead of per generation.
Getting Started: Official API Setup
Create an account and generate a key at lumalabs.ai/dream-machine/api/keys.
Pass the key as a Bearer token in the Authorization header on every request.
The base URL is https://api.lumalabs.ai/dream-machine/v1.
curl --request POST \
--url https://api.lumalabs.ai/dream-machine/v1/generations \
--header 'accept: application/json' \
--header 'authorization: Bearer YOUR_LUMA_API_KEY' \
--header 'content-type: application/json' \
--data '{
"prompt": "a cinematic aerial shot over a misty mountain range at sunrise",
"model": "ray-2",
"resolution": "720p",
"duration": "5s"
}'Official API vs. Apiframe Access
For the classic Dream Machine API covered in this guide, the direct Luma API and Apiframe are working from the same underlying model generation: Ray 2 and Ray 2 Flash. So the choice isn't really about which one gets you newer model access, it's about integration overhead. Going direct to Luma means a dedicated key, its own billing dashboard, and its own request/response shape to build around. Going through Apiframe gets you the same Ray 2 and Ray 2 Flash models alongside Kling, Hailuo, Seedance, Runway, Veo, and others, all under one API key, one credit balance, and one consistent job-polling pattern (POST /v2/videos/generate, then poll GET /v2/jobs/:id).
That consistency matters most if you're already building video generation into a product that needs more than one model, since you're not maintaining N different auth schemes and N different response formats for N providers. One caveat worth flagging: if Ray3.2's newer capabilities (multi-keyframe direction, native HDR, EXR export) are specifically what you need, that model currently lives only on Luma's separate Agents API, and Apiframe doesn't offer it yet. Going direct to Luma is your only option there for now.
How to Call the Luma API: Code Example
Here's a complete example using Apiframe's unified endpoint, which mirrors the same core request shape (prompt, model, duration, aspect ratio) as the direct Luma API but wraps it in the same submit-and-poll pattern used across every model Apiframe supports:
import requests
import time
API_KEY = "afk_your_api_key_here"
BASE_URL = "https://api.apiframe.ai/v2"
headers = {
"X-API-Key": API_KEY,
"Content-Type": "application/json",
}
# 1. Submit the generation request
payload = {
"prompt": "a cinematic aerial shot over a misty mountain range at sunrise",
"model": "luma-ray-2",
"lumaParams": {
"duration": 5,
"aspect_ratio": "16:9",
},
}
response = requests.post(f"{BASE_URL}/videos/generate", headers=headers, json=payload)
response.raise_for_status()
job_id = response.json()["jobId"]
print(f"Job submitted: {job_id}")
# 2. Poll for the result
while True:
job = requests.get(f"{BASE_URL}/jobs/{job_id}", headers=headers).json()
if job["status"] == "COMPLETED":
print("Video ready:", job["result"]["videoUrl"])
break
elif job["status"] == "FAILED":
print("Generation failed:", job.get("error"))
break
time.sleep(5)Credit cost for luma-ray-2 is 153 credits for a 5-second clip and 276 credits for 9 seconds; luma-ray-flash-2 runs 51 credits for 5 seconds and 92 for 9 seconds, roughly a third of the standard model's cost, which tracks with Luma's own pricing where Flash is the cheaper, faster variant.
Use Cases
Ray 2's strengths (photorealistic lighting, smooth camera moves, and coherent motion) show up well in a handful of practical use cases: short marketing video snippets that don't need dialogue, product demo b-roll from a still photo, social content where a few seconds of polished motion beats a static image, and storyboard or animatic previews before committing budget to a full production shoot.
FAQ
Is there a genuinely free tier? On the consumer web app, yes: about 80 credits per day, resetting daily, capped at 720p with a watermark. The developer Dream Machine API does not have a comparable free tier; it's pay-as-you-go from the first request, though new accounts sometimes get trial credit (worth checking your dashboard when you sign up).
How long does a generation take? This varies by load and clip length, generally in the range of tens of seconds to a couple of minutes for a 5 to 9 second clip. Poll rather than assume a fixed time.
What resolutions and durations are supported? Through the developer Dream Machine API, Ray 2 supports 540p, 720p, 1080p, and 4K, in 5 or 9 second clips.
Does it support image-to-video? Yes, using the keyframes parameter with a frame0 (start image), frame1 (end image), or both.
If you're weighing Luma against other video models like Kling or Hailuo for the same project, Apiframe's video model docs let you compare parameters and credit costs side by side before you commit to one.