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

package/lib/API/minimax/image.js

@@ -0,0 +1,219 @@
+/**
+ * @file lib/API/minimax/image.js
+ * @module minimax/image
+ * @description Pure HTTP wrapper for the Minimax Image Generation API.
+ *              Fully aligned with the official documentation:
+ *              - lib/API/minimax/image.generation.md
+ *              - lib/API/minimax/image.to.image.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.
+ */
+
+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 image data (either URL or base64) to a local temporary file.
+ * Handles both `response_format: 'url'` and `response_format: 'base64'`.
+ * Supports data URL prefix for base64.
+ *
+ * @param {string} imageData - Either a URL or a base64-encoded string (with or without data: prefix).
+ * @param {string} [filenamePrefix='minimax-image'] - Prefix for the local filename.
+ * @param {number} [index=0] - Index for multiple images to avoid filename collisions.
+ * @returns {Promise<string>} Absolute path to the saved local file.
+ */
+async function saveImageToLocal(imageData, filenamePrefix = 'minimax-image', index = 0) {
+  const tmpDir = path.join(process.cwd(), '.cache', 'minimax');
+  await fs.mkdir(tmpDir, { recursive: true });
+
+  const filename = `${filenamePrefix}-${Date.now()}-${index}.png`;
+  const localPath = path.join(tmpDir, filename);
+
+  if (typeof imageData === 'string' && imageData.startsWith('http')) {
+    // URL case
+    const response = await fetch(imageData);
+    if (!response.ok) {
+      throw new Error(`Failed to download image: ${response.status} ${response.statusText}`);
+    }
+    const buffer = Buffer.from(await response.arrayBuffer());
+    await fs.writeFile(localPath, buffer);
+  } else if (typeof imageData === 'string') {
+    // Base64 case (with or without data: prefix)
+    let base64Data = imageData;
+    if (imageData.startsWith('data:')) {
+      base64Data = imageData.split(',')[1];
+    }
+    const buffer = Buffer.from(base64Data, 'base64');
+    await fs.writeFile(localPath, buffer);
+  } else {
+    throw new Error('Invalid image data provided to saveImageToLocal');
+  }
+
+  return localPath;
+}
+
+/**
+ * Core image generation request (supports both Text-to-Image and Image-to-Image).
+ *
+ * Fully implements the official Minimax Image Generation API
+ * as documented in `lib/API/minimax/image.generation.md` and `image.to.image.md`.
+ *
+ * Uses the single endpoint `/v1/image_generation`.
+ *
+ * Supports all models, parameters, and response formats.
+ *
+ * @param {string} prompt - Text description of the image, max 1500 characters.
+ * @param {Object} [options] - All available options from the official spec.
+ *
+ * @param {string} [options.model='image-01'] - Model to use.
+ *   Supported values:
+ *   - 'image-01' (default, text-to-image and img2img)
+ *   - 'image-01-live' (for image-to-image)
+ *
+ * @param {string} [options.aspect_ratio='1:1'] - Image aspect ratio.
+ *   Options: '1:1', '16:9', '4:3', '3:2', '2:3', '3:4', '9:16', '21:9'
+ *
+ * @param {number} [options.width] - Image width in px (512-2048, divisible by 8).
+ *   Only effective for model 'image-01'. aspect_ratio takes priority if both provided.
+ *
+ * @param {number} [options.height] - Image height in px (same rules as width).
+ *
+ * @param {string} [options.response_format='url'] - 'url' or 'base64'.
+ *   Default is `'url'` (user preference).
+ *   ⚠️ `url` links expire after 24 hours.
+ *
+ * @param {number} [options.seed] - Random seed for reproducibility.
+ *
+ * @param {number} [options.n=1] - Number of images to generate (1-9).
+ *
+ * @param {boolean} [options.prompt_optimizer=false] - Enable automatic prompt optimization.
+ *
+ * @param {Array<Object>} [options.subject_reference] - For Image-to-Image.
+ *   Array of subject references. Currently supports:
+ *   - { type: 'character', image_file: 'https://...' or 'data:image/...;base64,...' }
+ *
+ * @param {Object} [options.extra] - Any additional parameters not yet documented.
+ *
+ * @returns {Promise<{
+ *   image_urls: string[],        // Array from data.image_urls (if url format)
+ *   image_base64: string[],      // Array from data.image_base64 (if base64 format)
+ *   local_paths: string[],       // Absolute paths to saved files
+ *   metadata: Object,            // { success_count, failed_count }
+ *   id: string,                  // Trace ID
+ *   duration: number,            // API call duration in milliseconds
+ *   raw: object                  // Full raw response
+ * }>}
+ *
+ * @example
+ * // Text-to-Image (basic)
+ * const result = await requestImage("A serene mountain landscape at sunset", {
+ *   model: "image-01",
+ *   aspect_ratio: "16:9",
+ *   n: 2
+ * });
+ *
+ * @example
+ * // Image-to-Image
+ * const result = await requestImage("A girl looking into the distance", {
+ *   model: "image-01",
+ *   subject_reference: [{
+ *     type: "character",
+ *     image_file: "https://example.com/portrait.jpg"
+ *   }],
+ *   n: 1
+ * });
+ */
+async function requestImage(prompt, options = {}) {
+  const headers = getHeaders();
+  const url = `${BASE_URL}/image_generation`;
+
+  const body = {
+    model: options.model || 'image-01',
+    prompt: prompt,
+    aspect_ratio: options.aspect_ratio || '1:1',
+    response_format: options.response_format || 'url',   // User preference: URL as default
+    n: options.n ?? 1,
+    prompt_optimizer: options.prompt_optimizer ?? false,
+    ...options.extra
+  };
+
+  if (options.width !== undefined) body.width = options.width;
+  if (options.height !== undefined) body.height = options.height;
+  if (options.seed !== undefined) body.seed = options.seed;
+  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 API error ${res.status}: ${JSON.stringify(res.response)}`);
+  }
+
+  const respData = res.response?.data || {};
+  const metadata = res.response?.metadata || {};
+  const traceId = res.response?.id;
+
+  let imageDataArray = [];
+
+  if (respData.image_urls && Array.isArray(respData.image_urls) && respData.image_urls.length > 0) {
+    imageDataArray = respData.image_urls;
+  } else if (respData.image_base64 && Array.isArray(respData.image_base64) && respData.image_base64.length > 0) {
+    imageDataArray = respData.image_base64;
+  }
+
+  if (imageDataArray.length === 0) {
+    throw new Error('No image data found in data.image_urls or data.image_base64 of Minimax response');
+  }
+
+  const localPaths = [];
+  for (let i = 0; i < imageDataArray.length; i++) {
+    const localPath = await saveImageToLocal(imageDataArray[i], 'minimax-image', i);
+    localPaths.push(localPath);
+  }
+
+  return {
+    image_urls: respData.image_urls || [],
+    image_base64: respData.image_base64 || [],
+    local_paths: localPaths,
+    metadata,
+    id: traceId,
+    duration,
+    raw: res.response
+  };
+}
+
+export {
+  getHeaders,
+  saveImageToLocal,
+  requestImage
+};

package/lib/API/minimax/image.to.image.md

@@ -0,0 +1,257 @@
+> ## 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.
+
+# Image-to-Image Generation
+
+> Use this API to generate images from image input.
+
+
+
+## OpenAPI
+
+````yaml /api-reference/image/generation/api/image-to-image.json POST /v1/image_generation
+openapi: 3.1.0
+info:
+  title: MiniMax Image Generation API
+  description: MiniMax image generation API for creating images from text prompts
+  license:
+    name: MIT
+  version: 1.0.0
+servers:
+  - url: https://api.minimax.io
+security:
+  - bearerAuth: []
+paths:
+  /v1/image_generation:
+    post:
+      tags:
+        - Image
+      summary: Image Generation
+      operationId: imageGeneration
+      parameters:
+        - name: Content-Type
+          in: header
+          required: true
+          description: >-
+            The media type of the request body. Must be set to
+            `application/json` to ensure the data is sent in JSON format.
+          schema:
+            type: string
+            enum:
+              - application/json
+            default: application/json
+      requestBody:
+        description: ''
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ImageGenerationReq'
+        required: true
+      responses:
+        '200':
+          description: ''
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ImageGenerationResp'
+components:
+  schemas:
+    ImageGenerationReq:
+      type: object
+      required:
+        - prompt
+        - model
+      properties:
+        model:
+          type: string
+          description: 'Model name. Options: `image-01`.'
+          enum:
+            - image-01
+            - image-01-live
+        prompt:
+          type: string
+          description: Text description of the image, max length 1500 characters.
+        subject_reference:
+          type: array
+          items:
+            $ref: '#/components/schemas/ImageSubjectReference'
+          description: Subject reference for image-to-image generation.
+        aspect_ratio:
+          type: string
+          description: |-
+            Image aspect ratio, default `1:1`. Options:
+            - `1:1` (1024x1024)
+            - `16:9` (1280x720)
+            - `4:3` (1152x864)
+            - `3:2` (1248x832)
+            - `2:3` (832x1248)
+            - `3:4` (864x1152)
+            - `9:16` (720x1280)
+            - `21:9` (1344x576)
+          enum:
+            - '1:1'
+            - '16:9'
+            - '4:3'
+            - '3:2'
+            - '2:3'
+            - '3:4'
+            - '9:16'
+            - '21:9'
+        width:
+          type: integer
+          description: >-
+            Image width (px). Only effective for `image-01`. Must be set
+            together with `height`. Range [512, 2048], must be divisible by 8.
+            If both `width/height` and `aspect_ratio` are provided,
+            `aspect_ratio` takes priority.
+        height:
+          type: integer
+          description: >-
+            Height of generated image (pixels). Only effective when `model` is
+            `image-01`.
+
+            Same rules as `width`.
+        response_format:
+          type: string
+          enum:
+            - url
+            - base64
+          default: url
+          description: |-
+            Response format for images. Default: url. Options: url, base64.
+            ⚠️ Note: url expires in 24 hours.
+        seed:
+          type: integer
+          format: int64
+          description: >-
+            Random seed. Using the same seed and parameters allows result
+            reproduction.
+
+            If omitted, each of the n images will use a unique random seed.
+        'n':
+          type: integer
+          default: 1
+          minimum: 1
+          maximum: 9
+          description: 'Number of images to generate per request. Range [1, 9]. Default: 1.'
+        prompt_optimizer:
+          type: boolean
+          default: false
+          description: 'Enable automatic optimization of prompt. Default: `false`.'
+      example:
+        model: image-01
+        prompt: A girl looking into the distance from a library window
+        aspect_ratio: '16:9'
+        subject_reference:
+          - type: character
+            image_file: >-
+              https://cdn.hailuoai.com/prod/2025-08-12-17/video_cover/1754990600020238321-411603868533342214-cover.jpg
+        'n': 2
+    ImageGenerationResp:
+      type: object
+      properties:
+        data:
+          $ref: '#/components/schemas/DataObject'
+        metadata:
+          type: object
+          properties:
+            success_count:
+              type: integer
+              description: Number of successfully generated images.
+            failed_count:
+              type: integer
+              description: Number of images blocked due to content safety.
+          description: Additional metadata about the generation.
+        id:
+          type: string
+          description: Trace ID for request tracking
+        base_resp:
+          $ref: '#/components/schemas/BaseResp'
+      example:
+        id: 03ff3cd0820949eb8a410056b5f21d38
+        data:
+          image_urls:
+            - XXX
+            - XXX
+            - XXX
+        metadata:
+          failed_count: '0'
+          success_count: '3'
+        base_resp:
+          status_code: 0
+          status_msg: success
+    ImageSubjectReference:
+      type: object
+      required:
+        - type
+        - image_file
+      properties:
+        type:
+          type: string
+          description: Subject type. Currently only supports `character` (portrait).
+        image_file:
+          type: string
+          description: "Reference image file. Supports public URLs or Base64-encoded [Data URL](https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes/data) (`data:image/jpeg;base64,...`).\nFor best results, upload a single front-facing portrait photo.\n- Image requirements:\n\t- Formats: JPG, JPEG, PNG\n\t- Size: less than 10MB"
+    DataObject:
+      type: object
+      properties:
+        image_urls:
+          type: array
+          items:
+            type: string
+          description: >-
+            Returned when `response_format` = `url`, contains an array of image
+            links.
+        image_base64:
+          type: array
+          items:
+            type: string
+          description: >-
+            Returned when `response_format` = `base64`, contains an array of
+            base64-encoded images.
+    BaseResp:
+      type: object
+      properties:
+        status_code:
+          type: integer
+          description: >-
+            The status codes and their meanings are as follows:
+
+            - `0`, Request successful
+
+            - `1002`, Rate limit triggered, please try again later
+
+            - `1004`, Account authentication failed, please check if the API Key
+            is correct
+
+            - `1008`, Insufficient account balance
+
+            - `1026`, Sensitive content detected in prompt
+
+            - `2013`, Invalid input parameters, please check if the parameters
+            are filled in as required
+
+            - `2049`, Invalid API key
+
+
+            For more information, please refer to the [Error Code
+            Reference](/api-reference/errorcode).  
+        status_msg:
+          type: string
+          description: Status details.
+  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).
+
+````

package/lib/API/minimax/index.js

@@ -0,0 +1,16 @@
+import * as music from './music.js';
+import * as image from './image.js';
+import * as video from './video.js';
+
+import musicToolset from './MusicToolset.js'
+import videoToolset from './VideoToolset.js'
+import imageToolset from './ImageToolset.js'
+
+export default {
+	music,
+	musicToolset,
+	video,
+	videoToolset,
+	image,
+	imageToolset
+}

package/lib/API/minimax/music.cover.preprocess.md

@@ -0,0 +1,206 @@
+> ## 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.
+
+# Music Cover Preprocess
+
+> Preprocess reference audio to extract features and lyrics for two-step cover generation.
+
+
+
+## OpenAPI
+
+````yaml POST /v1/music_cover_preprocess
+openapi: 3.1.0
+info:
+  title: MiniMax Music Generation API
+  description: >-
+    MiniMax music generation API with support for creating music from text
+    prompts and lyrics
+  license:
+    name: MIT
+  version: 1.0.0
+servers:
+  - url: https://api.minimax.io
+security:
+  - bearerAuth: []
+paths:
+  /v1/music_cover_preprocess:
+    post:
+      tags:
+        - Music
+      summary: Music Cover Preprocess
+      operationId: coverPreprocess
+      parameters:
+        - name: Content-Type
+          in: header
+          required: true
+          description: >-
+            The media type of the request body. Must be set to
+            `application/json` to ensure the data is sent in JSON format.
+          schema:
+            type: string
+            enum:
+              - application/json
+            default: application/json
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CoverPreprocessReq'
+        required: true
+      responses:
+        '200':
+          description: ''
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CoverPreprocessResp'
+components:
+  schemas:
+    CoverPreprocessReq:
+      type: object
+      required:
+        - model
+      properties:
+        model:
+          type: string
+          description: Model name. Must be `music-cover`.
+          enum:
+            - music-cover
+        audio_url:
+          type: string
+          description: >-
+            URL of the reference audio. Exactly one of `audio_url` or
+            `audio_base64` must be provided.
+
+
+            Reference audio constraints:
+
+            - Duration: 6 seconds to 6 minutes
+
+            - Size: max 50 MB
+
+            - Format: common audio formats (mp3, wav, flac, etc.)
+        audio_base64:
+          type: string
+          description: >-
+            Base64-encoded reference audio. Exactly one of `audio_url` or
+            `audio_base64` must be provided.
+
+
+            Reference audio constraints:
+
+            - Duration: 6 seconds to 6 minutes
+
+            - Size: max 50 MB
+
+            - Format: common audio formats (mp3, wav, flac, etc.)
+      example:
+        model: music-cover
+        audio_url: https://example.com/song.mp3
+    CoverPreprocessResp:
+      type: object
+      properties:
+        cover_feature_id:
+          type: string
+          description: >-
+            Unique identifier for the preprocessed audio features. Valid for 24
+            hours. Pass this to the [Music Generation
+            API](/api-reference/music-generation) `cover_feature_id` parameter
+            for two-step cover generation.
+
+
+            Same audio content returns the same `cover_feature_id` (MD5-based
+            deduplication).
+        formatted_lyrics:
+          type: string
+          description: >-
+            Structured lyrics extracted from the reference audio via ASR,
+            formatted with section tags such as `[Verse]`, `[Chorus]`,
+            `[Bridge]`, etc. You can modify these lyrics before passing them to
+            the Music Generation API.
+        structure_result:
+          type: string
+          description: >-
+            JSON string containing the song structure analysis result, including
+            segment types (`intro`, `verse`, `chorus`, `bridge`, `outro`,
+            `inst`, `silence`) and their start/end timestamps in seconds.
+        audio_duration:
+          type: number
+          format: double
+          description: Duration of the reference audio in seconds.
+        trace_id:
+          type: string
+          description: Unique trace ID for request tracking.
+        base_resp:
+          $ref: '#/components/schemas/BaseResp'
+      example:
+        cover_feature_id: a1b2c3d4e5f67890abcdef1234567890
+        formatted_lyrics: |-
+          [Verse 1]
+          First line of the song
+          Second line continues
+
+          [Chorus]
+          This is the chorus
+          Singing out loud
+        structure_result: >-
+          {"num_segments":4,"segments":[{"start":0,"end":15.5,"label":"intro"},{"start":15.5,"end":45.2,"label":"verse"},{"start":45.2,"end":75.0,"label":"chorus"},{"start":75.0,"end":90.0,"label":"outro"}]}
+        audio_duration: 90
+        trace_id: 061e5f144eb7f10b1fdde81126e24f91
+        base_resp:
+          status_code: 0
+          status_msg: success
+    BaseResp:
+      type: object
+      description: Status code and details
+      properties:
+        status_code:
+          type: integer
+          description: >-
+            Status codes and their meanings:
+
+
+            `0`: Success
+
+
+            `1002`: Rate limit triggered, retry later
+
+
+            `1004`: Authentication failed, check API key
+
+
+            `1008`: Insufficient balance
+
+
+            `1026`: Content flagged for sensitive material
+
+
+            `2013`: Invalid parameters, check input
+
+
+            `2049`: Invalid API key
+
+
+            For more information, please refer to the [Error Code
+            Reference](/api-reference/errorcode).
+        status_msg:
+          type: string
+          description: Detailed error message
+  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).
+
+````
+