What key capabilities are available via the API?

The Ray 3.2 API provides the full control surface, allowing for: Multi-Keyframe: Precise storybeat control with up to 16 individual keyframes per clip. Performance Tracking: High-accuracy skeletal pose, gesture, and posture tracking. Expressive Facial Performance: Frame-by-frame transfer of expression states for up to 8 faces. Reframe: Change aspect ratios, extend frames, and replace backgrounds while preserving lighting. Motion Transfer: Extract or preserve motion from source videos. Edit Controls: Includes video.edit.strength presets and manual signal conditioning (pose, depth, normals, trajectory, face). Endpoints: Use type: "video" for generation, type: "video_edit" for editing, and type: "video_reframe" for aspect ratio changes.

What output formats are supported?

The API supports native 16-bit HDR generation and 16-bit EXR export. These formats are designed to integrate cleanly into professional pipelines like Resolve or Nuke, providing the wide gamut and color accuracy required for high-end color grading and VFX compositing.

Which aspect ratios are supported?

Ray 3.2 video accepts six: 9:16, 3:4, 1:1, 4:3, 16:9, 21:9. Video edits derive the aspect ratio from the source video and ignore the request value.

Can I outpaint a video to a different aspect ratio?

Yes, use type: 'video_reframe' with your target aspect_ratio.

What resolutions and generation lengths are supported?

Resolution: 1080p outputs are natively supported across the model. Length: V2V (Video-to-Video) generations are supported at 10, 15, or 20 seconds. Extensions: Forward and backward extensions are supported in 5-second blocks.

How do I reference a video for editing?

Three ways to reference the source video on a video_edit (or video_reframe) request: 1. Prior Luma generation — source.generation_id, using the top-level id from the original POST /v1/generations response. Must be a completed video owned by the same API key. "source": { "generation_id": "d290f1ee-6c54-4b01-90e0-d70000f000" } 2. Partner-hosted URL — source.url plus source.media_type set to a video/* MIME type (e.g. "video/mp4"). "source": { "url": "https://example.com/clip.mp4", "media_type": "video/mp4" } 3. Inline base64 — source.data paired with source.media_type. "source": { "data": " ", "media_type": "video/mp4" } Key constraints: The url and data paths are capped at a 30-second source — longer clips are rejected at ingest before any billing. (The generation_id path uses the prior generation directly, no probe.) media_type is required up front for url/data — it's not sniffed, so a missing or non-video/* value 400s. image_ref is rejected on video_edit — guide the edit through the prompt and video.edit instead.

Can I extend a prior video?

Yes, by passing a chain reference (generation_id) in either video.start_frame (forward extend) or video.end_frame (backward extend) on a type: 'video' request.

Can I interpolate using a prior video?

Yes, set both start_frame and end_frame to image refs (url or data). Do not include generations_id in either: gen↔image, image↔gen, and gen↔gen interpolation are not yet available and are rejected with a 400 error.

Video generations are billed per 5-second block (e.g., a 10-second video counts as two blocks). Pricing varies based on the request type (create vs. edit) and your chosen settings, such as resolution and dynamic range (standard vs. HDR vs. HDR + EXR).

Are there specific requirements for source videos?

All source videos must be 30 seconds or shorter, whether provided via URL, base64 data, or generation_id. (source.media_type is required for URL/data inputs).

Where can I test my API requests?

We recommend using the Playground in your developer console at platform.lumalabs.ai/console/playground. It allows you to compose and test different request shapes, chain results, and generate ready-to-use cURL commands for your integration.

I am migrating from the legacy Dream Machine video API — where's the guide? Does video pricing differ from image pricing?

A detailed migration guide is available from your Luma contact during onboarding.

Why am I getting "Unexpected token '<', is not valid JSON"?

PHP warnings or notices are outputting HTML before the JSON response. This commonly occurs when the detail field returned by the API is an array, causing an "Array to string conversion" error during concatenation. To resolve this, suppress PHP display errors at the top of your file with error_reporting(0) and ini_set('display_errors', '0'), and ensure your error handler converts array responses to strings before concatenation using json_encode().

Why do I get "Failed to download video" on Modify or V2V requests?

Video URLs hosted on your own server are not normally accessible to the Luma API. The API cannot fetch assets from shared hosting environments. To resolve this: All images must be served through a public CDN. All videos must be served through a video CDN. Your upload function must detect both relative URLs (/frames/...) and full URLs pointing to your own domain, and re-upload them before sending them to the API. Set CDN expiration to at least 3600 seconds.

Why does V2V Modify ignore my source video motion and generate from the prompt only?

The most common cause is an expired Luma CDN presigned URL. These URLs expire after approximately 1 hour. When the API cannot access the source, it silently ignores it and generates it from the prompt alone. To resolve this, check whether the source video is cached locally before submitting a V2V request. If a local copy exists, re-upload it to your CDN to obtain a fresh URL. For imported videos, CDN upload should happen at import time rather than at generation time.

Why does my HDR request fall back to Ray 3 instead of Ray 3.2?

The model string ray-3.2+hdr is not being recognized by your routing logic. The sanitizer strips the +hdr suffix, does not recognize the remaining ray-3.2, and defaults to ray-3. To resolve this, your routing must check for both ray-3.2 and ray-3.2+hdr before sanitization. When the +hdr variant is detected, set the HDR flag separately and route to the Ray 3.2 handler with the base model string. Also add ray-3.2 to your valid models array as a safety net.

Why does Extend fail with "Generation failed"?

This is usually transient and can be resolved by retrying. It can also occur when: Extending an HDR video (HDR extend is not supported by the API - standard dynamic range only). aspect_ratio or duration are omitted from the request. To resolve this, always include aspect_ratio and duration explicitly in extend requests. If failures persist after including these fields, retry the request. The API documentation notes that this error is typically transient.

Why does the cost display always show 1% regardless of the actual credit cost?

Your cost lookup table has no entries for Ray 3.2, causing the function to fall back to a flat default value of 1.0. The confirmation popup uses this incorrect value. To resolve this, implement a client-side cost calculator that mirrors your server-side pricing function. Reference costs by request type and resolution: Generate: 540p = 0.15, 720p = 0.30, 1080p = 1.20 Generate HDR: 720p = 1.20, 1080p = 4.80 Edit: 540p = 0.72, 720p = 1.08, 1080p = 2.16 Edit HDR: 720p = 2.16, 1080p = 4.32 All confirmation dialogs must use the calculated cost for the current request type, not the flat default.

Why does the Reframe panel only use Ray 2 with no engine selector?

The Reframe panel was hardcoded with a single engine and no model selection. The request function did not send a model parameter, so the backend defaulted to ray-2. To resolve this, add a model dropdown to the Reframe panel and pass the selected model in the request, defaulting to ray-3.2. Note that Reframe is standard dynamic range only - the API rejects HDR reframe requests.

Why do imported videos fail on Modify with "Failed to download video"?

Imported videos stored on your local server are inaccessible to the Luma API. When any engine attempts to modify them, the download fails. To resolve this, re-upload imported videos to your CDN at import time, not at generation time. Store the CDN URL alongside the local path so that all subsequent API requests use the publicly accessible URL.

Why are multiple videos generated from a single click (duplicate charges)?

Slow network connections cause the API request to timeout on the client side. The error handler re-enables the submit button, and the user clicks again. Each click is accepted by the API as a separate request. To resolve this, implement a processing lock that persists across timeouts. Set the lock to true before submitting, and only release it in the final resolution handler (both success and error). If the lock is active, reject additional clicks with a user-facing message.

Build with Luma APIs

State-of-the-art image and video generation APIs for creative products, workflows, and production pipelines.

Use the API Explore docs

Partners building with our API

Video Generation

Build with Ray3.2

The Ray3.2 API exposes the full control surface. Cinema-grade output, ready to drop into the pipelines you already run.

Use Ray3.2 API Learn more

Direct the cut, frame by frame.

Multi-Keyframe lets you set up to 16 keyframes inside a single clip. Direct what changes and what holds, beat by beat. Sequence-level control, exposed at the API.

Scale one shoot into every variant.

Reframe handles the backdrop. V2V handles the SKU. HDR Generation and EXR Export handle the mood. One brand system, every market, every format, generated consistently through a single API.

Build cinema into your pipeline.

1080p output across the model. V2V at up to 20 seconds. Native HDR Generation and 16-bit EXR Export so AI work composites alongside live-action plates in your users' Resolve or Nuke.

Image Generation

Build with Uni-1.1

Half the price. Half the latency. First-pass success.

Use Uni-1.1 API Learn more

Brand as infrastructure

Brand systems that update across products, pages, and campaigns at once. Messy or chained prompts work natively. No middleware or prompt engineering required.

Scale across your pipeline

Generate across markets, every shot on brand. Less than half the cost means volume math finally works. Free tiers become viable. Fewer retries compound the savings.

Two endpoints. Full intent.

One reasoning endpoint. One generation endpoint. The model thinks before it ships, so the first pass is usually the right one.

Multi-Model Workflows

Better Together

Use Uni-1 for image generation and Ray3.2 for ai video generation to create richer multimodal creative workflows with greater consistency and control.

Contact Sales

Plans

Build it. Scale it.

Build

Pay per image. No commitment.
Ideal for prototyping and early production.

Start Building

Prices are approximate and based on billing tokens.

No minimum commitment.

Rate limits apply, no latency SLA.

Scale

Dedicated capacity with guaranteed throughput and latency.
Built for production workloads at scale.

Contact Sales

1 unit = 1 request per minute (Base) or 0.4 RPM (Max).

Minimum 4 units.

Includes SLA, moderation, and prompt enhancement.

No-train guarantee.

Cost Breakdown

Pay per video. No commitment. Ideal for prototyping and early production.

Task

540p

720p

1080p

T2V/I2V (5s)

$0.15

$0.30

$1.20

T2V/I2V (10s)

$0.45

$0.90

$3.60

V2V (5s)

$0.72

$1.44

$2.16

V2V (10s)

$1.08