@j-o-r/hello-dave 0.1.0 → 0.1.4

package/lib/API/minimax/video.js

@@ -2,23 +2,39 @@
  * @file lib/API/minimax/video.js
  * @module minimax/video
  * @description Pure HTTP wrapper for the Minimax Video Generation API.
- *              Fully aligned with the official documentation:
- *              - lib/API/minimax/video.generation.md
- *              - lib/API/minimax/video.query.md
- *              - lib/API/minimax/video.download.md
- *              - lib/API/minimax/video.from.image.md
- *              - lib/API/minimax/video.first.last.image.md
- *              - lib/API/minimax/video.from.subject.md
+ *              Fully aligned with the official documentation in:
+ *              - video.generation.md (Text-to-Video)
+ *              - video.from.image.md (Image-to-Video)
+ *              - video.first.last.image.md (First & Last Frame)
+ *              - video.from.subject.md (Subject Reference)
+ *              - video.query.md + video.download.md
  *
- *              This is a **new library** — only the current response format is supported.
- *              No backward compatibility with legacy response structures.
+ *              ============================================================
+ *              CLEAR MODEL ↔ TASK / MODE MAPPING (from official docs)
+ *              ============================================================
+ *
+ *              | Mode / Task                  | Supported Models                                      | Required Fields                  | Notes |
+ *              |------------------------------|-------------------------------------------------------|----------------------------------|-------|
+ *              | Text-to-Video                | MiniMax-Hailuo-2.3, MiniMax-Hailuo-02, T2V-01-Director, T2V-01 | prompt                           | Default mode |
+ *              | Image-to-Video               | MiniMax-Hailuo-2.3, MiniMax-Hailuo-2.3-Fast, MiniMax-Hailuo-02, I2V-01-Director, I2V-01-live, I2V-01 | first_frame_image                | - |
+ *              | First & Last Frame Video     | **MiniMax-Hailuo-02 ONLY**                            | last_frame_image (first optional) | Does NOT support 512P. Error if you use Hailuo-2.3 here. |
+ *              | Subject-Reference Video      | **S2V-01 ONLY**                                       | subject_reference (array)        | Character/face reference |
+ *
+ *              Default model in this wrapper: 'MiniMax-Hailuo-2.3'
+ *              → This is why you got the error with First-and-Last-Frame + Hailuo-2.3.
+ *
+ *              ============================================================
+ *              IMAGE REFERENCE RULES (STRICT)
+ *              ============================================================
+ *              - All image references (`first_frame_image`, `last_frame_image`, `subject_reference[].image`)
+ *                **MUST be public HTTP/HTTPS URLs**.
+ *              - **Base64 / data: URLs are NOT supported** and will be rejected with a clear error.
+ *              - The wrapper validates this before calling the API.
+ *              - For subject_reference (S2V-01): each item must have `image: [exactly one URL]` (length === 1).
  *
  *              This module only handles communication with Minimax endpoints.
  *              It does NOT handle file publishing, SSH, or CDN logic.
  *
- *              For publishing generated or reference files to a remote CDN,
- *              use the reusable `lib/cdn.js` module instead.
- *
  *              Video generation is asynchronous:
  *              1. Create task → returns task_id
  *              2. Poll query until status === 'Success' (or Fail)
@@ -35,6 +51,128 @@ const BASE_URL = 'https://api.minimax.io/v1';
 // All temporary files (audio, images, video) are saved under this directory
 const TMP_DIR = path.join(process.cwd(), '.cache', 'minimax');
 
+/** Supported modes for clear documentation and validation */
+const SUPPORTED_MODES = ['text', 'image', 'first-last', 'subject'];
+
+/**
+ * Checks if a string is a valid public HTTP/HTTPS URL.
+ * Rejects data: URLs, Base64, and non-HTTP schemes.
+ * @param {string} str
+ * @returns {boolean}
+ */
+function isValidPublicUrl(str) {
+  if (typeof str !== 'string' || !str.trim()) return false;
+  const trimmed = str.trim();
+  if (trimmed.startsWith('data:')) return false;           // explicitly rule out Base64
+  if (trimmed.startsWith('http://') || trimmed.startsWith('https://')) return true;
+  return false;
+}
+
+/**
+ * Validates that an image reference is a public URL (rejects Base64).
+ * Throws a clear error if invalid.
+ * @param {string} fieldName - e.g. 'first_frame_image'
+ * @param {string} value
+ */
+function validateImageUrl(fieldName, value) {
+  if (!value) return;
+  if (!isValidPublicUrl(value)) {
+    throw new Error(
+      `${fieldName} must be a public HTTP/HTTPS URL. ` +
+      `Base64 / data: URLs are not supported. ` +
+      `Got: ${typeof value === 'string' ? value.substring(0, 80) + '...' : value}`
+    );
+  }
+}
+
+/**
+ * Validates subject_reference array for S2V-01.
+ * - Each reference must have `image` as an array of **exactly length 1**.
+ * - The single image must be a public HTTP/HTTPS URL (no Base64).
+ * Throws a clear, actionable error on any violation.
+ * @param {Array} subjectRef
+ */
+function validateSubjectReference(subjectRef) {
+  if (!subjectRef || !Array.isArray(subjectRef)) return;
+
+  subjectRef.forEach((ref, idx) => {
+    if (!ref) {
+      throw new Error(`subject_reference[${idx}] is invalid (must be an object).`);
+    }
+
+    if (!Array.isArray(ref.image)) {
+      throw new Error(
+        `subject_reference[${idx}].image must be an array containing exactly one public URL ` +
+        `(S2V-01 requirement). Got: ${typeof ref.image}`
+      );
+    }
+
+    if (ref.image.length !== 1) {
+      throw new Error(
+        `subject_reference[${idx}].image must contain **exactly one** URL (length === 1). ` +
+        `S2V-01 does not support multiple images per reference. ` +
+        `Got length: ${ref.image.length}`
+      );
+    }
+
+    const img = ref.image[0];
+    if (!isValidPublicUrl(img)) {
+      throw new Error(
+        `subject_reference[${idx}].image[0] must be a public HTTP/HTTPS URL. ` +
+        `Base64 / data: URLs are not supported. ` +
+        `Got: ${typeof img === 'string' ? img.substring(0, 80) + '...' : img}`
+      );
+    }
+  });
+}
+
+/**
+ * Returns the list of officially supported models for a given mode.
+ * @param {string} mode - 'text' | 'image' | 'first-last' | 'subject'
+ * @returns {string[]}
+ */
+function getSupportedModelsForMode(mode) {
+  switch (mode) {
+    case 'first-last':
+      return ['MiniMax-Hailuo-02'];
+    case 'subject':
+      return ['S2V-01'];
+    case 'image':
+      return ['MiniMax-Hailuo-2.3', 'MiniMax-Hailuo-2.3-Fast', 'MiniMax-Hailuo-02', 'I2V-01-Director', 'I2V-01-live', 'I2V-01'];
+    case 'text':
+    default:
+      return ['MiniMax-Hailuo-2.3', 'MiniMax-Hailuo-02', 'T2V-01-Director', 'T2V-01'];
+  }
+}
+
+/**
+ * Auto-detects the most likely mode based on provided options.
+ * @param {Object} options
+ * @returns {string} one of SUPPORTED_MODES
+ */
+function detectMode(options = {}) {
+  if (options.last_frame_image) return 'first-last';
+  if (options.subject_reference) return 'subject';
+  if (options.first_frame_image) return 'image';
+  return 'text';
+}
+
+/**
+ * Validates that the chosen model is compatible with the detected/provided mode.
+ * Throws a clear, helpful error if not.
+ */
+function validateModelForMode(model, mode, options = {}) {
+  const supported = getSupportedModelsForMode(mode);
+  if (!supported.includes(model)) {
+    const supportedList = supported.join(', ');
+    throw new Error(
+      `Model "${model}" does NOT support "${mode}" mode.\n` +
+      `Supported models for "${mode}": ${supportedList}\n` +
+      `Please choose a compatible model or omit the model to use the default for this mode.`
+    );
+  }
+}
+
 /**
  * Get authentication headers for Minimax API.
  *
@@ -49,7 +187,7 @@ const getHeaders = () => {
     'Content-Type': 'application/json',
     'Authorization': `Bearer ${process.env.MINIMAX_API_KEY}`
   };
-};
+}
 
 /**
  * Saves video data from a download URL to a local temporary file.
@@ -97,7 +235,6 @@ async function waitForVideoReady(taskId, maxWaitMs = 300000, pollIntervalMs = 50
     const status = result.status;
 
     if (status !== lastStatus) {
-      console.log(`[Minimax Video] Task ${taskId} status: ${status}`);
       lastStatus = status;
     }
 
@@ -111,7 +248,7 @@ async function waitForVideoReady(taskId, maxWaitMs = 300000, pollIntervalMs = 50
     await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
   }
 
-  throw new Error(`Video generation timed out after ${maxWaitMs / 1000}s. Last status: ${lastStatus}`);
+  throw new Error(`minimax task_id : ${taskId} -  Video generation timed out after ${maxWaitMs / 1000}s. Last status: ${lastStatus}`);
 }
 
 /**
@@ -120,30 +257,82 @@ async function waitForVideoReady(taskId, maxWaitMs = 300000, pollIntervalMs = 50
  * Uses POST /v1/video_generation.
  * Supports all documented models and input types via options.
  *
- * @param {string} [prompt] - Text description (required for most modes).
- * @param {Object} [options]
+ * The function now includes **clear validation** so you get an explicit error
+ * instead of a cryptic API rejection.
+ *
+ * @param {string} [prompt=''] - Text description (required for most modes). Max 2000 chars.
+ *   Supports camera commands in [] for supported models, e.g. [Pan left], [Truck right].
+ * @param {Object} [options={}] - Generation options.
+ *
+ * @param {string} [options.model] - Model name. If omitted, a sensible default is chosen based on mode.
+ *   See the mapping table at the top of this file.
+ *
+ * @param {string} [options.first_frame_image] - **Public HTTP/HTTPS URL only** (no Base64/data: URLs).
+ *
+ * @param {string} [options.last_frame_image] - **Public HTTP/HTTPS URL only** (no Base64/data: URLs) — First & Last Frame mode only.
+ *
+ * @param {Array<Object>} [options.subject_reference] - For subject-reference mode (S2V-01 only).
+ *   Each item must be `{ type: "character", image: ["https://..."] }` with **exactly one URL** in the image array.
+ *
+ * @param {boolean} [options.prompt_optimizer=true] - Auto-optimize prompt (default true).
+ *
+ * @param {boolean} [options.fast_pretreatment=false] - Reduce optimization time (Hailuo models only).
+ *
+ * @param {number} [options.duration=6] - Video length in seconds (model/resolution dependent).
+ *
+ * @param {string} [options.resolution] - e.g. '768P', '1080P', '720P' (model dependent).
  *
- * @param {string} [options.model='MiniMax-Hailuo-2.3'] - Default model.
- *   Supported: MiniMax-Hailuo-2.3, MiniMax-Hailuo-02, T2V-01, I2V-01, S2V-01, etc.
+ * @param {string} [options.callback_url] - Optional webhook for async status updates.
  *
- * @param {string} [options.first_frame_image] - URL or data: URL for image-to-video / first-last.
- * @param {string} [options.last_frame_image] - For first & last frame mode.
- * @param {Array<Object>} [options.subject_reference] - For subject-reference mode.
+ * @param {Object} [options.extra] - Any additional parameters.
  *
- * @param {boolean} [options.prompt_optimizer=true]
- * @param {boolean} [options.fast_pretreatment=false]
- * @param {number} [options.duration=6]
- * @param {string} [options.resolution] - e.g. '768P', '1080P'
- * @param {string} [options.callback_url]
+ * @returns {Promise<{task_id: string, duration: number, raw: object}>}
  *
- * @returns {Promise<{task_id: string, raw: object}>}
+ * @example
+ * // Text-to-Video (default)
+ * await createVideoGenerationTask("A cat jumping [Pan left]", { model: "MiniMax-Hailuo-2.3" });
+ *
+ * @example
+ * // First & Last Frame — MUST use MiniMax-Hailuo-02 + public URLs
+ * await createVideoGenerationTask("", {
+ *   model: "MiniMax-Hailuo-02",
+ *   first_frame_image: "https://example.com/first.jpg",
+ *   last_frame_image: "https://example.com/last.jpg"
+ * });
+ *
+ * @example
+ * // Subject-Reference (S2V-01) — exactly one image per reference
+ * await createVideoGenerationTask("...", {
+ *   model: "S2V-01",
+ *   subject_reference: [
+ *     { type: "character", image: ["https://example.com/puppet.jpg"] },
+ *     { type: "character", image: ["https://example.com/girl.png"] }
+ *   ]
+ * });
  */
 async function createVideoGenerationTask(prompt = '', options = {}) {
+  const mode = detectMode(options);
+  let model = options.model;
+
+  // Choose a sensible default if no model provided
+  if (!model) {
+    const supported = getSupportedModelsForMode(mode);
+    model = supported[0];
+  }
+
+  // Validate model compatibility
+  validateModelForMode(model, mode, options);
+
+  // === STRICT URL VALIDATION (no Base64) ===
+  validateImageUrl('first_frame_image', options.first_frame_image);
+  validateImageUrl('last_frame_image', options.last_frame_image);
+  validateSubjectReference(options.subject_reference);
+
   const headers = getHeaders();
   const url = `${BASE_URL}/video_generation`;
 
   const body = {
-    model: options.model || 'MiniMax-Hailuo-2.3',
+    model,
     prompt: prompt,
     prompt_optimizer: options.prompt_optimizer ?? true,
     fast_pretreatment: options.fast_pretreatment ?? false,
@@ -161,7 +350,7 @@ async function createVideoGenerationTask(prompt = '', options = {}) {
   const res = await doRequest(url, 'POST', headers, body);
   const duration = Date.now() - start;
 
-  if (res.status !== 200) {
+  if (res.status !== 200 || !res.response.task_id) {
     throw new Error(`Minimax video generation error ${res.status}: ${JSON.stringify(res.response)}`);
   }
 
@@ -177,7 +366,7 @@ async function createVideoGenerationTask(prompt = '', options = {}) {
  *
  * GET /v1/query/video_generation?task_id=...
  *
- * @param {string} taskId
+ * @param {string} taskId - The task_id returned by createVideoGenerationTask.
  * @returns {Promise<{
  *   task_id: string,
  *   status: 'Preparing' | 'Queueing' | 'Processing' | 'Success' | 'Fail',
@@ -193,7 +382,7 @@ async function queryVideoGenerationTask(taskId) {
 
   const res = await doRequest(url, 'GET', headers);
 
-  if (res.status !== 200) {
+  if (res.status !== 200 || !res.response.task_id) {
     throw new Error(`Minimax query error ${res.status}: ${JSON.stringify(res.response)}`);
   }
 
@@ -212,7 +401,7 @@ async function queryVideoGenerationTask(taskId) {
  *
  * GET /v1/files/retrieve?file_id=...
  *
- * @param {string|number} fileId
+ * @param {string|number} fileId - The file_id from a successful query.
  * @returns {Promise<{
  *   file_id: string,
  *   filename: string,
@@ -227,7 +416,7 @@ async function retrieveVideoFile(fileId) {
 
   const res = await doRequest(url, 'GET', headers);
 
-  if (res.status !== 200) {
+  if (res.status !== 200 || !res.response.file) {
     throw new Error(`Minimax retrieve file error ${res.status}: ${JSON.stringify(res.response)}`);
   }
 
@@ -247,13 +436,13 @@ async function retrieveVideoFile(fileId) {
  * Handles the full async flow: create task → poll until ready → retrieve → download to .cache/minimax/
  *
  * Supports all video generation modes (text, image-to-video, first-last, subject-ref)
- * by passing the appropriate options.
+ * by passing the appropriate options. **Model validation + strict public-URL validation** are enforced.
  *
  * @param {string} prompt - Text prompt (can be empty for some modes).
- * @param {Object} [options] - Same as createVideoGenerationTask + polling options.
+ * @param {Object} [options={}] - Same as createVideoGenerationTask + polling options.
  *
- * @param {number} [options.max_wait_ms=300000]
- * @param {number} [options.poll_interval_ms=5000]
+ * @param {number} [options.max_wait_ms=300000] - Max polling time (5 minutes).
+ * @param {number} [options.poll_interval_ms=5000] - Polling interval in ms.
  *
  * @returns {Promise<{
  *   task_id: string,
@@ -267,24 +456,17 @@ async function retrieveVideoFile(fileId) {
  * }>}
  *
  * @example
- * // Text-to-Video
- * const result = await generateVideo("A cat jumping on a table [Pan left]", {
- *   model: "MiniMax-Hailuo-2.3",
- *   duration: 6,
- *   resolution: "768P"
- * });
- *
- * @example
- * // Image-to-Video
- * const result = await generateVideo("The character walks forward", {
- *   model: "MiniMax-Hailuo-2.3",
- *   first_frame_image: "https://example.com/image.jpg"
+ * // First & Last Frame (correct model + public URLs only)
+ * const result = await generateVideo("", {
+ *   model: "MiniMax-Hailuo-02",
+ *   first_frame_image: "https://example.com/first.jpg",
+ *   last_frame_image: "https://example.com/last.jpg"
  * });
  */
 async function generateVideo(prompt = '', options = {}) {
   const start = Date.now();
 
-  // Step 1: Create task
+  // Step 1: Create task (validation happens inside createVideoGenerationTask)
   const createResult = await createVideoGenerationTask(prompt, options);
   const taskId = createResult.task_id;
 
@@ -301,7 +483,7 @@ async function generateVideo(prompt = '', options = {}) {
 
   const fileId = readyResult.file_id;
   if (!fileId) {
-    throw new Error('No file_id in successful video response');
+    throw new Error('No file_id in successful video response:\n' + JSON.stringify(readyResult));
   }
 
   // Step 3: Retrieve download URL
@@ -335,5 +517,12 @@ export {
   queryVideoGenerationTask,
   retrieveVideoFile,
   generateVideo,
-  waitForVideoReady
+  waitForVideoReady,
+  // New exports for clarity / testing
+  getSupportedModelsForMode,
+  detectMode,
+  validateModelForMode,
+  isValidPublicUrl,
+  validateImageUrl,
+  validateSubjectReference
 };