@j-o-r/hello-dave 0.0.10 → 0.1.1

package/lib/API/minimax/video.js

@@ -0,0 +1,339 @@
+/**
+ * @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
+ *
+ *              This is a **new library** — only the current response format is supported.
+ *              No backward compatibility with legacy response structures.
+ *
+ *              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)
+ *              3. Retrieve file_id → get download_url
+ *              4. Download video to local .cache/minimax/
+ */
+
+import { request as doRequest } from '@j-o-r/apiserver';
+import fs from 'fs/promises';
+import path from 'path';
+
+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');
+
+/**
+ * Get authentication headers for Minimax API.
+ *
+ * @returns {Object} Headers object with Authorization Bearer token.
+ * @throws {Error} If MINIMAX_API_KEY environment variable is not set.
+ */
+const getHeaders = () => {
+  if (!process.env.MINIMAX_API_KEY) {
+    throw new Error('Missing MINIMAX_API_KEY! Please export MINIMAX_API_KEY=your_key');
+  }
+  return {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${process.env.MINIMAX_API_KEY}`
+  };
+};
+
+/**
+ * Saves video data from a download URL to a local temporary file.
+ * Handles MP4 videos.
+ *
+ * @param {string} videoUrl - Public download URL from retrieveVideoFile().
+ * @param {string} [filenamePrefix='minimax-video'] - Prefix for the local filename.
+ * @returns {Promise<string>} Absolute path to the saved local file.
+ */
+async function saveVideoToLocal(videoUrl, filenamePrefix = 'minimax-video') {
+  const tmpDir = path.join(process.cwd(), '.cache', 'minimax');
+  await fs.mkdir(tmpDir, { recursive: true });
+
+  const filename = `${filenamePrefix}-${Date.now()}.mp4`;
+  const localPath = path.join(tmpDir, filename);
+
+  if (typeof videoUrl === 'string' && videoUrl.startsWith('http')) {
+    const response = await fetch(videoUrl);
+    if (!response.ok) {
+      throw new Error(`Failed to download video: ${response.status} ${response.statusText}`);
+    }
+    const buffer = Buffer.from(await response.arrayBuffer());
+    await fs.writeFile(localPath, buffer);
+  } else {
+    throw new Error('Invalid video URL provided to saveVideoToLocal');
+  }
+
+  return localPath;
+}
+
+/**
+ * Internal helper: Waits for video generation task to complete by polling.
+ *
+ * @param {string} taskId
+ * @param {number} [maxWaitMs=300000] - Max wait time (5 minutes default)
+ * @param {number} [pollIntervalMs=5000] - Poll every 5 seconds
+ * @returns {Promise<{status: string, file_id?: string, video_width?: number, video_height?: number, raw: object}>}
+ */
+async function waitForVideoReady(taskId, maxWaitMs = 300000, pollIntervalMs = 5000) {
+  const startTime = Date.now();
+  let lastStatus = '';
+
+  while (Date.now() - startTime < maxWaitMs) {
+    const result = await queryVideoGenerationTask(taskId);
+    const status = result.status;
+
+    if (status !== lastStatus) {
+      console.log(`[Minimax Video] Task ${taskId} status: ${status}`);
+      lastStatus = status;
+    }
+
+    if (status === 'Success') {
+      return result;
+    }
+    if (status === 'Fail') {
+      throw new Error(`Video generation failed: ${JSON.stringify(result.raw)}`);
+    }
+
+    await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+  }
+
+  throw new Error(`Video generation timed out after ${maxWaitMs / 1000}s. Last status: ${lastStatus}`);
+}
+
+/**
+ * Creates a video generation task (Text-to-Video, Image-to-Video, First-Last, Subject-Ref).
+ *
+ * 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]
+ *
+ * @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.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 {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, raw: object}>}
+ */
+async function createVideoGenerationTask(prompt = '', options = {}) {
+  const headers = getHeaders();
+  const url = `${BASE_URL}/video_generation`;
+
+  const body = {
+    model: options.model || 'MiniMax-Hailuo-2.3',
+    prompt: prompt,
+    prompt_optimizer: options.prompt_optimizer ?? true,
+    fast_pretreatment: options.fast_pretreatment ?? false,
+    duration: options.duration ?? 6,
+    ...options.extra
+  };
+
+  if (options.resolution) body.resolution = options.resolution;
+  if (options.callback_url) body.callback_url = options.callback_url;
+  if (options.first_frame_image) body.first_frame_image = options.first_frame_image;
+  if (options.last_frame_image) body.last_frame_image = options.last_frame_image;
+  if (options.subject_reference) body.subject_reference = options.subject_reference;
+
+  const start = Date.now();
+  const res = await doRequest(url, 'POST', headers, body);
+  const duration = Date.now() - start;
+
+  if (res.status !== 200) {
+    throw new Error(`Minimax video generation error ${res.status}: ${JSON.stringify(res.response)}`);
+  }
+
+  return {
+    task_id: res.response?.task_id,
+    duration,
+    raw: res.response
+  };
+}
+
+/**
+ * Queries the status of a video generation task.
+ *
+ * GET /v1/query/video_generation?task_id=...
+ *
+ * @param {string} taskId
+ * @returns {Promise<{
+ *   task_id: string,
+ *   status: 'Preparing' | 'Queueing' | 'Processing' | 'Success' | 'Fail',
+ *   file_id?: string,
+ *   video_width?: number,
+ *   video_height?: number,
+ *   raw: object
+ * }>}
+ */
+async function queryVideoGenerationTask(taskId) {
+  const headers = getHeaders();
+  const url = `${BASE_URL}/query/video_generation?task_id=${encodeURIComponent(taskId)}`;
+
+  const res = await doRequest(url, 'GET', headers);
+
+  if (res.status !== 200) {
+    throw new Error(`Minimax query error ${res.status}: ${JSON.stringify(res.response)}`);
+  }
+
+  return {
+    task_id: res.response?.task_id,
+    status: res.response?.status,
+    file_id: res.response?.file_id,
+    video_width: res.response?.video_width,
+    video_height: res.response?.video_height,
+    raw: res.response
+  };
+}
+
+/**
+ * Retrieves file metadata and download URL for a completed video.
+ *
+ * GET /v1/files/retrieve?file_id=...
+ *
+ * @param {string|number} fileId
+ * @returns {Promise<{
+ *   file_id: string,
+ *   filename: string,
+ *   download_url: string,
+ *   bytes: number,
+ *   raw: object
+ * }>}
+ */
+async function retrieveVideoFile(fileId) {
+  const headers = getHeaders();
+  const url = `${BASE_URL}/files/retrieve?file_id=${encodeURIComponent(fileId)}`;
+
+  const res = await doRequest(url, 'GET', headers);
+
+  if (res.status !== 200) {
+    throw new Error(`Minimax retrieve file error ${res.status}: ${JSON.stringify(res.response)}`);
+  }
+
+  const file = res.response?.file || {};
+
+  return {
+    file_id: file.file_id,
+    filename: file.filename,
+    download_url: file.download_url,
+    bytes: file.bytes,
+    raw: res.response
+  };
+}
+
+/**
+ * High-level video generation function.
+ * 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.
+ *
+ * @param {string} prompt - Text prompt (can be empty for some modes).
+ * @param {Object} [options] - Same as createVideoGenerationTask + polling options.
+ *
+ * @param {number} [options.max_wait_ms=300000]
+ * @param {number} [options.poll_interval_ms=5000]
+ *
+ * @returns {Promise<{
+ *   task_id: string,
+ *   file_id: string,
+ *   video_url: string,           // download_url
+ *   local_path: string,          // path in .cache/minimax/
+ *   video_width: number,
+ *   video_height: number,
+ *   duration: number,            // total time including polling
+ *   raw: object
+ * }>}
+ *
+ * @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"
+ * });
+ */
+async function generateVideo(prompt = '', options = {}) {
+  const start = Date.now();
+
+  // Step 1: Create task
+  const createResult = await createVideoGenerationTask(prompt, options);
+  const taskId = createResult.task_id;
+
+  if (!taskId) {
+    throw new Error('No task_id returned from video generation');
+  }
+
+  // Step 2: Wait for completion
+  const readyResult = await waitForVideoReady(
+    taskId,
+    options.max_wait_ms ?? 300000,
+    options.poll_interval_ms ?? 5000
+  );
+
+  const fileId = readyResult.file_id;
+  if (!fileId) {
+    throw new Error('No file_id in successful video response');
+  }
+
+  // Step 3: Retrieve download URL
+  const fileResult = await retrieveVideoFile(fileId);
+
+  // Step 4: Download to local
+  const localPath = await saveVideoToLocal(fileResult.download_url, 'minimax-video');
+
+  const totalDuration = Date.now() - start;
+
+  return {
+    task_id: taskId,
+    file_id: fileId,
+    video_url: fileResult.download_url,
+    local_path: localPath,
+    video_width: readyResult.video_width,
+    video_height: readyResult.video_height,
+    duration: totalDuration,
+    raw: {
+      create: createResult.raw,
+      query: readyResult.raw,
+      retrieve: fileResult.raw
+    }
+  };
+}
+
+export {
+  getHeaders,
+  saveVideoToLocal,
+  createVideoGenerationTask,
+  queryVideoGenerationTask,
+  retrieveVideoFile,
+  generateVideo,
+  waitForVideoReady
+};

package/lib/API/minimax/video.query.md

@@ -0,0 +1,128 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://platform.minimax.io/docs/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Query Video Generation Task Status
+
+
+
+## OpenAPI
+
+````yaml /api-reference/video/generation/api/openapi.json GET /v1/query/video_generation
+openapi: 3.1.0
+info:
+  title: MiniMax API
+  description: MiniMax video generation and file management API
+  license:
+    name: MIT
+  version: 1.0.0
+servers:
+  - url: https://api.minimax.io
+security:
+  - bearerAuth: []
+paths:
+  /v1/query/video_generation:
+    get:
+      tags:
+        - Video
+      summary: Query Video Generation Task
+      operationId: queryVideoGenerationTask
+      parameters:
+        - name: task_id
+          in: query
+          required: true
+          description: >-
+            The task ID to query. Only tasks created under the current account
+            can be queried.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: ''
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/QueryVideoGenerationTaskResp'
+components:
+  schemas:
+    QueryVideoGenerationTaskResp:
+      type: object
+      properties:
+        task_id:
+          type: string
+          description: The queried task ID.
+        status:
+          $ref: '#/components/schemas/VideoProcessStatus'
+        file_id:
+          type: string
+          description: >-
+            Returned when the task succeeds. Represents the file ID of the
+            generated video.
+        video_width:
+          type: integer
+          description: >-
+            Returned when the task succeeds. The width of the generated video
+            (in pixels).
+        video_height:
+          type: integer
+          description: >-
+            Returned when the task succeeds. The height of the generated video
+            (in pixels).
+        base_resp:
+          $ref: '#/components/schemas/QueryVideoGenerationTaskBaseResp'
+      example:
+        task_id: '176843862716480'
+        status: Success
+        file_id: '176844028768320'
+        video_width: 1920
+        video_height: 1080
+        base_resp:
+          status_code: 0
+          status_msg: success
+    VideoProcessStatus:
+      type: string
+      enum:
+        - Preparing
+        - Queueing
+        - Processing
+        - Success
+        - Fail
+      description: |-
+        The current status of the task. Possible values:
+        - `Preparing` – Preparing
+        - `Queueing` – In queue
+        - `Processing` – Generating
+        - `Success` – Completed successfully
+        - `Fail` – Failed
+    QueryVideoGenerationTaskBaseResp:
+      type: object
+      properties:
+        status_code:
+          type: integer
+          description: |-
+            The status codes are as follows:
+            - `0`, Request successful;
+            - `1002`,  Rate limit triggered, retry later
+            - `1004`, Authentication failed, check API Key
+            - `1026`, Contains sensitive content in the input
+            - `1027`, Contains sensitive content in the generated video
+
+             For more information, please refer to the [Error Code Reference](/api-reference/errorcode).
+        status_msg:
+          type: string
+          description: Status message. Returns `success` when successful.
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: >-
+        `HTTP: Bearer Auth`
+
+        - Security Scheme Type: http
+
+        - HTTP Authorization Scheme: `Bearer API_key`, can be found in [Account
+        Management>API
+        Keys](https://platform.minimax.io/user-center/basic-information/interface-key).
+
+````