@ai-sdk/minimax 3.0.0 → 3.0.2

package/src/minimax-video-model.ts

@@ -0,0 +1,657 @@
+import {
+  AISDKError,
+  type Experimental_VideoModelV4,
+  type Experimental_VideoModelV4File,
+  type SharedV4Warning,
+} from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  convertImageModelFileToDataUri,
+  createJsonErrorResponseHandler,
+  createJsonResponseHandler,
+  delay,
+  getFromApi,
+  getTopLevelMediaType,
+  parseProviderOptions,
+  postJsonToApi,
+  resolve,
+  type FetchFunction,
+  type Resolvable,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import {
+  minimaxVideoModelOptionsSchema,
+  minimaxVideoRatios,
+  minimaxVideoResolutions,
+  type MiniMaxVideoModelOptions,
+} from './minimax-video-model-options';
+import type { MiniMaxVideoModelId } from './minimax-video-settings';
+
+interface MiniMaxVideoModelConfig {
+  provider: string;
+  // API root without a version suffix, e.g. `https://api.minimax.io`.
+  baseURL: string;
+  headers: Resolvable<Record<string, string | undefined>>;
+  fetch?: FetchFunction;
+  _internal?: {
+    currentDate?: () => Date;
+  };
+}
+
+type MiniMaxVideoDoGenerateOptions = Parameters<
+  Experimental_VideoModelV4['doGenerate']
+>[0];
+
+const DEFAULT_RESOLUTION = '2K';
+const DEFAULT_POLL_INTERVAL_MS = 10_000;
+const DEFAULT_POLL_TIMEOUT_MS = 600_000;
+const MIN_DURATION_SECONDS = 5;
+const MAX_DURATION_SECONDS = 15;
+const MAX_REFERENCE_IMAGES = 9;
+const MAX_REFERENCE_VIDEOS = 3;
+const MAX_REFERENCE_AUDIOS = 3;
+
+const allowedRatios = new Set<string>(minimaxVideoRatios);
+const allowedResolutions = new Set<string>(minimaxVideoResolutions);
+
+// The top-level `resolution` is `{width}x{height}`, but the API takes a named
+// tier, so map the canonical 2K frame sizes onto the single tier H3 supports.
+// Anything else can't be honored and warns.
+// One canonical frame size per ratio H3 supports, so a caller who pairs a
+// resolution with any supported ratio resolves to the tier instead of being
+// told 2K is unsupported.
+const RESOLUTION_MAP: Record<string, string> = {
+  // Square
+  '2048x2048': '2K',
+  // Landscape
+  '2560x1080': '2K',
+  '2560x1440': '2K',
+  '2048x1536': '2K',
+  // Portrait
+  '1440x2560': '2K',
+  '1536x2048': '2K',
+};
+
+// A caller may pass the named tier itself rather than a frame size — `2K` is
+// what the MiniMax API takes, so it is the natural thing to send. Accept it
+// case-insensitively instead of reporting it as unrecognized.
+function resolveTopLevelResolution(resolution: string): string | undefined {
+  const named = resolution.toUpperCase();
+  return allowedResolutions.has(named) ? named : RESOLUTION_MAP[resolution];
+}
+
+// Frame images must be images. Returns the offending top-level media type when
+// a frame is something else, so it can be rejected the way a reference input of
+// the wrong kind is. A frame with no media type is left alone: the core emits
+// URL inputs without one, and unlike a reference there is no routing decision
+// riding on it.
+function nonImageFrameMediaType(
+  file: Experimental_VideoModelV4File,
+): string | undefined {
+  if (file.mediaType == null) {
+    return undefined;
+  }
+
+  const topLevelMediaType = getTopLevelMediaType(file.mediaType);
+  return topLevelMediaType === 'image' ? undefined : topLevelMediaType;
+}
+
+export class MiniMaxVideoModel implements Experimental_VideoModelV4 {
+  readonly specificationVersion = 'v4';
+  readonly maxVideosPerCall = 1;
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  constructor(
+    readonly modelId: MiniMaxVideoModelId,
+    private config: MiniMaxVideoModelConfig,
+  ) {}
+
+  async doGenerate(
+    options: MiniMaxVideoDoGenerateOptions,
+  ): Promise<Awaited<ReturnType<Experimental_VideoModelV4['doGenerate']>>> {
+    const currentDate = this.config._internal?.currentDate?.() ?? new Date();
+    const warnings: SharedV4Warning[] = [];
+
+    const minimaxOptions = (await parseProviderOptions({
+      provider: 'minimax',
+      providerOptions: options.providerOptions,
+      schema: minimaxVideoModelOptionsSchema,
+    })) as MiniMaxVideoModelOptions | undefined;
+
+    if (options.fps != null) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'fps',
+        details: 'MiniMax-H3 does not support a custom frame rate.',
+      });
+    }
+
+    if (options.seed != null) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'seed',
+        details: 'MiniMax-H3 does not support a seed.',
+      });
+    }
+
+    if (options.n != null && options.n > 1) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'n',
+        details:
+          'MiniMax-H3 generates a single video per call. Only 1 video will be generated.',
+      });
+    }
+
+    if (options.generateAudio != null) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'generateAudio',
+        details:
+          'The MiniMax-H3 API does not expose an audio parameter. The generateAudio option was ignored.',
+      });
+    }
+
+    // Resolution: the API takes a named tier, so an explicit provider option
+    // wins and a top-level value is resolved to a tier.
+    let resolution: string | undefined = minimaxOptions?.resolution;
+    if (options.resolution != null) {
+      const mapped = resolveTopLevelResolution(options.resolution);
+      if (resolution != null) {
+        // The provider option is already a tier, so the only way the two can
+        // disagree is a top-level value that maps to no tier at all.
+        if (mapped == null) {
+          warnings.push({
+            type: 'unsupported',
+            feature: 'resolution',
+            details:
+              `Unrecognized resolution "${options.resolution}". MiniMax-H3 only supports "2K", ` +
+              `so providerOptions.minimax.resolution ("${resolution}") was used instead.`,
+          });
+        }
+      } else if (mapped != null) {
+        resolution = mapped;
+      } else {
+        warnings.push({
+          type: 'unsupported',
+          feature: 'resolution',
+          details:
+            `Unrecognized resolution "${options.resolution}". MiniMax-H3 only ` +
+            'supports "2K".',
+        });
+      }
+    }
+    resolution ??= DEFAULT_RESOLUTION;
+
+    // `convertImageModelFileToDataUri` passes `url` files through unchanged and
+    // encodes inline data as a data URI. MiniMax `mm_file://…` handles survive
+    // that pass-through, but not the core `generateVideo` path: it base64-decodes
+    // any string that is not `http(s)://` or `data:`, so `mm_file://` only
+    // reaches the API through `providerOptions.minimax.referenceAudioUrls`,
+    // which is forwarded raw — not through `image`, `frameImages`, or
+    // `inputReferences`.
+    const content: Array<Record<string, unknown>> = [
+      { type: 'text', text: options.prompt ?? '' },
+    ];
+
+    // The inputs that actually make it into `content` below, after the caps and
+    // rejections H3 imposes. Reported as `providerMetadata.minimax
+    // .resolvedInputs`: the warnings say an input was dropped, but not how many
+    // survived, which callers that meter usage need. Accumulated at the push
+    // sites rather than re-derived, so the two cannot disagree.
+    let sentImageCount = 0;
+    const sentReferenceVideoUrls: string[] = [];
+
+    // Resolve first/last frame inputs. A standalone `image` is treated as the
+    // first frame (image-to-video). The core sets `image` to the `first_frame`
+    // frame image when there is one, so the frame-image entry is tracked
+    // separately to report which input a warning came from.
+    const firstFrameImage = options.frameImages?.find(
+      frame => frame.frameType === 'first_frame',
+    )?.image;
+    let firstFrame = firstFrameImage ?? options.image;
+    let lastFrame = options.frameImages?.find(
+      frame => frame.frameType === 'last_frame',
+    )?.image;
+
+    // Reject unusable frames before deciding the generation mode.
+    const firstFrameMediaType =
+      firstFrame != null ? nonImageFrameMediaType(firstFrame) : undefined;
+    if (firstFrame != null && firstFrameMediaType != null) {
+      warnings.push({
+        type: 'unsupported',
+        feature: firstFrameImage != null ? 'frameImages' : 'image',
+        details:
+          firstFrameMediaType === 'video'
+            ? 'MiniMax-H3 does not accept a video as a frame image. The video was ignored.'
+            : `MiniMax-H3 only accepts an image as a frame image; the "${firstFrame.mediaType}" file was ignored.`,
+      });
+      firstFrame = undefined;
+    }
+
+    if (lastFrame != null) {
+      if (firstFrame == null) {
+        warnings.push({
+          type: 'unsupported',
+          feature: 'frameImages',
+          details:
+            'MiniMax-H3 requires a first_frame when a last_frame is provided. The last_frame was ignored.',
+        });
+        lastFrame = undefined;
+      } else {
+        const lastFrameMediaType = nonImageFrameMediaType(lastFrame);
+        if (lastFrameMediaType != null) {
+          warnings.push({
+            type: 'unsupported',
+            feature: 'frameImages',
+            details:
+              lastFrameMediaType === 'video'
+                ? 'MiniMax-H3 does not accept a video as a frame image. The last_frame video was ignored.'
+                : `MiniMax-H3 only accepts an image as a frame image; the "${lastFrame.mediaType}" last_frame was ignored.`,
+          });
+          lastFrame = undefined;
+        }
+      }
+    }
+
+    const usesFrameImages = firstFrame != null || lastFrame != null;
+
+    const referenceFiles = options.inputReferences ?? [];
+    const referenceAudioUrls = minimaxOptions?.referenceAudioUrls ?? [];
+    const usesReferences =
+      referenceFiles.length > 0 || referenceAudioUrls.length > 0;
+
+    if (usesFrameImages) {
+      if (firstFrame != null) {
+        content.push({
+          type: 'image_url',
+          image_url: { url: convertImageModelFileToDataUri(firstFrame) },
+          role: 'first_frame',
+        });
+        sentImageCount++;
+      }
+
+      if (lastFrame != null) {
+        content.push({
+          type: 'image_url',
+          image_url: { url: convertImageModelFileToDataUri(lastFrame) },
+          role: 'last_frame',
+        });
+        sentImageCount++;
+      }
+
+      // Frame images and reference inputs are mutually exclusive.
+      if (usesReferences) {
+        warnings.push({
+          type: 'unsupported',
+          feature: 'inputReferences',
+          details:
+            'MiniMax-H3 cannot combine frame images with reference inputs. The references were ignored.',
+        });
+      }
+    } else if (usesReferences) {
+      const referenceImages: Experimental_VideoModelV4File[] = [];
+      const referenceVideos: Experimental_VideoModelV4File[] = [];
+
+      for (const file of referenceFiles) {
+        const topLevelMediaType =
+          file.mediaType != null
+            ? getTopLevelMediaType(file.mediaType)
+            : undefined;
+
+        if (topLevelMediaType === 'video') {
+          referenceVideos.push(file);
+        } else if (topLevelMediaType === 'image') {
+          referenceImages.push(file);
+        } else if (topLevelMediaType == null) {
+          // Only URL references can omit a media type.
+          // Fall back to an image and warn
+          warnings.push({
+            type: 'unsupported',
+            feature: 'inputReferences',
+            details:
+              'MiniMax-H3 requires an explicit mediaType to route URL references as ' +
+              'video or image. Pass { data: url, mediaType: "video/mp4" } for video ' +
+              'references. The reference was treated as an image.',
+          });
+          referenceImages.push(file);
+        } else {
+          warnings.push({
+            type: 'unsupported',
+            feature: 'inputReferences',
+            details:
+              `MiniMax-H3 only accepts image and video references; the "${file.mediaType}" ` +
+              'reference was ignored. Pass reference audio via ' +
+              'providerOptions.minimax.referenceAudioUrls.',
+          });
+        }
+      }
+
+      for (const image of referenceImages.slice(0, MAX_REFERENCE_IMAGES)) {
+        content.push({
+          type: 'image_url',
+          image_url: { url: convertImageModelFileToDataUri(image) },
+          role: 'reference_image',
+        });
+        sentImageCount++;
+      }
+      if (referenceImages.length > MAX_REFERENCE_IMAGES) {
+        warnings.push({
+          type: 'unsupported',
+          feature: 'inputReferences',
+          details: `MiniMax-H3 accepts at most ${MAX_REFERENCE_IMAGES} reference images. Extra images were ignored.`,
+        });
+      }
+
+      for (const video of referenceVideos.slice(0, MAX_REFERENCE_VIDEOS)) {
+        const url = convertImageModelFileToDataUri(video);
+        content.push({
+          type: 'video_url',
+          video_url: { url },
+          role: 'reference_video',
+        });
+        // Inline files become data URIs, which are not worth echoing back.
+        if (video.type === 'url') {
+          sentReferenceVideoUrls.push(url);
+        }
+      }
+      if (referenceVideos.length > MAX_REFERENCE_VIDEOS) {
+        warnings.push({
+          type: 'unsupported',
+          feature: 'inputReferences',
+          details: `MiniMax-H3 accepts at most ${MAX_REFERENCE_VIDEOS} reference videos. Extra videos were ignored.`,
+        });
+      }
+
+      // Reference audio must accompany at least one reference image or video.
+      if (referenceAudioUrls.length > 0) {
+        if (referenceImages.length === 0 && referenceVideos.length === 0) {
+          warnings.push({
+            type: 'unsupported',
+            feature: 'referenceAudioUrls',
+            details:
+              'MiniMax-H3 reference audio must be paired with at least one reference image or video. The audio was ignored.',
+          });
+        } else {
+          for (const url of referenceAudioUrls.slice(0, MAX_REFERENCE_AUDIOS)) {
+            content.push({
+              type: 'audio_url',
+              audio_url: { url },
+              role: 'reference_audio',
+            });
+          }
+          if (referenceAudioUrls.length > MAX_REFERENCE_AUDIOS) {
+            warnings.push({
+              type: 'unsupported',
+              feature: 'referenceAudioUrls',
+              details: `MiniMax-H3 accepts at most ${MAX_REFERENCE_AUDIOS} reference audios. Extra audios were ignored.`,
+            });
+          }
+        }
+      }
+    }
+
+    // Aspect ratio. In frame-image mode the ratio follows the supplied image,
+    // so an explicit ratio is ignored.
+    let ratio = minimaxOptions?.ratio as string | undefined;
+    if (ratio == null && options.aspectRatio != null) {
+      if (allowedRatios.has(options.aspectRatio)) {
+        ratio = options.aspectRatio;
+      } else {
+        warnings.push({
+          type: 'unsupported',
+          feature: 'aspectRatio',
+          details:
+            `MiniMax-H3 does not support the aspect ratio "${options.aspectRatio}". ` +
+            'Using the provider default (adaptive).',
+        });
+      }
+    }
+    if (usesFrameImages && ratio != null) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'aspectRatio',
+        details:
+          'MiniMax-H3 derives the aspect ratio from the frame image; the requested ratio was ignored.',
+      });
+      ratio = undefined;
+    }
+
+    // H3 takes an integer between 5 and 15, so round before clamping: a
+    // fractional duration is rejected by the API just as an out-of-range one is.
+    let duration = options.duration ?? MIN_DURATION_SECONDS;
+    if (options.duration != null) {
+      if (!Number.isInteger(duration)) {
+        duration = Math.round(duration);
+        warnings.push({
+          type: 'unsupported',
+          feature: 'duration',
+          details: `MiniMax-H3 requires a whole number of seconds. The requested duration of ${options.duration} was rounded to ${duration}.`,
+        });
+      }
+
+      if (duration > MAX_DURATION_SECONDS) {
+        warnings.push({
+          type: 'unsupported',
+          feature: 'duration',
+          details: `MiniMax-H3 supports at most ${MAX_DURATION_SECONDS} seconds. The requested duration of ${options.duration} was clamped to ${MAX_DURATION_SECONDS}.`,
+        });
+        duration = MAX_DURATION_SECONDS;
+      } else if (duration < MIN_DURATION_SECONDS) {
+        warnings.push({
+          type: 'unsupported',
+          feature: 'duration',
+          details: `MiniMax-H3 requires at least ${MIN_DURATION_SECONDS} seconds. The requested duration of ${options.duration} was clamped to ${MIN_DURATION_SECONDS}.`,
+        });
+        duration = MIN_DURATION_SECONDS;
+      }
+    }
+
+    const body: Record<string, unknown> = {
+      model: this.modelId,
+      content,
+      resolution,
+      duration,
+    };
+    if (ratio != null) {
+      body.ratio = ratio;
+    }
+    if (minimaxOptions?.aigcWatermark != null) {
+      body.aigc_watermark = minimaxOptions.aigcWatermark;
+    }
+
+    const baseURL = this.config.baseURL;
+
+    const { value: createResponse } = await postJsonToApi({
+      url: `${baseURL}/v2/video_generation`,
+      headers: combineHeaders(
+        await resolve(this.config.headers),
+        options.headers,
+      ),
+      body,
+      failedResponseHandler: minimaxVideoFailedResponseHandler,
+      successfulResponseHandler: createJsonResponseHandler(
+        minimaxCreateVideoResponseSchema,
+      ),
+      abortSignal: options.abortSignal,
+      fetch: this.config.fetch,
+    });
+
+    const taskId = createResponse.task_id;
+    if (!taskId) {
+      throw new AISDKError({
+        name: 'MINIMAX_VIDEO_GENERATION_ERROR',
+        message: `No task_id returned from the MiniMax API. Response: ${JSON.stringify(createResponse)}`,
+      });
+    }
+
+    const pollIntervalMs =
+      minimaxOptions?.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const pollTimeoutMs =
+      minimaxOptions?.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
+    const startTime = Date.now();
+    let responseHeaders: Record<string, string> | undefined;
+
+    while (true) {
+      await delay(pollIntervalMs, { abortSignal: options.abortSignal });
+
+      if (Date.now() - startTime > pollTimeoutMs) {
+        throw new AISDKError({
+          name: 'MINIMAX_VIDEO_GENERATION_TIMEOUT',
+          message: `MiniMax video generation timed out after ${pollTimeoutMs}ms. Task ID: ${taskId}`,
+        });
+      }
+
+      const { value: statusResponse, responseHeaders: pollHeaders } =
+        await getFromApi({
+          url: `${baseURL}/v2/query/video_generation/${taskId}`,
+          validateUrl: false,
+          headers: combineHeaders(
+            await resolve(this.config.headers),
+            options.headers,
+          ),
+          successfulResponseHandler: createJsonResponseHandler(
+            minimaxVideoStatusResponseSchema,
+          ),
+          failedResponseHandler: minimaxVideoFailedResponseHandler,
+          abortSignal: options.abortSignal,
+          fetch: this.config.fetch,
+        });
+
+      responseHeaders = pollHeaders;
+      const task = statusResponse.task;
+
+      switch (task.status) {
+        case 'succeeded': {
+          const url = task.content?.url;
+          if (!url) {
+            throw new AISDKError({
+              name: 'MINIMAX_VIDEO_GENERATION_ERROR',
+              message: `MiniMax video generation completed but no video URL was returned. Task ID: ${taskId}`,
+            });
+          }
+
+          return {
+            videos: [
+              {
+                type: 'url' as const,
+                url,
+                mediaType: 'video/mp4',
+              },
+            ],
+            warnings,
+            response: {
+              timestamp: currentDate,
+              modelId: this.modelId,
+              headers: responseHeaders,
+            },
+            providerMetadata: {
+              minimax: {
+                taskId,
+                videoUrl: url,
+                resolvedInputs: {
+                  imageCount: sentImageCount,
+                  referenceVideoUrls: sentReferenceVideoUrls,
+                },
+                ...(task.duration != null ? { duration: task.duration } : {}),
+                ...(task.ratio != null ? { ratio: task.ratio } : {}),
+                ...(task.resolution != null
+                  ? { resolution: task.resolution }
+                  : {}),
+                ...(task.usage != null
+                  ? {
+                      usage: {
+                        totalSeconds: task.usage.total_seconds,
+                        inputSeconds: task.usage.input_seconds,
+                        outputSeconds: task.usage.output_seconds,
+                      },
+                    }
+                  : {}),
+              },
+            },
+          };
+        }
+
+        case 'failed': {
+          throw new AISDKError({
+            name: 'MINIMAX_VIDEO_GENERATION_FAILED',
+            message: `MiniMax video generation failed${
+              task.error?.message ? `: ${task.error.message}` : ''
+            }${task.error?.code != null ? ` (${task.error.code})` : ''}. Task ID: ${taskId}`,
+          });
+        }
+
+        case 'cancelled': {
+          throw new AISDKError({
+            name: 'MINIMAX_VIDEO_GENERATION_CANCELLED',
+            message: `MiniMax video generation was cancelled. Task ID: ${taskId}`,
+          });
+        }
+
+        case 'expired': {
+          throw new AISDKError({
+            name: 'MINIMAX_VIDEO_GENERATION_EXPIRED',
+            message: `MiniMax video generation request expired. Task ID: ${taskId}`,
+          });
+        }
+
+        // 'queued' | 'running' | unknown → keep polling.
+        default:
+          break;
+      }
+    }
+  }
+}
+
+const minimaxCreateVideoResponseSchema = z.object({
+  task_id: z.string().nullish(),
+});
+
+const minimaxVideoStatusResponseSchema = z.object({
+  task: z.object({
+    id: z.string().nullish(),
+    status: z.string().nullish(),
+    content: z
+      .object({
+        url: z.string().nullish(),
+      })
+      .nullish(),
+    resolution: z.string().nullish(),
+    duration: z.number().nullish(),
+    ratio: z.string().nullish(),
+    usage: z
+      .object({
+        total_seconds: z.number().nullish(),
+        input_seconds: z.number().nullish(),
+        output_seconds: z.number().nullish(),
+      })
+      .nullish(),
+    error: z
+      .object({
+        code: z.union([z.string(), z.number()]).nullish(),
+        message: z.string().nullish(),
+      })
+      .nullish(),
+  }),
+});
+
+const minimaxVideoErrorSchema = z.object({
+  type: z.string().nullish(),
+  error: z
+    .object({
+      type: z.string().nullish(),
+      message: z.string().nullish(),
+      http_code: z.union([z.string(), z.number()]).nullish(),
+    })
+    .nullish(),
+  request_id: z.string().nullish(),
+});
+
+const minimaxVideoFailedResponseHandler = createJsonErrorResponseHandler({
+  errorSchema: minimaxVideoErrorSchema,
+  errorToMessage: data =>
+    data.error?.message ?? 'MiniMax video generation error',
+});

package/src/minimax-video-settings.ts

@@ -0,0 +1,2 @@
+// https://platform.minimax.io/docs
+export type MiniMaxVideoModelId = 'MiniMax-H3' | (string & {});