openclaw-minimax-media 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,361 @@
+# Openclaw MiniMax Media
+
+Openclaw MiniMax Media is an OpenClaw plugin that registers MiniMax-powered tools for media and search workflows. It currently provides image understanding through the MiniMax Coding Plan VLM API, image generation through MiniMax `image-01`, music generation through MiniMax `music-2.6`, video generation through MiniMax `MiniMax-Hailuo-2.3`, text-to-speech through MiniMax `speech-2.8-hd`, and web search through the MiniMax Coding Plan search API. All six tools use the same MiniMax Coding Plan (Token Plan) API key.
+
+## Naming
+
+This package intentionally uses one consistent OpenClaw-facing identity:
+
+| Item | Value |
+| --- | --- |
+| npm package | `openclaw-minimax-media` |
+| installed folder | `openclaw-minimax-media` |
+| plugin ID | `openclaw-minimax-media` |
+| plugin name | `Openclaw MiniMax Media` |
+| tool names | `minimax_image`, `minimax_image_generate`, `minimax_music_generate`, `minimax_video_generate`, `minimax_tts`, `minimax_web_search` |
+
+## Features
+
+- Provides the `minimax_image` OpenClaw tool for image understanding.
+- Provides the `minimax_image_generate` OpenClaw tool for MiniMax `image-01` image generation.
+- Provides the `minimax_music_generate` OpenClaw tool for MiniMax `music-2.6` music generation.
+- Provides the `minimax_video_generate` OpenClaw tool for MiniMax `MiniMax-Hailuo-2.3` video generation.
+- Provides the `minimax_tts` OpenClaw tool for MiniMax `speech-2.8-hd` text-to-speech with `Chinese (Mandarin)_Warm_Girl`.
+- Provides the `minimax_web_search` OpenClaw tool, merged from `openclaw-minimax-web-search`.
+- Uses MiniMax Coding Plan APIs for all six tools (VLM, image generation, music generation, video generation, TTS, and web search).
+- Reads credentials from OpenClaw plugin config, `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`, or `MINIMAX_API_KEY`.
+- Accepts HTTP/HTTPS image URLs, local image paths, `@`-prefixed local paths, and Base64 data URLs.
+- Supports JPEG, PNG, and WebP image inputs.
+- Supports MiniMax image generation with aspect ratio control, up to 9 outputs, and one subject-reference image.
+- Supports MiniMax music generation with lyrics, instrumental mode, duration hints, and MP3 output.
+- Supports MiniMax video generation with text-to-video, one first-frame reference image, duration normalization, and resolution control.
+- Supports MiniMax text-to-speech with MP3 output.
+- Returns normalized web search result objects: title, URL, description, published date, and site name.
+- Marks image analysis and search outputs as untrusted external content.
+- Does not bundle any API key, token, personal account, private path, or internal network address.
+
+## Installation
+
+Use OpenClaw's plugin installer after publishing the package:
+
+```bash
+openclaw plugins install npm:openclaw-minimax-media@0.5.0 --pin
+```
+
+Restart the OpenClaw Gateway after installation if the CLI asks you to do so.
+
+If `openclaw-minimax-web-search` is already installed and enabled, disable or uninstall it before enabling this package. Both plugins register `minimax_web_search`, and duplicate tool registration can conflict.
+
+## Configuration
+
+Configure the plugin under its plugin ID: `openclaw-minimax-media`.
+
+Example OpenClaw config entry:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-minimax-media": {
+        "enabled": true,
+        "config": {
+          "apiKey": "YOUR_MINIMAX_CODING_PLAN_API_KEY",
+          "vlmTimeoutMs": 30000,
+          "imageGenerationTimeoutMs": 180000,
+          "musicGenerationTimeoutMs": 120000,
+          "videoGenerationTimeoutMs": 1200000,
+          "ttsTimeoutMs": 120000,
+          "searchTimeoutMs": 5000
+        }
+      }
+    }
+  }
+}
+```
+
+You can also provide the API key through an environment variable:
+
+```bash
+export MINIMAX_API_KEY="YOUR_MINIMAX_CODING_PLAN_API_KEY"
+# Optional alternatives:
+export MINIMAX_CODE_PLAN_KEY="YOUR_MINIMAX_CODING_PLAN_API_KEY"
+export MINIMAX_CODING_API_KEY="YOUR_MINIMAX_CODING_PLAN_API_KEY"
+# Optional: route media generation through the CN endpoint when supported by your account.
+export MINIMAX_API_HOST="https://api.minimaxi.com"
+```
+
+### Config fields
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `apiKey` | string | none | MiniMax Coding Plan (Token Plan) API key. |
+| `vlmUrl` | string | `https://api.minimaxi.com/v1/coding_plan/vlm` | MiniMax Coding Plan VLM API endpoint. |
+| `vlmModel` | string | `minimax-VL-01` | MiniMax VLM model name. |
+| `vlmTimeoutMs` | number | `30000` | VLM request timeout in milliseconds. Valid range: 1000-120000. |
+| `imageGenerationBaseUrl` | string | `https://api.minimax.io` | MiniMax image generation base URL. The tool appends `/v1/image_generation` unless a full endpoint is provided. |
+| `imageGenerationTimeoutMs` | number | `180000` | Image generation request timeout in milliseconds. Valid range: 1000-600000. |
+| `musicGenerationBaseUrl` | string | `https://api.minimax.io` | MiniMax music generation base URL. The tool appends `/v1/music_generation` unless a full endpoint is provided. |
+| `musicGenerationTimeoutMs` | number | `120000` | Music generation request timeout in milliseconds. Valid range: 1000-600000. |
+| `videoGenerationBaseUrl` | string | `https://api.minimax.io` | MiniMax video generation base URL. The tool appends `/v1/video_generation` unless a full endpoint is provided. |
+| `videoGenerationTimeoutMs` | number | `1200000` | End-to-end video generation operation timeout in milliseconds. Valid range: 1000-1800000. |
+| `ttsBaseUrl` | string | `https://api.minimax.io` | MiniMax T2A API base URL. The tool appends `/v1/t2a_v2` and strips trailing `/anthropic` or `/v1` suffixes. |
+| `ttsTimeoutMs` | number | `120000` | TTS request timeout in milliseconds. Valid range: 1000-600000. |
+| `ttsSpeed` | number | `1` | MiniMax TTS playback speed. Valid range: 0.5-2.0. |
+| `ttsVolume` | number | `1` | MiniMax TTS volume. Valid range: 0.01-10. |
+| `ttsPitch` | number | `0` | MiniMax TTS integer pitch shift. Valid range: -12 to 12. |
+| `searchUrl` | string | `https://api.minimaxi.com/v1/coding_plan/search` | MiniMax Coding Plan search API endpoint. |
+| `searchTimeoutMs` | number | `5000` | Search request timeout in milliseconds. Valid range: 1000-60000. |
+
+## Tool: `minimax_image`
+
+Parameters:
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `prompt` | string | yes | Text instruction describing what to analyze or extract from the image. |
+| `image_source` | string | yes | HTTP/HTTPS image URL, local file path, `@`-prefixed local file path, or Base64 data URL. |
+
+Example tool result shape:
+
+```json
+{
+  "content": "The image shows...",
+  "provider": "openclaw-minimax-media",
+  "model": "minimax-VL-01",
+  "sourceType": "url",
+  "externalContent": {
+    "untrusted": true,
+    "source": "image_analysis",
+    "provider": "minimax"
+  }
+}
+```
+
+## Tool: `minimax_image_generate`
+
+Parameters:
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `action` | `"generate"` or `"list"` | no | Defaults to `generate`. Use `list` to inspect MiniMax image generation capabilities. |
+| `prompt` | string | yes for generate | Image generation prompt. |
+| `image` | string | no | Single subject-reference image path, URL, `@`-prefixed local path, or Base64 data URL. |
+| `images` | string[] | no | Reference images. MiniMax `image-01` supports one reference image; extra entries are ignored. |
+| `aspectRatio` | string | no | Supported values: `1:1`, `16:9`, `4:3`, `3:2`, `2:3`, `3:4`, `9:16`, `21:9`. |
+| `count` | integer | no | Number of images to generate, from 1 to 9. Defaults to 1. |
+| `timeoutMs` | integer | no | Per-call timeout in milliseconds. Valid range: 1000-600000. |
+| `filename` | string | no | Output filename hint in returned image metadata. |
+
+MiniMax `image-01` uses the dedicated image endpoint: `{imageGenerationBaseUrl}/v1/image_generation`. The request body uses `response_format: "base64"` and returns PNG data URLs in the tool result.
+
+Example tool result shape:
+
+```json
+{
+  "provider": "openclaw-minimax-media",
+  "model": "image-01",
+  "count": 1,
+  "images": [
+    {
+      "url": "data:image/png;base64,...",
+      "mimeType": "image/png",
+      "filename": "image-1.png"
+    }
+  ],
+  "externalContent": {
+    "untrusted": true,
+    "source": "image_generation",
+    "provider": "minimax"
+  }
+}
+```
+
+## Tool: `minimax_music_generate`
+
+Parameters:
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `action` | `"generate"` or `"list"` | no | Defaults to `generate`. Use `list` to inspect MiniMax music generation capabilities. |
+| `prompt` | string | yes for generate | Music generation prompt. |
+| `lyrics` | string | no | Optional lyrics text. Cannot be used with `instrumental=true`. |
+| `instrumental` | boolean | no | Request instrumental-only music. |
+| `durationSeconds` | number | no | Target duration hint in seconds. MiniMax receives this as part of the prompt. |
+| `format` | `"mp3"` | no | Output format. MiniMax music generation currently supports MP3 only. |
+| `timeoutMs` | integer | no | Per-call timeout in milliseconds. Valid range: 1000-600000. |
+| `filename` | string | no | Output filename hint in returned track metadata. |
+
+MiniMax `music-2.6` uses the dedicated music endpoint: `{musicGenerationBaseUrl}/v1/music_generation`. The request body uses `output_format: "url"` and MP3 audio settings. The tool accepts both URL and inline audio responses from MiniMax and returns MP3 data URLs in the tool result.
+
+Example tool result shape:
+
+```json
+{
+  "provider": "openclaw-minimax-media",
+  "model": "music-2.6",
+  "count": 1,
+  "tracks": [
+    {
+      "url": "data:audio/mpeg;base64,...",
+      "mimeType": "audio/mpeg",
+      "filename": "track-1.mp3"
+    }
+  ],
+  "lyrics": ["Generated or returned lyrics..."],
+  "externalContent": {
+    "untrusted": true,
+    "source": "music_generation",
+    "provider": "minimax"
+  }
+}
+```
+
+## Tool: `minimax_video_generate`
+
+Parameters:
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `action` | `"generate"` or `"list"` | no | Defaults to `generate`. Use `list` to inspect MiniMax video generation capabilities. |
+| `prompt` | string | yes for generate | Video generation prompt. |
+| `image` | string | no | Single first-frame reference image path, URL, `@`-prefixed local path, or Base64 data URL. |
+| `images` | string[] | no | Reference images. MiniMax video generation supports one first-frame image; extra entries are ignored. |
+| `durationSeconds` | number | no | Target duration. `MiniMax-Hailuo-2.3` supports 6 or 10 seconds; the nearest supported value is used. |
+| `resolution` | `"768P"` or `"1080P"` | no | MiniMax-supported output resolution. |
+| `timeoutMs` | integer | no | End-to-end operation timeout in milliseconds. Valid range: 1000-1800000. |
+| `filename` | string | no | Output filename hint in returned video metadata. |
+
+MiniMax `MiniMax-Hailuo-2.3` uses the dedicated video endpoint: `{videoGenerationBaseUrl}/v1/video_generation`. The initial request returns a `task_id`; the tool polls `/v1/query/video_generation`, then downloads the completed `video_url` or resolves `file_id` through `/v1/files/retrieve`. Returned videos are MP4 data URLs.
+
+Example tool result shape:
+
+```json
+{
+  "provider": "openclaw-minimax-media",
+  "model": "MiniMax-Hailuo-2.3",
+  "count": 1,
+  "videos": [
+    {
+      "url": "data:video/mp4;base64,...",
+      "mimeType": "video/mp4",
+      "filename": "video-1.mp4"
+    }
+  ],
+  "metadata": {
+    "taskId": "example-task-id",
+    "status": "Success"
+  },
+  "externalContent": {
+    "untrusted": true,
+    "source": "video_generation",
+    "provider": "minimax"
+  }
+}
+```
+
+## Tool: `minimax_tts`
+
+Parameters:
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `text` | string | yes | Text to convert to speech. |
+| `timeoutMs` | integer | no | Request timeout in milliseconds. Valid range: 1000-600000. |
+| `filename` | string | no | Output filename hint in returned audio metadata. |
+
+This tool intentionally implements text-to-speech only. It always uses MiniMax `speech-2.8-hd` with voice `Chinese (Mandarin)_Warm_Girl`, calls `{ttsBaseUrl}/v1/t2a_v2`, decodes MiniMax's hex audio payload, and returns MP3 data URLs.
+
+Example tool result shape:
+
+```json
+{
+  "provider": "openclaw-minimax-media",
+  "model": "speech-2.8-hd",
+  "voiceId": "Chinese (Mandarin)_Warm_Girl",
+  "audio": {
+    "url": "data:audio/mpeg;base64,...",
+    "mimeType": "audio/mpeg",
+    "filename": "tts-1.mp3"
+  },
+  "externalContent": {
+    "untrusted": true,
+    "source": "tts",
+    "provider": "minimax"
+  }
+}
+```
+
+## Tool: `minimax_web_search`
+
+Parameters:
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `query` | string | yes | Search query string. Must not be empty. |
+| `count` | integer | no | Number of results to return, from 1 to 10. Defaults to 5. |
+
+Example tool result shape:
+
+```json
+{
+  "query": "OpenClaw AI agent framework",
+  "provider": "openclaw-minimax-media",
+  "count": 3,
+  "results": [
+    {
+      "title": "Example result",
+      "url": "https://example.com/article",
+      "description": "Short snippet...",
+      "published": "2026-01-01 12:00:00",
+      "siteName": "example.com"
+    }
+  ],
+  "externalContent": {
+    "untrusted": true,
+    "source": "web_search",
+    "provider": "minimax"
+  }
+}
+```
+
+## Operational notes and limitations
+
+- This package registers direct OpenClaw tools. It does not register OpenClaw's built-in `imageGenerationProviders`, `musicGenerationProviders`, or `videoGenerationProviders` contracts, so it does not participate in built-in provider fallback routing.
+- Generated images, music, videos, and TTS audio are returned as Base64 data URLs in the tool result. This is simple and npm-friendly, but large videos or long audio can make tool results very large compared with OpenClaw-managed media attachments.
+- Long video generation runs are handled inside one tool call by polling MiniMax. If the host or channel imposes a shorter tool execution timeout, prefer a shorter `timeoutMs` or move this implementation to a provider/background-task integration later.
+- Only JPEG, PNG, and WebP image inputs are accepted for image understanding, image generation references, and video first-frame references.
+
+## Safety and privacy
+
+- Do **not** publish real API keys in this package, README, examples, or OpenClaw config files.
+- This package does not include any bundled credentials.
+- Remote image URLs, search results, and model responses are external, untrusted content; agents should treat them accordingly.
+- Local image paths are read from the machine running OpenClaw. Only use local paths that are intended to be analyzed.
+- Input images are converted to Base64 data URLs before being sent to MiniMax VLM or image generation APIs.
+- Generated images are returned as PNG Base64 data URLs in the tool result.
+- Generated tracks are returned as MP3 Base64 data URLs in the tool result.
+- Generated videos are returned as MP4 Base64 data URLs in the tool result.
+- TTS audio is returned as an MP3 Base64 data URL in the tool result.
+- MiniMax API calls may consume your MiniMax Token Plan quota.
+- Avoid using `minimax_web_search` for sensitive queries, including political, religious, private, credential, or otherwise restricted content.
+
+## Development
+
+```bash
+npm install
+npm test
+npm pack --dry-run
+```
+
+The package publishes only these files:
+
+- `dist/`
+- `openclaw.plugin.json`
+- `README.md`
+- `LICENSE`
+
+Source files, local lockfiles, `node_modules`, backups, generated tarballs, and local workspace paths are excluded from the npm package.
+
+## License
+
+MIT