luma-ray-video

What it does

Directs and operates Luma Ray video generation through the Luma Agents API (ray-3.2) for text/video, image-to-video, edits, reframes, HDR/EXR, pricing and approvals, async delivery, migration, rights, privacy, and production QA. It emphasizes using the Agents API surface for new code and treats the legacy Dream Machine API as a compatibility layer. It differentiates three surfaces (Agents API, Luma App, Dream Machine) and specifies prompts, output formats, and pricing rules.

How it works

• Uses the current developer surface: Luma Agents API at base URL https://agents.lumalabs.ai/v1 with Bearer token LUMA_AGENTS_API_KEY and model ray-3.2.
• Supports generation types: video, video_edit, video_reframe via POST /v1/generations; polls via GET /v1/generations/{id}.
• Distinguishes from consumer app (Luma App) and legacy Dream Machine API; uses Luma Agents API for new code; treats Dream Machine as legacy compatibility surface.
• Defines capabilities and constraints for Ray 3.2: text-to-video, image-to-video with anchors or multi-keyframes, extend, and reframe; specifies frame durations, resolutions, and aspect ratios (e.g., 9:16, 3:4, 1:1, 4:3, 16:9, 21:9) and output MP4s with selectable resolutions (360p–1080p).
• For edits, requires exactly one source (generation_id, file_id, or URL/base64 with media_type) with per-channel duration limits; starts with video.edit.auto_controls: true and provides nine strength controls or per-signal controls (pose, depth, normals, trajectory, face), noting mutual exclusivity with auto_controls.
• For reframing, requires a source and target aspect_ratio; SDR only; per-source limits and 200 MB per source for URL/data.
• Includes pricing guidance and the requirement to create an approval record before paid POSTs, with explicit fields (canonical request, model/type, reference hashes, price, timestamp, max USD, rights, retention, approver, expiry), and failure modes on invalid/insufficient approvals.
• Provides example request bodies demonstrating video, keyframes, and edits, including the use of video properties like duration, resolution, HDR, and end_frame/start_frame semantics.

When to use it

Use for Ray 3.2 video generation needs (text/video, image/video, edits, reframing) when working with the Luma Agents API (ray-3.2). Before any paid POST, ensure an approval record exists with the canonical request and price, and that the approval maximum is sufficient.

What it can touch

• API: https://agents.lumalabs.ai/v1
• Model: ray-3.2
• Generation types: video, video_edit, video_reframe (via POST /v1/generations)
• Polling: GET /v1/generations/{id}
• Requires: LUMA_AGENTS_API_KEY sent as Bearer token; supports headers and request bodies shown in examples

Caveats

• Volatile facts verified on 2026-07-10; recheck model page, schema, price, and limits before paid runs.
• Legacy Dream Machine API remains documented; do not send legacy fields to the Agents API.
• Pricing figures are from 2026-07-10 and may change; recheck before execution.
• HDR/EXR and certain features have specific constraints (e.g., HDR requires 720p/1080p and 5 s for type video; EXR only when exr_export is true).
• Approvals must be complete before paid POSTs; the dry-run example shows idempotency and tracing behavior but is not a guarantee of success.