What Is the Uni-1 API and How Do I Use It for Image Generation and Editing?

Category: Product Education Tags: Uni-1, API, image generation, image editing, text-to-image, reference images, modify image, Luma Agents

Introduction

Uni-1 is Luma's multimodal reasoning image model that combines image understanding and generation in a single architecture. This guide covers how to access the API, use both generation and editing endpoints, work with reference images, and optimize prompts for professional results. Whether you're generating new images or editing existing ones, Uni-1 provides unified creative control through one API.

Understanding Uni-1's Unified Architecture

Uni-1 represents a fundamental shift in AI image generation. Unlike traditional diffusion-based models that pull images from noise, Uni-1 uses autoregressive generation — the same token-by-token prediction method that powers large language models — to reason about what it's creating as it creates it. There is no handoff between a system that understands a prompt and a separate system that generates the image. Understanding and generation share the same processing pipeline, running on one set of weights.

This unified approach enables Uni-1 to reason through complex instructions, maintain context across iterative edits, and evaluate its own outputs during the creation process. In human preference Elo rating tests, Uni-1 ranks first in overall quality, style and editing, and reference-based generation categories. It achieves state-of-the-art results on the RISEBench benchmark for reasoning-informed visual editing, demonstrating strong capabilities in temporal, causal, spatial, and logical reasoning.

Uni-1 is accessible through the Luma API at lumalabs.ai/api and through the Luma Agents creative platform. It handles both image generation (text-to-image) and image editing (modifying existing images with text instructions) through dedicated API endpoints.

Getting Started with the Uni-1 API

Setting Up API Access

Step 1: Create Your Developer Account

Navigate to lumalabs.ai/api and create an account. Once registered, access the developer dashboard where you can generate your API key. Full quickstart guides and authentication instructions are available at docs.lumalabs.ai.

Step 2: Understand the Two Core Endpoints

Uni-1 operates through two primary endpoints, each serving a distinct creative function. The create_image endpoint generates entirely new images from text prompts, with optional support for up to 9 reference images for style, character, or content guidance. The modify_image endpoint enables prompt-based editing of existing images, where you supply a source image and text instructions describing desired changes.

Step 3: Choose Your Output Format

Configure the output_format parameter based on your needs. Use png when lossless quality is essential — ideal for graphics, illustrations, or images requiring sharp edges and fine detail preservation. Use jpeg when file size optimization matters more — best for photographs or web-optimized content. If the parameter is omitted or set to null, Uni-1 automatically selects the optimal format based on prompt content.

Generating New Images with create_image

The create_image endpoint transforms text descriptions into images. Write clear, descriptive prompts up to 6,000 characters. Uni-1 is optimized for English prompts; for best results with other languages, translate your prompt to English first.

Select from 9 supported aspect ratios: 3:1, 2:1, 16:9, 3:2, 1:1, 2:3, 9:16, 1:2, and 1:3. The default is 16:9. Output resolution is determined automatically by the model based on your chosen aspect ratio.

For guided generation, include up to 9 reference images alongside your prompt. Each reference can serve a different role — character reference, color palette, lighting guide, composition template, or style source. Specify in your prompt which elements to borrow from each reference for precise control.

Editing Existing Images with modify_image

The modify_image endpoint provides prompt-based image editing. Supply a source image and text instructions describing the changes you want. The model transforms the scene according to your instructions while preserving overall composition. The output automatically preserves the source image's original dimensions, and the aspect ratio is locked to the source.

This is prompt-based editing rather than mask-based inpainting or outpainting. Focus on clear, specific instructions about what to change and what to preserve. For example: "Change the time of day to golden hour. Update sky, light direction, shadows, and color temperature. Keep all subjects and composition unchanged."

Advanced Reference Image Techniques

Multi-Reference Workflows

Uni-1 supports sophisticated multi-reference generation where each reference image controls a different aspect of the output. Assign roles explicitly in your prompt for best results:

• Character Reference: "Use IMAGE1 (woman with short copper-red hair, freckles) as a CHARACTER reference. Preserve her features. Generate a new scene: she's sitting in a softly lit café."
• Multi-Layer References: "Use IMAGE1 as a COLOR PALETTE reference, IMAGE2 as LIGHTING, IMAGE3 as COMPOSITION. Create a lone figure walking through a rain-slicked street at night."
• Style Transfer: "Use IMAGE1 as STYLE reference. Apply its artistic treatment to a mountain landscape at dawn."

Controlling Reference Influence

There is no explicit adherence slider for reference images. Instead, control influence through prompt specificity. Being more detailed about which elements to borrow (naming specific colors, styles, composition details) increases adherence. Being vague allows more creative interpretation. Treat each reference as having authority over its assigned layer only.

Seeds for Reproducibility

Seeds transform experimentation into repeatable systems. Save your prompt and seed together as a reusable recipe. The same prompt with the same seed produces consistent results, enabling reliable production workflows.

Pricing and Cost Optimization

Token-Based Pricing Structure

Uni-1 uses token-based billing. Each image (input or output) equals approximately 2,000 billing tokens at current settings:

• Input text: $0.50 per million tokens
• Input images: $1.20 per million tokens
• Output text and thought chain: $3.00 per million tokens
• Output image tokens: $45.45 per million tokens

Per-Image Cost Estimates (2048px Resolution)

• Text-to-image generation: approximately $0.09 per image
• Image editing with single reference: approximately $0.09 per image
• Multi-reference generation (2 images): approximately $0.10 per image
• Multi-reference generation (8 images): approximately $0.11 per image
  
  (NOTE All prices above are rough approximations, and truly depend on the complexity of the output being generated)

Cost Optimization Strategies

Select appropriate aspect ratios and resolutions for your use case rather than defaulting to maximum dimensions. Batch similar generation tasks together. Use the modify_image endpoint for iterative refinement rather than regenerating from scratch. Develop prompt templates with seeds for production consistency.

Troubleshooting

• What happens if my generated image doesn't match my prompt well?: Uni-1 performs best with clear, descriptive English prompts. Ensure your prompt is specific about key elements you want included. For complex scenes, break down instructions into structured components (subject, environment, lighting, style). Check that your prompt is within the 6,000 character limit.

• Why does my modified image look completely different from the source?: In modify_image mode, precision in your instructions is essential. Specify exactly what should change AND what should remain unchanged. Use phrases like "Keep all subjects and composition unchanged" alongside your modification instructions.

• My reference images seem to have little effect on the output...: Reference influence is controlled through prompt specificity, not a slider. Be explicit about which elements to borrow from each reference. Name specific attributes: "Use IMAGE1's warm copper-red hair color and freckle pattern" works better than "Use IMAGE1 as reference."

• Why am I getting unexpected output formats?: If you omit the output_format parameter, the model automatically selects based on prompt content. Set output_format to png or jpeg explicitly to control output format consistently.

• My non-English prompts produce inconsistent results...: Uni-1 is primarily optimized for English. Translate your prompts to English before submission for the most reliable and consistent output quality.
  
  

Mini Frequently Asked Questions (FAQs)

1. What is the difference between Uni-1 and Dream Machine's Photon image model? Uni-1 is Luma's advanced multimodal reasoning model with API access, supporting up to 9 reference images, prompt-based editing, and autoregressive generation. Photon is Dream Machine's integrated image model designed for quick generation within the Dream Machine interface, primarily for creating source images for video workflows.

2. Can I use Uni-1 to generate images and then animate them in Dream Machine? Yes, images generated with Uni-1 can be downloaded and uploaded to Dream Machine as source material for Image-to-Video generation using RAY 2 or RAY 3 models.

3. Does Uni-1 support batch generation or generating multiple images at once? Refer to the API documentation at docs.lumalabs.ai for current batch generation capabilities and rate limiting details. The API is designed for production integration with standard REST architecture.

4. How does Uni-1's pricing compare to competing image generation APIs? At 2048px resolution, Uni-1 costs approximately $0.09 per text-to-image generation, which is 10-30% less than comparable models at high resolution. Token-based pricing provides predictable costs for applications with variable output volumes.

5. Can Uni-1 generate sequences or multiple related images with consistency? Yes, Uni-1 excels at sequential generation. Using character references and seeds, you can generate coherent image sequences maintaining consistency across scenes, such as aging a character over time or showing different angles of the same subject.

For a Full FAQ please visit: https://lumaai-help.freshdesk.com/en/support/solutions/articles/151000230411-how-do-i-use-the-uni-1-api- 

Related Articles

• [What Is RAY 3 and How Is It Different from Previous Models?]
• [How Do I Maintain Character Consistency Across Multiple Scenes?]
• [What Is Draft Mode and When Should I Use It?]
• [How Do Credits Work in Dream Machine?]
• [What Are Luma Agents and How Do They Work?]

Original Author: Lua AI Team
Original Creation Date: May 05, 2026
Updated by: Chris Roebuck