Luma Ray 3.2 API Guide: Building Consistent Multi-Shot AI Videos

Luma released Ray 3.2 on June 9, 2026, with a production-oriented control surface and an API. The important change is not simply higher visual quality. Ray 3.2 can generate clips, transform existing footage, place visual anchors at selected moments, reframe an output, and export formats intended for a post-production pipeline.

That makes it a strong candidate for multi-shot work, but “supports keyframes” is not the same as “guarantees a consistent film.” A sequence still needs explicit continuity rules, durable job state, evaluation, and a separate finishing step. This guide describes that system without assuming a native connection to any editor or media service.

What the current API actually exposes

The current Luma Agents documentation lists ray-3.2 for five related operations:

• text-to-video with type: "video";
• image-to-video using a start frame, end frame, or indexed keyframes;
• video editing with type: "video_edit" and a source clip;
• video reframing with type: "video_reframe";
• extension by referencing a prior generation as a start or end frame.

It also documents seamless loops, HDR output at supported resolutions, and an EXR export when HDR is enabled. Standard video output is MP4. Those modes share POST /v1/generations, then use a submit-poll-download lifecycle.

There is one documentation detail worth handling carefully. Luma’s June announcement and API landing page describe up to 16 keyframes in a clip. The current Luma Agents model guide lists up to 64 anchors through video.keyframes and video.keyframe_indexes. That may reflect an expanded API after launch or a difference between surfaces. Do not hard-code a marketing number as a permanent contract. Validate the live request schema, keep a server-side limit, and log validation errors by request ID.

Start with a sequence specification

Before calling a model, create a compact shot bible. It should define facts the sequence must preserve:

• character appearance, wardrobe, props, and handedness;
• product shape, materials, labels, and approved colors;
• environment geometry, time of day, weather, and light direction;
• lens language, camera movement, frame rate, and aspect ratio;
• prohibited changes, such as extra text or an altered logo;
• the intended first and last state of every shot.

Turn that bible into a structured record rather than pasting an essay into every prompt. Each shot can reference a versioned character sheet, product reference, palette, and environment frame. When an art director approves a new detail, update the version once and regenerate only affected shots.

Consistency should be testable. “Same red jacket” can become a color range and reference crop. “Same package” can become silhouette and text checks. “Continuous action” can become a comparison between the final frames of shot A and the opening frames of shot B.

Define the cut before generating the shots. A useful shot record includes planned duration, transition type, entry motion, exit motion, and a few frames of editorial handle at each end. If shot A ends during a fast leftward pan, shot B should either continue that energy or make an intentional contrast. Asking a model for isolated beautiful clips and deciding their order later often produces mismatched screen direction and pacing.

Separate continuity into fixed and flexible fields. Product geometry and wardrobe may be fixed, while camera angle and background action can vary. This prevents a reviewer from rejecting legitimate variation or accepting a change that violates the brief. Store those fields beside every take so selection is based on the same contract.

Use keyframes as contracts, not decoration

A keyframe is most useful when it settles a visible decision. For an image-to-video shot, an approved start frame establishes identity and composition. An end frame establishes the target pose or camera destination. Indexed anchors can protect intermediate story beats.

Dense keyframing is not automatically better. Conflicting anchors can force abrupt interpolation, distorted motion, or a visual compromise that matches none of them. Begin with the fewest anchors that define the shot:

1. lock the opening composition;
2. add an ending anchor when the destination matters;
3. add an intermediate anchor only for a critical beat;
4. review motion between anchors before adding more.

For a sequence, reuse approved visual sources instead of exporting an arbitrary generated frame every time. If the end of one shot must become the beginning of the next, store that exact frame, its generation ID, checksum, crop, and approval status.

Submit, poll, and download safely

The API returns a generation object with an opaque ID and a state such as queued, processing, completed, or failed. A controller should persist the ID before it begins polling. That prevents a worker restart from submitting a duplicate paid generation.

A simplified request envelope looks like this:

{
  "model": "ray-3.2",
  "type": "video",
  "prompt": "A measured dolly move around the approved product, preserving shape and lighting",
  "aspect_ratio": "16:9",
  "video": {
    "duration": "5s",
    "resolution": "720p"
  }
}

The exact allowed fields depend on operation and may evolve, so use the official SDK or live reference when implementing. A robust worker applies exponential backoff, records the request trace identifier, stops on terminal failures, and distinguishes rate limiting from moderation, invalid input, exhausted budget, and generation failure.

Luma’s current docs say output presigned URLs expire after one hour. Download promptly into storage you control, or poll the generation again for a fresh URL. Store the media checksum and generation metadata beside the asset; an expiring URL is not an archive.

Budget by accepted shot

Luma’s API page lists pay-as-you-go SDR prices by operation, duration, and resolution. At the time of writing, a 10-second text- or image-to-video request is shown at approximately $0.45 for 540p, $0.90 for 720p, and $3.60 for 1080p. Video-to-video and professional HDR or EXR options cost more. Pricing and availability can change, so query the current page before committing a campaign budget.

The useful metric is not price per request. It is cost per accepted shot. If a $0.90 request requires six attempts, the generation cost is already $5.40 before storage, review, and finishing. Track acceptance rate by shot type, prompt version, resolution, and continuity requirement.

Use draft resolution for composition experiments, then promote a locked prompt and anchors to the delivery tier. Do not upscale every rejected take. Apply account-level spending limits and cap retries at the workflow level, not only inside one worker.

Capacity also affects delivery planning. Luma distinguishes shared pay-as-you-go access from provisioned throughput with a latency commitment. A prototype can tolerate queue variation; a scheduled campaign may need reserved capacity or a larger deadline buffer. Load-test the actual account and region instead of extrapolating from one interactive request.

Evaluate each clip and each cut

Single-shot review should cover prompt adherence, identity, object count, text integrity, anatomy, motion, physics, flicker, and artifacts. Sequence review adds continuity:

• Does screen direction carry across the cut?
• Does the subject begin where the prior shot ended?
• Are lighting and color temperature compatible?
• Do wardrobe, product details, and background geography persist?
• Does motion cadence feel intentional rather than randomly reset?

Automated vision checks can flag large changes, black frames, unexpected text, or missing audio tracks, but they should not be the final authority for a branded or public asset. Preserve reviewer notes so later prompts address real failure patterns instead of accumulating vague adjectives.

Separate generation from final assembly

Ray 3.2 can create controlled shots, yet the final deliverable still needs ordering, transitions, branding, audio, and export validation. Keeping that stage separate makes the pipeline easier to retry. A failed logo placement should not trigger another expensive generation.

For a Medux-based path, an authorized Codex or Claude MCP client can invoke a specific downstream operation after shots have passed review. Medux is not built into Ray 3.2, and this workflow does not claim that Luma sends outputs to Medux automatically.

The Claude MCP video-merge tutorial shows a practical assembly lifecycle: obtain signed upload locations, upload approved clips, create an asynchronous task, poll its status, and download the result. The logo-on-video tutorial can be a later, independent branding step.

Persist a manifest containing ordered clip checksums, Medux task IDs, transition choices, and the accepted output checksum. If assembly fails, resume from that manifest instead of regenerating Ray shots. This division of responsibility is the foundation of a reliable multi-shot system: Ray 3.2 directs individual images through time, while explicit orchestration, review, and finishing turn those shots into one accountable sequence.