Question 1

What key capabilities are available via the API?

Accepted Answer

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.

Question 2

What output formats are supported?

Accepted Answer

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.

Question 3

Which aspect ratios are supported?

Accepted Answer

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.

Question 4

Can I outpaint a video to a different aspect ratio?

Accepted Answer

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

Question 5

What resolutions and generation lengths are supported?

Accepted Answer

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.

Question 6

How do I reference a video for editing?

Accepted Answer

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": "<base64 bytes>", "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.

Question 7

Can I extend a prior video?

Accepted Answer

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.

Question 8

Can I interpolate using a prior video?

Accepted Answer

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.

Question 9

How is usage billed?

Accepted Answer

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).

Question 10

Are there specific requirements for source videos?

Accepted Answer

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).

Question 11

Where can I test my API requests?

Accepted Answer

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.

Question 12

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

Accepted Answer

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

Question 13

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

Accepted Answer

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().

Question 14

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

Accepted Answer

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.

Question 15

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

Accepted Answer

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.

Question 16

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

Accepted Answer

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.

Question 17

Why does Extend fail with "Generation failed"?

Accepted Answer

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.

Question 18

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

Accepted Answer

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.

Question 19

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

Accepted Answer

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.

Question 20

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

Accepted Answer

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.

Question 21

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

Accepted Answer

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.

Ship cinema, not content.

What You Can Build

Direct the cut, frame by frame.

Build cinema into your pipeline.

Scale one shoot into every variant.

Better Together

Build it. Scale it.

For Building: Pay-as-you-go

Explore Other Models

Ray3.14

Ray3

API FAQs

Stop generating. Start shipping.