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

package/lib/API/minimax/VideoToolset.js

@@ -0,0 +1,296 @@
+/**
+ * @file lib/API/minimax/VideoToolset.js
+ * @module minimax/VideoToolset
+ * @description Comprehensive ToolSet for the Minimax Video Generation API.
+ *
+ * This ToolSet exposes the full Minimax Video API with every available option
+ * and detailed return values, following the same pattern as lib/genericToolset.js,
+ * MusicToolset.js, and ImageToolset.js.
+ *
+ * It is designed to be used directly by AI agents or merged into larger toolsets.
+ *
+ * Video generation is asynchronous. The main `generate_video` tool automatically
+ * waits for completion and downloads the MP4 to .cache/minimax/.
+ *
+ * @example
+ * import videoToolset from './lib/API/minimax/VideoToolset.js';
+ *
+ * // Use in an agent:
+ * const toolset = agent.getToolset();
+ * toolset.merge(videoToolset);
+ */
+
+import ToolSet  from '../../ToolSet.js';
+import * as minimax from './video.js';
+
+const tools = new ToolSet('auto');
+
+/* ============================================================
+   CORE VIDEO GENERATION (Full async flow with auto-download)
+   ============================================================ */
+
+tools.add(
+  'generate_video',
+  'Generate a video using the Minimax Video Generation API. ' +
+  'Supports Text-to-Video, Image-to-Video, First & Last Frame, and Subject-Reference modes. ' +
+  'Automatically polls until the video is ready, then downloads the MP4 to .cache/minimax/. ' +
+  'This is the recommended high-level tool for video generation.',
+  {
+    type: 'object',
+    properties: {
+      prompt: {
+        type: 'string',
+        description: 'Text description of the video, up to 2000 characters. ' +
+                     'Supports camera movement commands in [brackets] for supported models. ' +
+                     'Example: "A cute cat jumping on a wooden table [Static shot]"'
+      },
+      model: {
+        type: 'string',
+        enum: [
+          'MiniMax-Hailuo-2.3',
+          'MiniMax-Hailuo-02',
+          'T2V-01-Director',
+          'T2V-01',
+          'MiniMax-Hailuo-2.3-Fast',
+          'I2V-01-Director',
+          'I2V-01-live',
+          'I2V-01',
+          'S2V-01'
+        ],
+        default: 'MiniMax-Hailuo-2.3',
+        description: 'Video generation model. ' +
+                     '"MiniMax-Hailuo-2.3" = recommended for text-to-video and image-to-video. ' +
+                     '"MiniMax-Hailuo-02" = good for first-last frame. ' +
+                     '"S2V-01" = subject reference mode.'
+      },
+      first_frame_image: {
+        type: 'string',
+        description: 'Public URL or data: URL of the first frame image (for Image-to-Video or First-Last mode). ' +
+                     'Formats: JPG, JPEG, PNG, WebP. Size < 20MB. Short side > 300px.'
+      },
+      last_frame_image: {
+        type: 'string',
+        description: 'Public URL or data: URL of the last frame image (for First & Last Frame mode only).'
+      },
+      subject_reference: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            type: { type: 'string', enum: ['character'], description: 'Subject type. Currently only "character" supported.' },
+            image: {
+              type: 'array',
+              items: { type: 'string' },
+              description: 'Array of reference image URLs (usually one image).'
+            }
+          },
+          required: ['type', 'image']
+        },
+        description: 'For Subject-Reference to Video (S2V-01 model). Array of character references.'
+      },
+      prompt_optimizer: {
+        type: 'boolean',
+        default: true,
+        description: 'Automatically optimize the prompt. Default true.'
+      },
+      fast_pretreatment: {
+        type: 'boolean',
+        default: false,
+        description: 'Reduces optimization time when prompt_optimizer is enabled (Hailuo models only).'
+      },
+      duration: {
+        type: 'integer',
+        enum: [6, 10],
+        default: 6,
+        description: 'Video duration in seconds. Available values depend on model and resolution.'
+      },
+      resolution: {
+        type: 'string',
+        enum: ['512P', '720P', '768P', '1080P'],
+        description: 'Video resolution. Options depend on model and duration. ' +
+                     'Example: "768P" or "1080P".'
+      },
+      callback_url: {
+        type: 'string',
+        description: 'Optional callback URL for async status updates.'
+      },
+      max_wait_ms: {
+        type: 'integer',
+        default: 300000,
+        description: 'Maximum wait time for polling (default 5 minutes).'
+      },
+      poll_interval_ms: {
+        type: 'integer',
+        default: 5000,
+        description: 'Polling interval in milliseconds (default 5 seconds).'
+      },
+      extra: {
+        type: 'object',
+        description: 'Additional parameters not yet documented.'
+      }
+    },
+    required: ['prompt']
+  },
+  async (params) => {
+    const result = await minimax.generateVideo(params.prompt, params);
+
+    return JSON.stringify({
+      task_id: result.task_id,
+      file_id: result.file_id,
+      video_url: result.video_url,
+      local_path: result.local_path,
+      video_width: result.video_width,
+      video_height: result.video_height,
+      total_duration_ms: result.duration,
+      raw_responses: result.raw,
+      note: 'Video has been automatically saved to local_path. ' +
+            'The generation was polled until completion. Use max_wait_ms to adjust timeout.'
+    }, null, 2);
+  }
+);
+
+/* ============================================================
+   LOW-LEVEL: CREATE TASK ONLY
+   ============================================================ */
+
+tools.add(
+  'create_video_task',
+  'Create a video generation task without waiting. ' +
+  'Returns a task_id that can be polled manually with query_video_task. ' +
+  'Useful for advanced workflows or when using callbacks.',
+  {
+    type: 'object',
+    properties: {
+      prompt: {
+        type: 'string',
+        description: 'Text description of the video.'
+      },
+      model: {
+        type: 'string',
+        default: 'MiniMax-Hailuo-2.3',
+        description: 'Video model to use.'
+      },
+      first_frame_image: { type: 'string' },
+      last_frame_image: { type: 'string' },
+      subject_reference: { type: 'array' },
+      prompt_optimizer: { type: 'boolean', default: true },
+      duration: { type: 'integer', default: 6 },
+      resolution: { type: 'string' },
+      callback_url: { type: 'string' },
+      extra: { type: 'object' }
+    },
+    required: ['prompt']
+  },
+  async (params) => {
+    const result = await minimax.createVideoGenerationTask(params.prompt, params);
+
+    return JSON.stringify({
+      task_id: result.task_id,
+      duration_ms: result.duration,
+      raw_response: result.raw,
+      note: 'Use query_video_task with this task_id to check status.'
+    }, null, 2);
+  }
+);
+
+/* ============================================================
+   LOW-LEVEL: QUERY TASK STATUS
+   ============================================================ */
+
+tools.add(
+  'query_video_task',
+  'Query the current status of a video generation task. ' +
+  'Returns status (Preparing, Queueing, Processing, Success, Fail) and file_id when ready.',
+  {
+    type: 'object',
+    properties: {
+      task_id: {
+        type: 'string',
+        description: 'The task_id returned by create_video_task or generate_video.'
+      }
+    },
+    required: ['task_id']
+  },
+  async (params) => {
+    const result = await minimax.queryVideoGenerationTask(params.task_id);
+
+    return JSON.stringify({
+      task_id: result.task_id,
+      status: result.status,
+      file_id: result.file_id,
+      video_width: result.video_width,
+      video_height: result.video_height,
+      raw_response: result.raw,
+      note: 'Poll this until status === "Success" to get the file_id.'
+    }, null, 2);
+  }
+);
+
+/* ============================================================
+   LOW-LEVEL: RETRIEVE FILE
+   ============================================================ */
+
+tools.add(
+  'retrieve_video_file',
+  'Retrieve the download URL and metadata for a completed video using its file_id.',
+  {
+    type: 'object',
+    properties: {
+      file_id: {
+        type: 'string',
+        description: 'The file_id returned when a video task reaches Success status.'
+      }
+    },
+    required: ['file_id']
+  },
+  async (params) => {
+    const result = await minimax.retrieveVideoFile(params.file_id);
+
+    return JSON.stringify({
+      file_id: result.file_id,
+      filename: result.filename,
+      download_url: result.download_url,
+      bytes: result.bytes,
+      raw_response: result.raw,
+      note: 'Use save_video_to_local with the download_url to download the file.'
+    }, null, 2);
+  }
+);
+
+/* ============================================================
+   HELPER: DIRECT LOCAL SAVE
+   ============================================================ */
+
+tools.add(
+  'save_video_to_local',
+  'Save a video from a download URL to a local file in .cache/minimax/. ' +
+  'Useful when you already have a download_url from retrieve_video_file.',
+  {
+    type: 'object',
+    properties: {
+      video_url: {
+        type: 'string',
+        description: 'Public download URL of the video (from retrieve_video_file).'
+      },
+      filename_prefix: {
+        type: 'string',
+        default: 'minimax-video',
+        description: 'Prefix for the generated filename.'
+      }
+    },
+    required: ['video_url']
+  },
+  async (params) => {
+    const localPath = await minimax.saveVideoToLocal(
+      params.video_url,
+      params.filename_prefix
+    );
+
+    return JSON.stringify({
+      local_path: localPath,
+      note: 'Video file saved successfully.'
+    });
+  }
+);
+
+export default tools;

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

@@ -0,0 +1,239 @@
+> ## 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.
+
+# Text to Image Generation
+
+> Use this API to generate images from text input.
+
+
+
+## OpenAPI
+
+````yaml /api-reference/image/generation/api/text-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
+        prompt:
+          type: string
+          description: Text description of the image, max length 1500 characters.
+        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: >-
+            Image height (px). Only effective for `image-01`. Must be set
+            together with `width`. Range [512, 2048], must be divisible by 8. If
+            both `width/height` and `aspect_ratio` are provided, `aspect_ratio`
+            takes priority.
+        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 produces
+            reproducible images. If not provided, a random seed is generated for
+            each image.
+        '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 man in a white t-shirt, full-body, standing front view, outdoors,
+          with the Venice Beach sign in the background, Los Angeles. Fashion
+          photography in 90s documentary style, film grain, photorealistic.
+        aspect_ratio: '16:9'
+        response_format: url
+        'n': 3
+        prompt_optimizer: true
+    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
+    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).
+
+````