Luma Provider

Luma AI provides state-of-the-art image generation models through their Dream Machine platform. Their models offer ultra-high quality image generation with superior prompt understanding and unique capabilities like character consistency and multi-image reference support.

Setup

The Luma provider is available via the @ai-sdk/luma module. You can install it with

pnpm add @ai-sdk/luma

Provider Instance

You can import the default provider instance luma from @ai-sdk/luma:

import { luma } from '@ai-sdk/luma';

If you need a customized setup, you can import createLuma and create a provider instance with your settings:

import { createLuma } from '@ai-sdk/luma';

const luma = createLuma({
  apiKey: 'your-api-key', // optional, defaults to LUMA_API_KEY environment variable
  baseURL: 'custom-url', // optional
  headers: {
    /* custom headers */
  }, // optional
});

You can use the following optional settings to customize the Luma provider instance:

• baseURL string

  Use a different URL prefix for API calls, e.g. to use proxy servers. The default prefix is https://api.lumalabs.ai.

• apiKey string

  API key that is being sent using the Authorization header. It defaults to the LUMA_API_KEY environment variable.

• headers Record<string,string>

  Custom headers to include in the requests.

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  Custom fetch implementation. You can use it as a middleware to intercept requests, or to provide a custom fetch implementation for e.g. testing.

Image Models

You can create Luma image models using the .image() factory method. For more on image generation with the AI SDK see generateImage().

Basic Usage

import { luma } from '@ai-sdk/luma';
import { experimental_generateImage as generateImage } from 'ai';
import fs from 'fs';

const { image } = await generateImage({
  model: luma.image('photon-1'),
  prompt: 'A serene mountain landscape at sunset',
  aspectRatio: '16:9',
});

const filename = `image-${Date.now()}.png`;
fs.writeFileSync(filename, image.uint8Array);
console.log(`Image saved to ${filename}`);

Image Model Settings

When creating an image model, you can customize the generation behavior with optional settings:

const model = luma.image('photon-1', {
  maxImagesPerCall: 1, // Maximum number of images to generate per API call
  pollIntervalMillis: 5000, // How often to check for completed images (in ms)
  maxPollAttempts: 10, // Maximum number of polling attempts before timeout
});

Since Luma processes images through an asynchronous queue system, these settings allow you to tune the polling behavior:

• maxImagesPerCall number

  Override the maximum number of images generated per API call. Defaults to 1.

• pollIntervalMillis number

  Control how frequently the API is checked for completed images while they are being processed. Defaults to 500ms.

• maxPollAttempts number

  Limit how long to wait for results before timing out, since image generation is queued asynchronously. Defaults to 120 attempts.

Model Capabilities

Luma offers two main models:

Both models support the following aspect ratios:

• 1:1
• 3:4
• 4:3
• 9:16
• 16:9 (default)
• 9:21
• 21:9

For more details about supported aspect ratios, see the Luma Image Generation documentation.

Key features of Luma models include:

• Ultra-high quality image generation
• 10x higher cost efficiency compared to similar models
• Superior prompt understanding and adherence
• Unique character consistency capabilities from single reference images
• Multi-image reference support for precise style matching

Advanced Options

Luma models support several advanced features through the providerOptions.luma parameter.

Image Reference

Use up to 4 reference images to guide your generation. Useful for creating variations or visualizing complex concepts. Adjust the weight (0-1) to control the influence of reference images.

// Example: Generate a salamander with reference
await generateImage({
  model: luma.image('photon-1'),
  prompt: 'A salamander at dusk in a forest pond, in the style of ukiyo-e',
  providerOptions: {
    luma: {
      image_ref: [
        {
          url: 'https://example.com/reference.jpg',
          weight: 0.85,
        },
      ],
    },
  },
});

Style Reference

Apply specific visual styles to your generations using reference images. Control the style influence using the weight parameter.

// Example: Generate with style reference
await generateImage({
  model: luma.image('photon-1'),
  prompt: 'A blue cream Persian cat launching its website on Vercel',
  providerOptions: {
    luma: {
      style_ref: [
        {
          url: 'https://example.com/style.jpg',
          weight: 0.8,
        },
      ],
    },
  },
});

Character Reference

Create consistent and personalized characters using up to 4 reference images of the same subject. More reference images improve character representation.

// Example: Generate character-based image
await generateImage({
  model: luma.image('photon-1'),
  prompt: 'A woman with a cat riding a broomstick in a forest',
  providerOptions: {
    luma: {
      character_ref: {
        identity0: {
          images: ['https://example.com/character.jpg'],
        },
      },
    },
  },
});

Modify Image

Transform existing images using text prompts. Use the weight parameter to control how closely the result matches the input image (higher weight = closer to input but less creative).

// Example: Modify existing image
await generateImage({
  model: luma.image('photon-1'),
  prompt: 'transform the bike to a boat',
  providerOptions: {
    luma: {
      modify_image_ref: {
        url: 'https://example.com/image.jpg',
        weight: 1.0,
      },
    },
  },
});

For more details about Luma's capabilities and features, visit the Luma Image Generation documentation.