@ai-sdk/luma 2.0.8 → 2.0.9

package/src/luma-image-model.ts

@@ -0,0 +1,441 @@
+import {
+  ImageModelV3,
+  ImageModelV3File,
+  SharedV3Warning,
+  InvalidResponseDataError,
+} from '@ai-sdk/provider';
+import {
+  FetchFunction,
+  combineHeaders,
+  createBinaryResponseHandler,
+  createJsonResponseHandler,
+  createJsonErrorResponseHandler,
+  createStatusCodeErrorResponseHandler,
+  delay,
+  getFromApi,
+  postJsonToApi,
+  InferSchema,
+  lazySchema,
+  parseProviderOptions,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { LumaImageSettings, LumaReferenceType } from './luma-image-settings';
+import { z } from 'zod/v4';
+
+const DEFAULT_POLL_INTERVAL_MILLIS = 500;
+const DEFAULT_MAX_POLL_ATTEMPTS = 60000 / DEFAULT_POLL_INTERVAL_MILLIS;
+
+interface LumaImageModelConfig {
+  provider: string;
+  baseURL: string;
+  headers: () => Record<string, string>;
+  fetch?: FetchFunction;
+  _internal?: {
+    currentDate?: () => Date;
+  };
+}
+
+export class LumaImageModel implements ImageModelV3 {
+  readonly specificationVersion = 'v3';
+  readonly maxImagesPerCall = 1;
+  readonly pollIntervalMillis = DEFAULT_POLL_INTERVAL_MILLIS;
+  readonly maxPollAttempts = DEFAULT_MAX_POLL_ATTEMPTS;
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  constructor(
+    readonly modelId: string,
+    private readonly config: LumaImageModelConfig,
+  ) {}
+
+  async doGenerate({
+    prompt,
+    n,
+    size,
+    aspectRatio,
+    seed,
+    providerOptions,
+    headers,
+    abortSignal,
+    files,
+    mask,
+  }: Parameters<ImageModelV3['doGenerate']>[0]): Promise<
+    Awaited<ReturnType<ImageModelV3['doGenerate']>>
+  > {
+    const warnings: Array<SharedV3Warning> = [];
+
+    if (seed != null) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'seed',
+        details: 'This model does not support the `seed` option.',
+      });
+    }
+
+    if (size != null) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'size',
+        details:
+          'This model does not support the `size` option. Use `aspectRatio` instead.',
+      });
+    }
+
+    // Parse and validate provider options
+    const lumaOptions = await parseProviderOptions({
+      provider: 'luma',
+      providerOptions,
+      schema: lumaImageProviderOptionsSchema,
+    });
+
+    // Extract non-request options
+    const {
+      pollIntervalMillis,
+      maxPollAttempts,
+      referenceType,
+      images: imageConfigs,
+      ...providerRequestOptions
+    } = lumaOptions ?? {};
+
+    // Handle image editing via files with reference type support
+    const editingOptions = this.getEditingOptions(
+      files,
+      mask,
+      referenceType ?? undefined,
+      imageConfigs ?? [],
+    );
+
+    const currentDate = this.config._internal?.currentDate?.() ?? new Date();
+    const fullHeaders = combineHeaders(this.config.headers(), headers);
+    const { value: generationResponse, responseHeaders } = await postJsonToApi({
+      url: this.getLumaGenerationsUrl(),
+      headers: fullHeaders,
+      body: {
+        prompt,
+        ...(aspectRatio ? { aspect_ratio: aspectRatio } : {}),
+        model: this.modelId,
+        ...editingOptions,
+        ...providerRequestOptions,
+      },
+      abortSignal,
+      fetch: this.config.fetch,
+      failedResponseHandler: this.createLumaErrorHandler(),
+      successfulResponseHandler: createJsonResponseHandler(
+        lumaGenerationResponseSchema,
+      ),
+    });
+
+    const imageUrl = await this.pollForImageUrl(
+      generationResponse.id,
+      fullHeaders,
+      abortSignal,
+      {
+        pollIntervalMillis: pollIntervalMillis ?? undefined,
+        maxPollAttempts: maxPollAttempts ?? undefined,
+      },
+    );
+
+    const downloadedImage = await this.downloadImage(imageUrl, abortSignal);
+
+    return {
+      images: [downloadedImage],
+      warnings,
+      response: {
+        modelId: this.modelId,
+        timestamp: currentDate,
+        headers: responseHeaders,
+      },
+    };
+  }
+
+  private async pollForImageUrl(
+    generationId: string,
+    headers: Record<string, string | undefined>,
+    abortSignal: AbortSignal | undefined,
+    pollSettings?: { pollIntervalMillis?: number; maxPollAttempts?: number },
+  ): Promise<string> {
+    const url = this.getLumaGenerationsUrl(generationId);
+    const maxPollAttempts =
+      pollSettings?.maxPollAttempts ?? this.maxPollAttempts;
+    const pollIntervalMillis =
+      pollSettings?.pollIntervalMillis ?? this.pollIntervalMillis;
+
+    for (let i = 0; i < maxPollAttempts; i++) {
+      const { value: statusResponse } = await getFromApi({
+        url,
+        headers,
+        abortSignal,
+        fetch: this.config.fetch,
+        failedResponseHandler: this.createLumaErrorHandler(),
+        successfulResponseHandler: createJsonResponseHandler(
+          lumaGenerationResponseSchema,
+        ),
+      });
+
+      switch (statusResponse.state) {
+        case 'completed':
+          if (!statusResponse.assets?.image) {
+            throw new InvalidResponseDataError({
+              data: statusResponse,
+              message: `Image generation completed but no image was found.`,
+            });
+          }
+          return statusResponse.assets.image;
+        case 'failed':
+          throw new InvalidResponseDataError({
+            data: statusResponse,
+            message: `Image generation failed.`,
+          });
+      }
+      await delay(pollIntervalMillis);
+    }
+
+    throw new Error(
+      `Image generation timed out after ${this.maxPollAttempts} attempts.`,
+    );
+  }
+
+  private createLumaErrorHandler() {
+    return createJsonErrorResponseHandler({
+      errorSchema: lumaErrorSchema,
+      errorToMessage: (error: LumaErrorData) =>
+        error.detail[0].msg ?? 'Unknown error',
+    });
+  }
+
+  private getEditingOptions(
+    files: ImageModelV3File[] | undefined,
+    mask: ImageModelV3File | undefined,
+    referenceType: LumaReferenceType = 'image',
+    imageConfigs: Array<{ weight?: number | null; id?: string | null }> = [],
+  ): Record<string, unknown> {
+    const options: Record<string, unknown> = {};
+
+    // Luma does not support mask-based inpainting
+    if (mask != null) {
+      throw new Error(
+        'Luma AI does not support mask-based image editing. ' +
+          'Use the prompt to describe the changes you want to make, along with ' +
+          '`prompt.images` containing the source image URL.',
+      );
+    }
+
+    if (files == null || files.length === 0) {
+      return options;
+    }
+
+    // Validate all files are URL-based
+    for (const file of files) {
+      if (file.type !== 'url') {
+        throw new Error(
+          'Luma AI only supports URL-based images. ' +
+            '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;
+      }
+
+      case 'character': {
+        // Group images by identity id
+        const identities: Record<string, string[]> = {};
+        for (let i = 0; i < files.length; i++) {
+          const file = files[i] as { type: 'url'; url: string };
+          const identityId = imageConfigs[i]?.id ?? 'identity0';
+          if (!identities[identityId]) {
+            identities[identityId] = [];
+          }
+          identities[identityId].push(file.url);
+        }
+
+        // Validate each identity has at most 4 images
+        for (const [identityId, images] of Object.entries(identities)) {
+          if (images.length > 4) {
+            throw new Error(
+              `Luma AI character supports up to 4 images per identity. ` +
+                `Identity '${identityId}' has ${images.length} images.`,
+            );
+          }
+        }
+
+        options.character = Object.fromEntries(
+          Object.entries(identities).map(([id, images]) => [id, { images }]),
+        );
+        break;
+      }
+
+      case 'modify_image': {
+        // Only supports a single image
+        if (files.length > 1) {
+          throw new Error(
+            'Luma AI modify_image only supports a single input image. ' +
+              `You provided ${files.length} images.`,
+          );
+        }
+        options.modify_image = {
+          url: (files[0] as { type: 'url'; url: string }).url,
+          weight: imageConfigs[0]?.weight ?? defaultWeights.modify_image,
+        };
+        break;
+      }
+    }
+
+    return options;
+  }
+
+  private getLumaGenerationsUrl(generationId?: string) {
+    return `${this.config.baseURL}/dream-machine/v1/generations/${
+      generationId ?? 'image'
+    }`;
+  }
+
+  private async downloadImage(
+    url: string,
+    abortSignal: AbortSignal | undefined,
+  ): Promise<Uint8Array> {
+    const { value: response } = await getFromApi({
+      url,
+      // No specific headers should be needed for this request as it's a
+      // generated image provided by Luma.
+      abortSignal,
+      failedResponseHandler: createStatusCodeErrorResponseHandler(),
+      successfulResponseHandler: createBinaryResponseHandler(),
+      fetch: this.config.fetch,
+    });
+    return response;
+  }
+}
+
+// limited version of the schema, focussed on what is needed for the implementation
+// this approach limits breakages when the API changes and increases efficiency
+const lumaGenerationResponseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      id: z.string(),
+      state: z.enum(['queued', 'dreaming', 'completed', 'failed']),
+      failure_reason: z.string().nullish(),
+      assets: z
+        .object({
+          image: z.string(), // URL of the generated image
+        })
+        .nullish(),
+    }),
+  ),
+);
+
+const lumaErrorSchema = z.object({
+  detail: z.array(
+    z.object({
+      type: z.string(),
+      loc: z.array(z.string()),
+      msg: z.string(),
+      input: z.string(),
+      ctx: z
+        .object({
+          expected: z.string(),
+        })
+        .nullish(),
+    }),
+  ),
+});
+
+export type LumaErrorData = z.infer<typeof lumaErrorSchema>;
+
+/**
+ * Provider options schema for Luma image generation.
+ *
+ * @see https://docs.lumalabs.ai/docs/image-generation
+ */
+export const lumaImageProviderOptionsSchema = lazySchema(() =>
+  zodSchema(
+    z
+      .object({
+        /**
+         * The type of image reference to use when providing input images.
+         * - `image`: Guide generation using reference images (up to 4). Default.
+         * - `style`: Apply a specific style from reference image(s).
+         * - `character`: Create consistent characters from reference images (up to 4).
+         * - `modify_image`: Transform a single input image with prompt guidance.
+         */
+        referenceType: z
+          .enum(['image', 'style', 'character', 'modify_image'])
+          .nullish(),
+
+        /**
+         * Per-image configuration array. Each entry corresponds to an image in `prompt.images`.
+         * Allows setting individual weights for each reference image.
+         */
+        images: z
+          .array(
+            z.object({
+              /**
+               * The weight of this image's influence on the generation.
+               * - For `image`: Higher weight = closer to reference (default: 0.85)
+               * - For `style`: Higher weight = stronger style influence (default: 0.8)
+               * - For `modify_image`: Higher weight = closer to input, lower = more creative (default: 1.0)
+               */
+              weight: z.number().min(0).max(1).nullish(),
+
+              /**
+               * The identity name for character references.
+               * Used with `character` to specify which identity group the image belongs to.
+               * Luma supports multiple identities (e.g., 'identity0', 'identity1') for generating
+               * images with multiple consistent characters.
+               * Default: 'identity0'
+               */
+              id: z.string().nullish(),
+            }),
+          )
+          .nullish(),
+
+        /**
+         * Override the polling interval in milliseconds (default 500).
+         */
+        pollIntervalMillis: z.number().nullish(),
+
+        /**
+         * Override the maximum number of polling attempts (default 120).
+         */
+        maxPollAttempts: z.number().nullish(),
+      })
+      .passthrough(),
+  ),
+);
+
+export type LumaImageProviderOptions = InferSchema<
+  typeof lumaImageProviderOptionsSchema
+>;

package/src/luma-image-settings.ts

@@ -0,0 +1,96 @@
+// https://luma.ai/models?type=image
+export type LumaImageModelId = 'photon-1' | 'photon-flash-1' | (string & {});
+
+/**
+ * The type of image reference to use when providing input images.
+ *
+ * - `image`: Guide generation using reference images (up to 4). Default.
+ * - `style`: Apply a specific style from reference image(s).
+ * - `character`: Create consistent characters from reference images (up to 4).
+ * - `modify_image`: Transform a single input image with prompt guidance.
+ */
+export type LumaReferenceType =
+  | 'image'
+  | 'style'
+  | 'character'
+  | 'modify_image';
+
+/**
+ * Per-image configuration for Luma image references.
+ */
+export interface LumaImageConfig {
+  /**
+   * The weight of this image's influence on the generation.
+   *
+   * - For `image`: Higher weight = closer to reference (default: 0.85)
+   * - For `style`: Higher weight = stronger style influence (default: 0.8)
+   * - For `modify_image`: Higher weight = closer to input, lower = more creative (default: 1.0)
+   *
+   * Note: Not applicable to `character`.
+   */
+  weight?: number;
+
+  /**
+   * The identity name for character references.
+   *
+   * Used with `character` to specify which identity group the image belongs to.
+   * Luma supports multiple identities (e.g., 'identity0', 'identity1') for generating
+   * images with multiple consistent characters.
+   *
+   * Default: 'identity0'
+   */
+  id?: string;
+}
+
+/**
+ * Configuration settings for Luma image generation.
+ *
+ * Since the Luma API processes images through an asynchronous queue system, these
+ * settings allow you to tune the polling behavior when waiting for image
+ * generation to complete.
+ */
+export interface LumaImageSettings {
+  /**
+   * Override the polling interval in milliseconds (default 500). This controls how
+   * frequently the API is checked for completed images while they are being
+   * processed in Luma's queue.
+   */
+  pollIntervalMillis?: number;
+
+  /**
+   * Override the maximum number of polling attempts (default 120). Since image
+   * generation is queued and processed asynchronously, this limits how long to wait
+   * for results before timing out.
+   */
+  maxPollAttempts?: number;
+
+  /**
+   * The type of image reference to use when providing input images via `prompt.images`.
+   * Default is `image`.
+   *
+   * - `image`: Guide generation using reference images (up to 4)
+   * - `style`: Apply a specific style from reference image(s)
+   * - `character`: Create consistent characters from reference images (up to 4)
+   * - `modify_image`: Transform a single input image with prompt guidance
+   */
+  referenceType?: LumaReferenceType;
+
+  /**
+   * Per-image configuration array. Each entry corresponds to an image in `prompt.images`.
+   * Allows setting individual weights for each reference image.
+   *
+   * @example
+   * ```ts
+   * providerOptions: {
+   *   luma: {
+   *     referenceType: 'image',
+   *     images: [
+   *       { weight: 0.9 },
+   *       { weight: 0.5 },
+   *     ],
+   *   },
+   * }
+   * ```
+   */
+  images?: LumaImageConfig[];
+}

package/src/luma-provider.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { createLuma } from './luma-provider';
+import { LumaImageModel } from './luma-image-model';
+
+vi.mock('./luma-image-model', () => ({
+  LumaImageModel: vi.fn(),
+}));
+
+describe('createLuma', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('image', () => {
+    it('should construct an image model with default configuration', () => {
+      const provider = createLuma();
+      const modelId = 'luma-v1';
+
+      const model = provider.image(modelId);
+
+      expect(model).toBeInstanceOf(LumaImageModel);
+      expect(LumaImageModel).toHaveBeenCalledWith(
+        modelId,
+        expect.objectContaining({
+          provider: 'luma.image',
+          baseURL: 'https://api.lumalabs.ai',
+        }),
+      );
+    });
+
+    it('should respect custom configuration options', () => {
+      const customBaseURL = 'https://custom-api.lumalabs.ai';
+      const customHeaders = { 'X-Custom-Header': 'value' };
+      const mockFetch = vi.fn();
+
+      const provider = createLuma({
+        apiKey: 'custom-api-key',
+        baseURL: customBaseURL,
+        headers: customHeaders,
+        fetch: mockFetch,
+      });
+      const modelId = 'luma-v1';
+
+      provider.image(modelId);
+
+      expect(LumaImageModel).toHaveBeenCalledWith(
+        modelId,
+        expect.objectContaining({
+          baseURL: customBaseURL,
+          headers: expect.any(Function),
+          fetch: mockFetch,
+          provider: 'luma.image',
+        }),
+      );
+    });
+  });
+});

package/src/luma-provider.ts

@@ -0,0 +1,97 @@
+import { ImageModelV3, NoSuchModelError, ProviderV3 } from '@ai-sdk/provider';
+import {
+  FetchFunction,
+  loadApiKey,
+  withoutTrailingSlash,
+  withUserAgentSuffix,
+} from '@ai-sdk/provider-utils';
+import { LumaImageModel } from './luma-image-model';
+import { LumaImageModelId } from './luma-image-settings';
+import { VERSION } from './version';
+
+export interface LumaProviderSettings {
+  /**
+Luma API key. Default value is taken from the `LUMA_API_KEY` environment
+variable.
+  */
+  apiKey?: string;
+  /**
+Base URL for the API calls.
+  */
+  baseURL?: string;
+  /**
+Custom headers to include in the requests.
+  */
+  headers?: Record<string, string>;
+  /**
+Custom fetch implementation. You can use it as a middleware to intercept requests,
+or to provide a custom fetch implementation for e.g. testing.
+  */
+  fetch?: FetchFunction;
+}
+
+export interface LumaProvider extends ProviderV3 {
+  /**
+Creates a model for image generation.
+  */
+  image(modelId: LumaImageModelId): ImageModelV3;
+
+  /**
+Creates a model for image generation.
+   */
+  imageModel(modelId: LumaImageModelId): ImageModelV3;
+
+  /**
+   * @deprecated Use `embeddingModel` instead.
+   */
+  textEmbeddingModel(modelId: string): never;
+}
+
+const defaultBaseURL = 'https://api.lumalabs.ai';
+
+export function createLuma(options: LumaProviderSettings = {}): LumaProvider {
+  const baseURL = withoutTrailingSlash(options.baseURL ?? defaultBaseURL);
+  const getHeaders = () =>
+    withUserAgentSuffix(
+      {
+        Authorization: `Bearer ${loadApiKey({
+          apiKey: options.apiKey,
+          environmentVariableName: 'LUMA_API_KEY',
+          description: 'Luma',
+        })}`,
+        ...options.headers,
+      },
+      `ai-sdk/luma/${VERSION}`,
+    );
+
+  const createImageModel = (modelId: LumaImageModelId) =>
+    new LumaImageModel(modelId, {
+      provider: 'luma.image',
+      baseURL: baseURL ?? defaultBaseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+    });
+
+  const embeddingModel = (modelId: string) => {
+    throw new NoSuchModelError({
+      modelId,
+      modelType: 'embeddingModel',
+    });
+  };
+
+  return {
+    specificationVersion: 'v3' as const,
+    image: createImageModel,
+    imageModel: createImageModel,
+    languageModel: (modelId: string) => {
+      throw new NoSuchModelError({
+        modelId,
+        modelType: 'languageModel',
+      });
+    },
+    embeddingModel,
+    textEmbeddingModel: embeddingModel,
+  };
+}
+
+export const luma = createLuma();

package/src/version.ts

@@ -0,0 +1,6 @@
+// Version string of this package injected at build time.
+declare const __PACKAGE_VERSION__: string | undefined;
+export const VERSION: string =
+  typeof __PACKAGE_VERSION__ !== 'undefined'
+    ? __PACKAGE_VERSION__
+    : '0.0.0-test';