dsh-minimax-byapi 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to `dsh-minimax-byapi` are recorded here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [semantic versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.1.0
+
+First release. The plugin is renamed and reworked from the previous Grok gateway plugin to talk to the official MiniMax open platform, then corrected against the official API reference (`platform.minimax.cn/docs/api-reference`).
+
+### Added
+
+- Native dsh LLM provider under the route `minimax-byapi`, display name **MiniMax**, serving chat through the official pi-ai adapter.
+- Five connection presets in `connection.plan`: `payg-global`, `payg-cn`, `coding-global`, `coding-cn` and `custom`. Each preset fills the API base URL and the chat protocol — the OpenAI-compatible `/v1` route for pay-as-you-go, the Anthropic-compatible `/anthropic` route for M Plan.
+- Support for both MiniMax key types with one protocol: the pay-as-you-go API key and the M Plan subscription key (`sk-cp-…`) are both sent as `Authorization: Bearer <key>`. The difference is billing and model tier, not the wire format.
+- Model discovery through `GET {root}/v1/models`, merged with the plugin's built-in model constants so media models stay listed even when the endpoint only returns chat models. Models are auto-categorized as chat, image, video, speech, music, research or unknown; only chat models enter the model picker.
+- Built-in chat model metadata for `MiniMax-M3.1-Flash` and `MiniMax-M3` (1,000,000 context, 131,072 recommended output, image input, reasoning-effort levels for M3.1-Flash).
+- Media tools in the `dsh-minimax-media` component: `minimax_generate_image`, `minimax_edit_image`, `minimax_generate_video`, `minimax_list_voices`, `minimax_speak`, `minimax_speak_long`, `minimax_transcribe`, `minimax_generate_music`, `minimax_media_status`, `minimax_media_retry_download`, `minimax_media_list`; plus `minimax_models` and `minimax_quota` in the `minimax-byapi` component. Thirteen tools in total.
+- MiniMax-native media calls: image generation with aspect-ratio and `n` (1–9) control and `subject_reference` for image-to-image, the v2 video endpoint for the MiniMax-H3 family (4–15 s), the v1 video endpoint for the Hailuo family (6 s or 10 s), text-to-speech, and speech-to-text with `asr-1.0`.
+- Durable, session-scoped media tasks: task records survive restarts, downloads are written to a `.part` file and renamed after validation, and a failed download can be retried without regenerating the result, so nothing is billed twice.
+- Settings page with access mode, API address, API key, key verification, timeout, the chat-model table and media-model selection. The API key is written to the dsh credential service under the reference name `MINIMAX_API_KEY`; the configuration keeps only the reference.
+- English and Chinese README, a bilingual settings page, tool result cards and media player that follow the dsh interface language.
+- `minimax_quota` reads the M Plan remaining quota from `GET https://www.{minimax.io|minimax.cn}/v1/token_plan/remains` — the 5-hour and weekly windows with total, remaining, used, percentage and reset time, plus a per-model split when the server returns one. It reports a readable error for a pay-as-you-go key, which the endpoint refuses.
+- Voice tooling: `minimax_list_voices` lists the `voice_id` values an account can use (`system` / `voice_cloning` / `voice_generation` / `all`), and `minimax_speak_long` runs asynchronous long-form speech through `/v1/t2a_async_v2` → `/v1/query/t2a_async_query_v2` → `/v1/files/retrieve`, up to 100,000 characters per call.
+- `reasoning_effort` is now sent explicitly with `supportsReasoningEffort` on the Chat Completions route, and the output cap always uses `max_completion_tokens` (the deprecated `max_tokens` is never sent). Covered by a request-body test.
+- Image parameters: `style_type` / `style_weight` for `image-01-live`, an explicit `width` / `height` pair for `image-01`, and `aigc_watermark` for images and videos. Local validation rejects a style on the wrong model, `21:9` on `image-01-live`, and an unpaired or out-of-range pixel size.
+- Video v2 parameters: `aigc_watermark`, `prompt_expansion_mode` (MiniMax-H3-Max only), the per-model resolution and duration rules, and the ratio rules — text-to-video requires a concrete ratio, image-to-video is fixed to `adaptive`, and `MiniMax-H3-Lite` rejects `adaptive`. The v2 prompt limit is 7000 characters while v1 stays at 2000.
+- A "Text model parameters" section in both READMEs and the parameter table in `VALIDATION.md`, listing what the plugin controls and what the adapter cannot send (`service_tier`, `reasoning_split`, disabling thinking on MiniMax-M3, text `seed`).
+
+### Changed
+
+- The plugin was renamed from `dsh-grok-byapi` to `dsh-minimax-byapi`; the package name, display name (`MiniMax ByAPI`), the two component ids (`minimax-byapi` and `dsh-minimax-media`) and the credential reference (`MINIMAX_API_KEY`) all follow the new provider.
+- The credential reference renamed from `GROK_ALL_API_KEY` to `MINIMAX_API_KEY`.
+- The default access mode is now `coding-cn` with `anthropic-messages`: a fresh install points at `https://api.minimaxi.com/anthropic`, the China M Plan route on the protocol MiniMax recommends. `connection.baseURL` and `connection.api` follow that default. Both China hosts answer identically (`api.minimaxi.com` and `api.minimax.cn`); the preset uses `api.minimaxi.com`, and switching to the other spelling is a `custom` address.
+- The settings page puts the API protocol selector to the left of the address field, and changing it rewrites the official address path.
+- Image width/height versus aspect ratio: the official rule is that `aspect_ratio` wins when both are given; the plugin instead honours the explicit pixel size and stops sending `aspect_ratio`, so an explicit value is never silently dropped. Documented in both READMEs.
+- The media data directory is now `$DSH_HOME/plugins/dsh-minimax-byapi`.
+- Documentation was rewritten for MiniMax: bilingual README, `SECURITY.md`, `VALIDATION.md` and the API research notes under `docs/`.
+
+### Fixed
+
+- **Every chat request failed with "pi-ai request header preparation failed".** The plugin applies the official pi-ai adapter to a scope of its own, and that scope did not answer the host's request-header seam: pi-ai `0.2.2-rc.1` composes every provider route's headers through `ctx.waterfall("llm-pi-ai/request-headers", …)`. The route therefore registered and the models were listed, but the first request threw a `TypeError` before any byte reached MiniMax. The scope now delegates that seam to the host context and forwards any other member the official adapter captures, so a later pi-ai release cannot break the route the same way again.
+- **The declared peer ranges rejected the host's own versions.** `package.json` pinned `@deepseek-ai/cordis` to `~4.0.4`, `@deepseek-ai/schemastery` to `~3.18.4` and the `dsh-*` peers to `>=0.2.1-0 <0.3.0`, while the host ships cordis `4.1.0`, schemastery `3.19.0` and the `0.2.2-rc.1` line. The `dsh-*` range rejected the host outright: npm only lets a prerelease satisfy a range whose comparators mention that same `[major, minor, patch]` tuple. The ranges now match the sibling plugins — `>=4.0.4 <5.0.0`, `>=3.18.4 <4.0.0` and `>=0.2.1-0 <0.3.0-0 || >=0.2.2-0 <0.3.0-0` — and the development tree resolves to the host's versions, so the test suite exercises the same pi-ai the host runs.
+- **The API address now follows the protocol.** On the official hosts `/v1` and `/anthropic` are paired with the OpenAI-compatible and Anthropic-compatible protocols; switching the protocol rewrites the path and re-derives the access mode from the address-plus-protocol pair, so the settings page can no longer produce "`/v1` with `anthropic-messages`". Custom endpoints are left untouched.
+- **Text parameters on the Anthropic-compatible route.** pi-ai's default thinking form (`type: "enabled"` with `budget_tokens`) is not accepted by MiniMax; the plugin now forces adaptive thinking, so the request carries `thinking: { type: "adaptive" }` and `output_config.effort` instead. Verified by a request-body test.
+- **Missing H3 video variants.** `MiniMax-H3-Highspeed` and `MiniMax-H3-Lite` were absent from the built-in catalog, so they could not be selected even though the v2 endpoint serves them.
+- **`image-01-live` was described as image-to-image only.** The official OpenAPI allows it for text-to-image and gives it a `style` object; the note is corrected and the style parameters are exposed.
+
+### Removed
+
+- The Grok-specific gateway integration, the Grok Imagine media component and every `grok_*` tool.
+- The video-editing and video-extension tools of the previous plugin.
+- The Grok demo assets under `docs/assets/`, the screenshot manifest and the old planning documents.
+
+### Known limitations
+
+- Music generation is retired upstream: MiniMax closed the music API to new users on 2026-08-20 and lists all music models as retired. The tool stays for existing paying accounts only.
+- Realtime voice conversation (audio-in / audio-out), voice cloning, voice design and MiniMax's server-side web search tool are not provided.
+- Video results are snapshots: the result card does not refresh itself, the finished file has to be fetched with `minimax_media_status`.
+- An end-to-end chat turn with a real MiniMax key has been performed (2026-11-06); media generation has not — see `VALIDATION.md`.
+
+[Keep a Changelog]: https://keepachangelog.com/en/1.1.0/
+[semantic versioning]: https://semver.org/spec/v2.0.0.html

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NingYuanLee
+
+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

@@ -1,3 +1,302 @@
-# Temporary Holding Version
+# dsh-minimax-byapi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Native MiniMax for DeepSeek Harness: chat with a subscription (M Plan) key or a pay-as-you-go API key, plus image, video, speech, speech-to-text and music tools over the official MiniMax API.
+
+[![CI](https://github.com/NingYuanLee/dsh-minimax-byapi/actions/workflows/ci.yml/badge.svg)](https://github.com/NingYuanLee/dsh-minimax-byapi/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) [![Node >=22.19](https://img.shields.io/badge/node-%3E%3D22.19.0-339933.svg)](#compatibility) [![dsh 0.2.x](https://img.shields.io/badge/dsh-0.2.x-blue.svg)](#compatibility) [![topic: dsh-plugin](https://img.shields.io/badge/topic-dsh--plugin-6f42c1.svg)](https://github.com/topics/dsh-plugin)
+
+English | [中文](README.zh.md)
+
+> **Published on npm.** `dsh plugin add dsh-minimax-byapi` installs the released package; a git clone or a local checkout works too — see [Install](#install).
+
+One plugin, one MiniMax connection. Chat models appear in the model picker; image, video, speech and music models stay out of it and are used through tools instead. Any chat model — MiniMax or another provider — can call those tools. The plugin talks to the official MiniMax open platform, keeps the API key in the dsh credential service, and saves generated media locally. It is not an OAuth client, does not provide an account or quota, and does not read any MiniMax CLI token.
+
+## Features
+
+| Area | Current scope |
+| --- | --- |
+| Chat provider | Registers a native dsh LLM provider: route `minimax-byapi`, display name **MiniMax**. Streaming text and tool calls go through the official pi-ai adapter, over either the OpenAI-compatible or the Anthropic-compatible route. |
+| Model catalog | `GET {root}/v1/models` discovery, merged with the plugin's built-in model constants, auto-categorized as chat, image, video, speech, music, research, or unknown. Only chat models enter the picker. Per-model overrides are available. |
+| Connection presets | Five access modes: pay-as-you-go (international / China) and M Plan subscription (international / China), plus a custom endpoint. The preset fills the base URL and the chat protocol. |
+| Settings page | Access mode, API address, API key, verification, timeout, the chat-model table (the picker's source of truth), and media-model selection. Copy follows the dsh language (English or Chinese). |
+| Durable media tasks | Task records are per session and survive restarts. Downloads write `.part` files and are renamed after validation. A failed download can be retried without regenerating, so nothing is billed twice. |
+| Results in chat | Tool result cards, file preview, and a sidebar player for MP4, MP3 and WAV. Tool cards and the player follow the dsh language. |
+
+The plugin registers two components: `minimax-byapi` (chat, model catalog, settings page) and `dsh-minimax-media` (media tools). Together they register 13 tools:
+
+| Tool | What it does |
+| --- | --- |
+| `minimax_models` | Refreshes the catalog and returns models grouped by capability. Optional `verify_key` checks address and key with one `GET /v1/models`. |
+| `minimax_quota` | Reads the M Plan remaining quota and reset times (5-hour and weekly windows). Subscription key only — a pay-as-you-go key is refused. |
+| `minimax_generate_image` | Text to image: `prompt`, optional `model`, aspect ratio, `n` (1–9, default 1), style settings for `image-01-live`. |
+| `minimax_edit_image` | Image to image: `prompt` plus a reference image (`subject_reference`). |
+| `minimax_generate_video` | Text to video. V2 models (MiniMax-H3 family) run 4–15 s; V1 models (Hailuo family) run 6 s or 10 s. |
+| `minimax_list_voices` | Lists the `voice_id` values this account can use (`system` / `voice_cloning` / `voice_generation` / `all`). |
+| `minimax_speak` | Synchronous text to speech: `text` up to 10000 characters, optional `model`, `voice_id`, speed, volume, pitch, emotion and format. |
+| `minimax_speak_long` | Asynchronous long-form speech: `text` up to 100000 characters, returns a task id to fetch with `minimax_media_status`. |
+| `minimax_transcribe` | Speech to text: uploads an audio file and returns the transcript. |
+| `minimax_generate_music` | Text to music. Retired by MiniMax — see [Music](#music-is-retired). |
+| `minimax_media_list` | Lists media tasks created in the current session. |
+| `minimax_media_status` | Checks a task and downloads the result when ready: `task_id`. |
+| `minimax_media_retry_download` | Retries a failed download without regenerating: `task_id`. |
+
+Not provided: realtime voice conversation (audio-in / audio-out), voice cloning, voice design, MiniMax's server-side web search tool, and a live task dashboard. Video jobs are polled in-process after submit, but the result card is a snapshot and does not refresh itself — call `minimax_media_status` to fetch the finished file. Model classification is rule-based, not a guarantee.
+
+## Compatibility
+
+| Component | Requirement | Verified |
+| --- | --- | --- |
+| dsh | `>=0.2.1-rc.2 <0.3.0-0` via `engines.dsh` | `0.2.2-rc.1` in an isolated Web profile: install, load, both components running, settings page rendered. Chat and media calls still need a real key — see [VALIDATION.md](VALIDATION.md) |
+| Node.js | `>=22.19.0` | CI runs Node 22.19 and 24 on Linux and Windows |
+| MiniMax | Official open platform, international (`api.minimax.io`) or China (`api.minimaxi.com` / `api.minimax.cn`) | Documented endpoints only; no live call with a real key yet |
+| Other dsh 0.2.x | Inside the `engines.dsh` range | Not individually verified |
+
+`engines.dsh` is the compatibility gate; `peerDependencies` pin the SDK packages the source uses but do not decide compatibility, so rerun the integration tests after a dsh upgrade.
+
+## Connection and the two kinds of key
+
+MiniMax issues two kinds of credential, and the plugin treats them the same way on the wire:
+
+| | Pay-as-you-go API key | M Plan subscription key |
+| --- | --- | --- |
+| Prefix | standard key | `sk-cp-…` |
+| Header | `Authorization: Bearer <key>` | **Identical** — `Authorization: Bearer sk-cp-…` |
+| Hosts | same hosts | same hosts |
+| Billing | deducts account balance | deducts M Plan quota, then credits, then balance |
+| Model tiers | all available models | plan tier decides which models you may call |
+
+Both key types speak the same protocol; only the billing source and the available model tiers differ. The plugin stores the key in the dsh credential service under the reference name `MINIMAX_API_KEY` and never writes it into the configuration.
+
+Both China hosts answer: `api.minimaxi.com` (the preset default) and `api.minimax.cn` (the host the current CN OpenAPI specs list). They behave identically for chat, media and quota; switch to `custom` if you need the other spelling.
+
+### Access modes
+
+`connection.plan` fills the base URL and the chat protocol:
+
+| Plan | Base URL | Chat protocol |
+| --- | --- | --- |
+| `payg-global` — pay-as-you-go, international | `https://api.minimax.io/v1` | `openai-completions` |
+| `payg-cn` — pay-as-you-go, China | `https://api.minimaxi.com/v1` | `openai-completions` |
+| `coding-global` — M Plan, international | `https://api.minimax.io/anthropic` | `anthropic-messages` |
+| `coding-cn` — M Plan, China | `https://api.minimaxi.com/anthropic` | `anthropic-messages` |
+| `custom` — bring your own endpoint | empty | `openai-completions` |
+
+On the official hosts the address and the protocol are paired: `/v1` speaks OpenAI-compatible, `/anthropic` speaks Anthropic-compatible. Changing the protocol in the settings page rewrites the path for you, and changing an access preset fills both. Custom endpoints are never rewritten.
+
+The settings page defaults to **`coding-cn` with `anthropic-messages`**, so a fresh install points at `https://api.minimaxi.com/anthropic` — the China M Plan route on MiniMax's recommended protocol.
+
+**MiniMax recommends the Anthropic-compatible route** (the docs label it "recommended" and the SDK examples lead with it). It serves the same two models with the same bearer key, and it is the only route where the thinking depth travels as `output_config.effort`. Use `coding-global` / `coding-cn` if you want that default; both key types work there.
+
+### M Plan quota
+
+`minimax_quota` calls `GET https://www.minimax.io/v1/token_plan/remains` (China: `https://www.minimax.cn/v1/token_plan/remains`) and returns the remaining and used quota with reset times for the 5-hour rolling window and the weekly window, plus a per-model split when the server provides one.
+
+- **Subscription key only.** A pay-as-you-go key is refused by the service; the tool reports that instead of failing silently.
+- Text, image, audio and other non-video capabilities are limited by both windows; video models are limited by the weekly window only, and unused quota does not carry over.
+- The response field names are not documented upstream: `current_*_usage_count` is reported by MiniMax issue trackers as returning *remaining*, not used. The plugin reads it as remaining and falls back to treating it as used when the number exceeds the total. Treat the MiniMax console usage page as authoritative.
+- The quota is read on demand, never polled or cached.
+
+## Install
+
+**From npm (recommended):**
+
+```powershell
+dsh --profile minimax-test --from-default-profile web --dump-config
+dsh plugin --profile minimax-test add dsh-minimax-byapi
+```
+
+**From git:**
+
+```powershell
+dsh --profile minimax-test --from-default-profile web --dump-config
+dsh plugin --profile minimax-test add "git+https://github.com/NingYuanLee/dsh-minimax-byapi.git"
+```
+
+**From a local checkout (development):**
+
+```powershell
+git clone https://github.com/NingYuanLee/dsh-minimax-byapi.git
+cd dsh-minimax-byapi
+npm install --ignore-scripts
+dsh --profile minimax-test --from-default-profile web --dump-config
+dsh plugin --profile minimax-test add "$PWD"   # bash/zsh: "$(pwd)"
+```
+
+`--dump-config` creates the profile from your default profile and prints the merged configuration without starting a server. `dsh plugin add` records the bundle in that profile — no manual YAML edit. The package has no `prepare` or `postinstall` script, so installation runs no build code and needs no `allowBuilds` entry.
+
+Start dsh with that profile:
+
+```powershell
+dsh --profile minimax-test --no-open
+```
+
+Keep the plugin in a dedicated profile until you are satisfied; this keeps the provider, tools and settings out of your daily environment. For a fully isolated trial, point `DSH_HOME` at a scratch directory.
+
+## Update and uninstall
+
+Updating a git install means removing it and adding the new commit; local installs update with `git pull` and `npm install --ignore-scripts`; an npm install picks up the new version when you remove and re-add the plugin. Restart dsh afterwards.
+
+```powershell
+dsh plugin --profile minimax-test remove dsh-minimax-byapi
+```
+
+Removing the plugin takes its layers out of the profile: the provider, the 13 tools and the settings page are gone. Generated media and task records are **not** deleted, and the credential is **not** removed either. Delete the data directory yourself if you want the files gone:
+
+```powershell
+Remove-Item -Recurse -Force "$env:DSH_HOME\plugins\dsh-minimax-byapi"
+```
+
+Delete the credential in dsh if you no longer need it.
+
+## Configuration
+
+Use the plugin settings page for normal setup. Manual configuration in the profile's `cordis.patch.yml` is possible but optional:
+
+```yaml
+- id: minimax-byapi
+  name: dsh-minimax-byapi
+  config:
+    connection:
+      plan: coding-cn
+      baseURL: https://api.minimaxi.com/anthropic
+      api: anthropic-messages
+      apiKeyEnv: MINIMAX_API_KEY
+      verify: true
+      timeoutMs: 60000
+    media:
+      imageModel: image-01
+      videoModel: MiniMax-H3
+      speechModel: speech-2.8-hd
+      musicModel: ''
+      dataDir: ''
+```
+
+| Key | Default | Notes |
+| --- | --- | --- |
+| `connection.plan` | `coding-cn` | Access mode: `payg-global`, `payg-cn`, `coding-global`, `coding-cn`, `custom`. Fills `baseURL` and `api`. The default is the China M Plan route on the recommended Anthropic-compatible protocol. |
+| `connection.baseURL` | `https://api.minimaxi.com/anthropic` | API address. Non-local addresses must be HTTPS; the path is normalized to `/v1` or `/anthropic`. |
+| `connection.apiKey` | empty | Direct key override for local testing; takes precedence over the credential. Leave empty in normal use. |
+| `connection.apiKeyEnv` | `MINIMAX_API_KEY` | Credential reference name in the dsh credential service. |
+| `connection.api` | `anthropic-messages` | Chat protocol: `openai-completions`, `openai-responses` or `anthropic-messages`. |
+| `connection.verify` | `true` | Verify `GET {root}/v1/models` with the saved key when settings are saved. |
+| `connection.timeoutMs` | `60000` | Request timeout in milliseconds (1000–600000). |
+| `media.imageModel` | empty | Image model used when a call omits `model`. |
+| `media.videoModel` | empty | Video model used when a call omits `model`. |
+| `media.speechModel` | empty | TTS model used when a call omits `model`. |
+| `media.musicModel` | empty | Music model used when a call omits `model`. Retired upstream; only existing paying accounts can call it. |
+| `media.dataDir` | empty | Media output directory; empty means `$DSH_HOME/plugins/dsh-minimax-byapi`. |
+| `modelOverrides` | `[]` | Per-model overrides written by the settings page: category, display name, image support, context window, max output, reasoning efforts. Applied on the next refresh. |
+
+`connection`, `media` and `modelOverrides` are volatile sections: after saving, dsh reloads the plugin layer and the model catalog is discovered again.
+
+The settings page writes the API key into the dsh credential service under the reference name above; the configuration keeps only the reference. Do not hand-write a key into YAML.
+
+## Capabilities
+
+### Chat models
+
+| Model | Context | Recommended output | Image input | Thinking |
+| --- | --- | --- | --- | --- |
+| `MiniMax-M3.1-Flash` | 1,000,000 | 131,072 | yes | Always on; depth `low` / `medium` / `high` / `xhigh` / `max` |
+| `MiniMax-M3` | 1,000,000 | 131,072 | yes | Adaptive; no effort dial |
+
+Retired and no longer callable: `MiniMax-M2`, `M2.1`, `M2.5`, `M2.7`, `M2.7-highspeed`, `M1`, `Text-01`, `VL-01` and `abab6.5`. M Plan users are routed to `MiniMax-M3.1-Flash` automatically.
+
+### Text model parameters
+
+The plugin maps MiniMax's text parameters onto the dsh surfaces that own them. Parameters are per request, so they live in dsh's model picker and the plugin settings page's model table, not in a separate form:
+
+| MiniMax parameter | What the plugin does | Where you control it |
+| --- | --- | --- |
+| `max_completion_tokens` (Chat Completions) / `max_tokens` (Anthropic) / `max_output_tokens` (Responses) | Sends the request's output cap under the field that protocol expects — `max_tokens` is never sent, it is deprecated upstream | dsh picks the cap per call; the model table's max-output column is the catalog default (131,072 recommended, 524,288 hard cap) |
+| `reasoning_effort` (Chat Completions) | Sent as `reasoning_effort` with `low` / `medium` / `high` / `xhigh` / `max`; nothing is sent when no level is chosen, so the server keeps its default (`max`) | Reasoning level in the model picker; the levels on offer come from the model table's reasoning column |
+| `output_config.effort` (Anthropic-compatible) | Sent as `output_config.effort` with the same five levels | Same reasoning level |
+| `thinking` | Only `adaptive` is ever sent. On the Anthropic route the plugin forces adaptive thinking, because pi-ai's default budget form (`type: "enabled"`, `budget_tokens`) is not accepted by MiniMax | Implicit: `MiniMax-M3.1-Flash` always thinks; `MiniMax-M3` thinks when a level is selected, otherwise the server default stands |
+| `reasoning_content` | Parsed as the model's thinking channel; no switch is sent (`reasoning_split` defaults to the split form) | Read-only |
+| `temperature` / `top_p` | Not sent as user knobs; MiniMax ignores them anyway (fixed at 1 and 0.95) | Not available — upstream ignores the value |
+| `service_tier`, `reasoning_split`, `seed` for text | Not exposed: the adapter has no field for them | Not available |
+
+Two route differences worth knowing: `MiniMax-M3` defaults to adaptive thinking on the OpenAI-compatible route but to no thinking on the Anthropic-compatible route, and `MiniMax-M3.1-Flash` rejects `thinking: disabled` on both. The plugin therefore never sends a disable request.
+
+The catalog is the merge of `GET {root}/v1/models` and the plugin's built-in constants, so the media models below stay listed even when the discovery endpoint only returns chat models. The settings page's model table is what the picker shows — delete a row and save to hide that model.
+
+### Media models
+
+| Capability | Models |
+| --- | --- |
+| Image | `image-01` (text and image to image), `image-01-live` (same, plus style settings) |
+| Video (v2 endpoint) | `MiniMax-H3` (768P / 2K, 4–15 s), `MiniMax-H3-Highspeed` (480P / 768P, 4–15 s), `MiniMax-H3-Lite` (480P / 768P, 4–15 s, no `adaptive` ratio), `MiniMax-H3-Max` (480P / 768P, 5–15 s) |
+| Video (v1 endpoint) | `MiniMax-Hailuo-2.3`, `MiniMax-Hailuo-2.3-Fast` (image to video only), `MiniMax-Hailuo-02` — 6 s or 10 s, 512P / 720P / 768P / 1080P |
+| Speech | `speech-2.8-hd`, `speech-2.8-turbo`, `speech-2.6-hd`, `speech-2.6-turbo`, `speech-02-hd`, `speech-02-turbo` |
+| Speech to text | `asr-1.0` |
+| Music | `music-3.0`, `music-2.6`, `music-cover` — retired, see below |
+
+Each media picker in the settings page shows a one-line description of the currently selected model, and the options carry the same text as a tooltip. Image generation accepts an aspect ratio of `1:1`, `16:9`, `4:3`, `3:2`, `2:3`, `3:4`, `9:16` or `21:9` — `21:9` is `image-01` only — a prompt of at most 1500 characters and `n` between 1 and 9. `image-01` also accepts an explicit `width`/`height` pair (512–2048 px, multiples of 8, both required); when both are given the plugin honours the explicit pixel size and does not send `aspect_ratio` (upstream would otherwise ignore `width`/`height`). `image-01-live` additionally accepts a `style` object (`style_type` 漫画 / 元气 / 中世纪 / 水彩, `style_weight` in (0, 1]). Image-to-image passes the reference image as `subject_reference` (a `character` reference: a public URL or a `data:image/jpeg;base64,…` Data URL, JPG/JPEG/PNG under 10 MB).
+
+Video generation is asynchronous in three steps: create the task, query the task, then download the file. The plugin keeps the task id, so `minimax_media_status` can fetch the finished clip without submitting a new one.
+
+### Music is retired
+
+MiniMax has retired the music models, and since **2026-08-20** the music API is closed to new users — only existing paying accounts can still call it. The `minimax_generate_music` tool and the `media.musicModel` setting remain in place for those accounts, but a new account will get an error from the server. Treat music as a legacy capability, not as something to plan around.
+
+## Permissions and privacy
+
+- **Network:** only the MiniMax endpoint you configure. Discovery calls `GET {root}/v1/models`, chat uses the configured route, and the media tools call the image, video, speech, speech-to-text and music endpoints on the same host. No telemetry, no analytics, no third-party service.
+- **Credentials:** the key lives in the dsh credential service under the reference name `MINIMAX_API_KEY`; it is not written to YAML, to logs, to task records or to the repository. Media download requests are sent to MiniMax's own file host and carry no separate credential.
+- **Files:** generated media goes to `$DSH_HOME/plugins/dsh-minimax-byapi` (or `media.dataDir`). Task records may contain time-limited upstream URLs; treat them as private.
+- **Data leaves your machine:** prompts, the reference images you attach, the audio you upload for transcription and the text you synthesize are sent to MiniMax to be processed, exactly as you send them in the chat prompt. The plugin does not filter, redact or re-host that content.
+- **Not done by this plugin:** reading or reusing a MiniMax CLI token, installing or running other plugins, fetching runtime dependencies at install time, calling the server-side web search tool, voice cloning or voice design.
+
+Installing any dsh plugin runs third-party code with your user permissions, and tool approvals do not sandbox plugin code — review the source before installing. Please report security issues through [SECURITY.md](SECURITY.md).
+
+## Usage
+
+- **Chat:** choose **MiniMax** in the model picker. Only chat models are listed; the settings page's model table is what the picker shows, so delete a row and save to hide that model.
+- **Images:** one call generates and saves; inline the result with an absolute local path — `![alt](<D:/path/result-1.png>)`. dsh Web serves it through `/api/file`; the limit is 20 MiB per file.
+- **Video:** submits a job. Call `minimax_media_status` with the returned `task_id` until the result is saved or the task failed; the status card does not refresh by itself. Do not resubmit a job whose submission status is unknown — that would be billed twice.
+- **Speech:** `minimax_speak` writes an audio file for text up to 10000 characters; `minimax_speak_long` submits an asynchronous job for long text and returns a task id to fetch with `minimax_media_status`; `minimax_list_voices` returns the `voice_id` values to pass to either. `minimax_transcribe` uploads a local audio file and returns the transcript as text.
+- **Display:** video and audio appear in the tool result card player. Do not inline them with Markdown image syntax — the chat does not render them and shows a broken image instead.
+
+## Troubleshooting
+
+Installation is successful when all four checks pass:
+
+1. `dsh --profile minimax-test --dump-config` lists the `minimax-byapi` layer.
+2. The Plugins page shows this plugin with both components (`minimax-byapi` and `dsh-minimax-media`) running.
+3. `minimax_models` returns categorized model IDs.
+4. After `dsh plugin --profile minimax-test remove dsh-minimax-byapi`, the layers and components are gone.
+
+| Symptom | Fix |
+| --- | --- |
+| `dsh plugin add` fails or reports 404 | Use the git or local-checkout form above; that path does not depend on the npm registry. |
+| Plugin is listed but does not load | Your dsh is outside `>=0.2.1-rc.2 <0.3.0-0`. Upgrade to a 0.2.x build. |
+| 401 or 403 in settings | Wrong key or base URL. Re-save the key and check the address preset (`api.minimax.io` vs `api.minimaxi.com`). |
+| "该地址没有开放模型列表接口" | That address does not expose `GET /v1/models`; the self-check is skipped and the built-in model constants are used. |
+| Connection refused or timeout | The endpoint is unreachable, or the account has no balance left. `timeoutMs` caps each request. |
+| No MiniMax models in the picker | `/v1/models` returned nothing classified as chat; refresh with `minimax_models` and add overrides. |
+| Model not discovered or wrong category | Refresh `minimax_models`, then correct the category in the settings page. |
+| Media call fails while chat works | The account does not have access to that model or capability — a music call on a new account fails this way by design. |
+| Video stays generating | Query `minimax_media_status`; do not resubmit a task whose submission status is unknown. |
+| Download failed but the task is done | Call `minimax_media_retry_download`; it retries the download only and never regenerates. |
+
+More measured behavior and limits: [VALIDATION.md](VALIDATION.md).
+
+## Development and testing
+
+```bash
+npm install --ignore-scripts
+npm test             # automated tests
+npm run check        # syntax checks for the source files
+npm run build        # rebuilds lib/client.js from src/client.js
+npm pack --dry-run
+```
+
+CI (`.github/workflows/ci.yml`) runs on Linux and Windows with Node 22.19 and 24: install, tests, syntax checks, build, a check that `lib/client.js` matches the build output, and a pack dry run. Pushing a `v*` tag runs `.github/workflows/release.yml`, which verifies that the tag matches `package.json`, repeats the checks, attaches the packed tarball to a GitHub Release, and publishes to npm only if an `NPM_TOKEN` secret is configured.
+
+Further reading: [docs/connection-and-keys.md](docs/connection-and-keys.md) for the access modes, key types and model status; [docs/media-workflow.md](docs/media-workflow.md) for the media task lifecycle; [docs/minimax-api-notes.md](docs/minimax-api-notes.md) for the upstream API research this plugin is built on. These pages live in the repository only — `docs/` is not part of the published package.
+
+## Community, license and disclaimer
+
+- Bugs and feature requests: [Issues](https://github.com/NingYuanLee/dsh-minimax-byapi/issues) (bug report and feature request templates are provided).
+- Security: [SECURITY.md](SECURITY.md) — please use GitHub's private vulnerability reporting.
+- License: [MIT](LICENSE). Copyright (c) 2026 NingYuanLee.
+- Repository: <https://github.com/NingYuanLee/dsh-minimax-byapi>. This is a community plugin project, not an official DeepSeek or MiniMax product. "ByAPI" means the plugin reaches MiniMax through the official API with your own key; it does not implement every MiniMax product feature.