--- title: "Build with Luma APIs" description: "State-of-the-art image and video generation APIs for creative products, workflows, and production pipelines." canonical: "https://lumalabs.ai/api" source: "https://lumalabs.ai/api.md" --- # Build with Luma APIs State-of-the-art image and video generation APIs for creative products, workflows, and production pipelines. [Use the API](https://platform.lumalabs.ai) · [Explore docs](https://docs.agents.lumalabs.ai) ## Partners building with our API - Freepik - Envato - Fal - Comfy - Flora - Runware - Krea - Lovart - Weavy _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 ](https://platform.lumalabs.ai/) [Learn more](https://docs.agents.lumalabs.ai/guides/videos/) ### 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](https://platform.lumalabs.ai/) [Learn more](https://docs.agents.lumalabs.ai/guides/images/) ### 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 video generation to create richer multimodal creative workflows with greater consistency and control. [Contact Sales](https://lumalabs.ai/contact-sales) _Plans_ ## Build it. Scale it. ### Build Pay per image. No commitment. Ideal for prototyping and early production. [Start Building](https://lumalabs.ai/api/dashboard) - 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](https://lumalabs.ai/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 ### Ray3.2 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 | $2.16 | $4.32 | | Reframe (per second) | $0.06 | $0.12 | $0.36 | - Prices shown are SDR output - HDR output is 2× SDR pricing - HDR + EXR output is 3× SDR pricing - No minimum commitment - Rate limits apply, no latency SLA ### Uni-1.1 Pay per image. No commitment. Ideal for prototyping and early production. | Task | Resolution | Uni-1.1 | Uni-1.1 Max | | --- | --- | --- | --- | | Text to image | 2048px (2K) | $0.0404 | $0.1000 | | Image Edit | 2048px (2K) | $0.0434 | $0.1030 | | 1 image reference | 2048px (2K) | $0.0434 | $0.1030 | | 2 image references | 2048px (2K) | $0.0464 | $0.1060 | | 8 image references | 2048px (2K) | $0.0644 | $0.1240 | - Prices are approximate and based on billing tokens - No minimum commitment - Rate limits apply, no latency SLA ## API FAQs ### Ray3.2 ### 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. ### How is usage billed? 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. ### Uni-1.1 ### What is uni-1? uni-1 is Luma's unified image generation and editing model. It handles text-to-image and image-to-image through the same endpoint, with support for text rendering, spatial reasoning, multi-panel output, and style transfer. ### What is uni-1-max? uni-1-max produces higher-quality output than uni-1. It uses the same wire format and parameter set — same prompts, same aspect_ratio, same image_ref semantics. The per-image price is roughly 2.5× the uni-1 rate. Available to all accounts by passing "model": "uni-1-max" on POST /v1/generations. ### When should I use uni-1-max vs uni-1? Use uni-1 for the broad set of generation and editing tasks — it's the default and the lowest cost. Use uni-1-max when you want higher-quality output and the per-image cost increase is justified (e.g. final hero images, ad creative, anything where re-generations are expensive). The two models accept identical parameters; you can switch by changing only the model field on the request. ### Does uni-1 support non-English prompts? uni-1 is optimized for English. Other languages may work to varying degrees, but results are less reliable. Write prompts in English, or translate before sending, for best output. ### Can I reproduce the same image from the same prompt? Not deterministically. Each generation uses a different random seed and there is no public seed parameter. For visual consistency across multiple images, pair the same prompt with one or more image_ref references as style anchors. ### Does uni-1 support inpainting or outpainting with masks? No. There is no mask parameter. Editing is prompt-based: describe the change in natural language and uni-1 applies it while preserving unmentioned parts of the image. Examples: "replace the background with a tropical beach at sunset", "change the car's color to midnight blue", "convert to a bold manga illustration with clean ink outlines". ### What does web_search: true do? The model searches the web for visual references before generating, then uses what it finds to ground the output. This noticeably improves accuracy for prompts that name real-world landmarks, products, or public figures. Web search adds a few seconds of latency, so leave it off for purely imaginative prompts. ### Can I generate a video with the Luma Agents API? No. uni-1 is image-only, and type accepts image and image_edit. For video generation, see Luma's Dream Machine. ### How is pricing calculated for uni-1 and uni-1-max? Two options:Pay-as-you-go — pay per image. The price depends on the model (uni-1 or uni-1-max), the action type (image vs. image_edit), and the number of reference images. Each extra reference image adds a small increment. uni-1-max is roughly 2.5× the uni-1 rate.Provisioned Throughput — billed monthly per unit of guaranteed capacity (1 unit = 1 RPM on uni-1, 0.4 RPM on uni-1-max). Minimum 8 units; longer commitments unlock bigger discounts. ## Stop generating. Start shipping. [Use the API](https://platform.lumalabs.ai) · [Contact Sales](https://lumalabs.ai/contact-sales)