vercel/ai · error · Error

Luma AI image supports up to 4 reference images. You provide

Error message

Luma AI image supports up to 4 reference images. You provided ${files.length} images.

What it means

Thrown by getEditingOptions when the 'image' reference type receives more than 4 files. Luma's image reference editing mode accepts at most 4 reference images, so the SDK enforces the limit client-side before calling the API.

Source

Thrown at packages/luma/src/luma-image-model.ts:269

            'Please provide image URLs using `prompt.images` with publicly accessible URLs. ' +
            'Base64 and Uint8Array data are not supported.',
        );
      }
    }

    // Default weights per reference type
    const defaultWeights: Record<LumaReferenceType, number> = {
      image: 0.85,
      style: 0.8,
      character: 1.0, // Not used, but defined for completeness
      modify_image: 1.0,
    };

    switch (referenceType) {
      case 'image': {
        // Supports up to 4 images
        if (files.length > 4) {
          throw new Error(
            'Luma AI image supports up to 4 reference images. ' +
              `You provided ${files.length} images.`,
          );
        }
        options.image = files.map((file, index) => ({
          url: (file as { type: 'url'; url: string }).url,
          weight: imageConfigs[index]?.weight ?? defaultWeights.image,
        }));
        break;
      }

      case 'style': {
        // Style ref accepts an array but typically uses one style image
        options.style = files.map((file, index) => ({
          url: (file as { type: 'url'; url: string }).url,
          weight: imageConfigs[index]?.weight ?? defaultWeights.style,
        }));
        break;

View on GitHub (pinned to 69428b1f8b)

Solutions

Reduce the reference images to at most 4, prioritizing the most relevant ones.
Split the request into multiple generations with different reference subsets.
Combine/merge reference images into a single composite image before sending.
Use a provider with a higher multi-image reference limit if more than 4 is essential.

Example fix

// before
const refs = allReferences; // 6 images
await generateImage({ model: luma.image('photon-flash-1'), prompt: { text: 'style match', images: refs, referenceType: 'image' } });
// after
const refs = allReferences.slice(0, 4);
await generateImage({ model: luma.image('photon-flash-1'), prompt: { text: 'style match', images: refs, referenceType: 'image' } });

Defensive patterns

Strategy: validation

Validate before calling

if ((images ?? []).length > 4) {
  throw new Error(`Luma image references accept at most 4 images, got ${images.length}`);
}

Try / catch

try {
  await generateImage({ model: lumaImage, prompt: { ...prompt, images } });
} catch (e) {
  if (e instanceof Error && e.message.includes('up to 4 reference images')) {
    return generateImage({ model: lumaImage, prompt: { ...prompt, images: images.slice(0, 4) } });
  }
  throw e;
}

Prevention

Cap reference selection UIs at 4 images when targeting Luma.
Slice/curate reference arrays defensively before submission.
Write unit tests asserting reference counts per provider mode.
Encode per-provider limits in a shared constants module.

When it happens

Trigger: Calling generateImage with a luma image model using image references (e.g. referenceType 'image') and providing 5 or more images in prompt.images / the files array.

Common situations: Building mood-board style generations with many inspiration images; programmatically fanning out collections of assets as references without capping the count; migrating from providers with higher reference limits.

Related errors

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/4908fe46fc5df470. Report an issue: GitHub.