Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/minimax/README.md

Raw
Rendered preview
minimax

minimax

Generate images, synthesize speech, understand images, resume H3 jobs using existing MiniMax M Plan credentials without replacing Pi's MiniMax chat provider.

Use in Pi

Configure Pi's existing minimax credential with M Plan key from Plan Details, not PAYG API key. Pi ≥1.5.1 supports pi auth login minimax --api-key from an interactive terminal; older Pi versions use /login minimax. Use native image model minimax-media/image-01 through codemode models.getModelOfType("image", "minimax-media", "image-01") + models.generateImages(model, { input: [{ type: "text", text: "A red square" }] }). Images return inline, never automatically persist. Codemode uses default one 512×512 image; its native image binding exposes no provider-options argument. Extension SDK provider options additionally accept n 1–9, width/height 512–2048 divisible by 8, seed 0–2147483647. Prompts accept ≤1500 characters; reference images/editing remain unavailable.

Ask Pi to call minimax_understand_image with prompt + source for explicit M Plan understanding, distinct from normal chat vision. Source accepts absolute local JPEG/PNG/WebP path or public HTTPS URL, ≤8 MiB. Ask Pi to call minimax_speech with text + absolute outputPath for MP3 synthesis using speech-2.8-turbo + verified stock voice English_Graceful_Lady. Text accepts ≤10000 characters; output ≤12 MiB, no overwrite. Voice creation, cloning, other voices remain unverified.

Use minimax_video with action: "submit", unique job, prompt to start MiniMax-H3 text-to-video. Defaults: 4 seconds, 768P, 1:1; supported duration 4–15, resolution 768P | 2K, ratio 21:9 | 16:9 | 4:3 | 1:1 | 3:4 | 9:16. Submission returns persisted task identity immediately, not finished media. Use action: "status" + job for one bounded query; list recovers session-owned jobs after reload. Use retrieve + job + absolute outputPath for completed MP4 ≤128 MiB. Saved MP3 and MP4 paths are clickable file:// links in terminals with hyperlink support; clicking opens your default player. With ffmpeg on PATH, a retrieved video row shows a four-frame preview strip when Pi displays inline images. The preview is display-only: it never reaches the model or codemode, stays under 96 KB per retrieval, and is kept in session history. Without ffmpeg, or if preview generation fails, retrieval still succeeds with the link only. Use cancel + job for queued work only; racing completion can instead delete terminal upstream record. Local abort never guarantees remote cancellation or refunded usage. Unknown completion never triggers automatic resubmission; inspect recorded job before starting another. Jobs belong to originating session + credential identity, not inherited forks or unrelated PiPi sessions. Upstream query covers last seven days; signed download expiry remains unknown. Go has no included H3; Explore/Build document included H3, but account entitlement remains unverified until explicitly authorized operation succeeds.

Call minimax_capabilities for local discovery, credential blockers, H3 approval mode, documented plan differences, explicit unavailable conditional capabilities. Remote retrieval pins validated public DNS addresses, rejects redirects, caps bytes + 30-second download time; HTTP URLs upgrade to HTTPS without downgrade. Downloads never receive API credentials; signed URLs stay out of ordinary status output. Image API responses cap at 32 MiB; image/speech/status requests cap at 120 seconds. No automatic artifact directories or overwrite; choose existing parent directory + new filename.

Image generation, understanding, and speech run without any approval dialog, including noninteractive, codemode, and PiPi use. H3 submit asks in the UI with duration, resolution, catalog estimate, and weekly-only allowance: submit once, allow H3 for the current session, or cancel. Cancel sends nothing; the session allowance lives in memory and resets on every session start. Noninteractive H3 submit needs USER setting or environment approval:

{ "minimax": { "videoApproval": "always" } }

Project settings never approve H3, including trusted projects; invalid values fail closed. Purchased Credits, if ever bought, could be consumed once the included allowance runs out.

After each consuming operation, the extension reads remaining M Plan allowance without consuming it and shows M Plan left 5h … · wk … in the result. It also emits quota:provider-activity so the quota extension refreshes; a failed allowance read never fails the operation. No consuming discovery, quota-based enforcement, automatic retries, PAYG fallback, cross-region fallback. CN routes remain unavailable. Catalog estimates do not establish provider charges, allowance consumption, or Credits usage; missing measurements remain unknown. Native result usage carries catalog estimates for returned image count, understanding requests, provider-reported speech characters, and provider-reported H3 output seconds. Zero token counts mean no reported chat tokens, not free service; video token-equivalent counts remain separate provider measurements. Status/download repetition does not repeat H3 accounting; requested/provider-reported seconds do not establish encoded duration. Cancellation racing terminal record deletion can leave consumed usage unrecoverable; missing usage never establishes a zero charge.

Installation

Reference

Setting names

Setting Environment
minimax.region PI_MINIMAX_REGION
minimax.videoApproval PI_MINIMAX_VIDEO_APPROVAL

Setting values

Setting Default Valid values Purpose
minimax.region "global" "global", "cn" Service region: Only global M Plan routes are established; cn reports unavailable.
minimax.videoApproval "ask" "ask", "always" H3 video approval: USER or env only: ask confirms each H3 submit in the UI (or allows it for the session); always submits without a dialog, including noninteractive use. Project settings never authorize.
<img src="assets/banner.svg" alt="minimax" height="70">

# minimax

Generate images, synthesize speech, understand images, resume H3 jobs using existing MiniMax M Plan credentials without replacing Pi's MiniMax chat provider.

## Use in Pi

Configure Pi's existing `minimax` credential with M Plan key from Plan Details, not PAYG API key.
Pi ≥1.5.1 supports `pi auth login minimax --api-key` from an interactive terminal; older Pi versions use `/login minimax`.
Use native image model `minimax-media/image-01` through codemode `models.getModelOfType("image", "minimax-media", "image-01")` + `models.generateImages(model, { input: [{ type: "text", text: "A red square" }] })`.
Images return inline, never automatically persist.
Codemode uses default one 512×512 image; its native image binding exposes no provider-options argument.
Extension SDK provider options additionally accept `n` 1–9, `width`/`height` 512–2048 divisible by 8, `seed` 0–2147483647.
Prompts accept ≤1500 characters; reference images/editing remain unavailable.

Ask Pi to call `minimax_understand_image` with `prompt` + `source` for explicit M Plan understanding, distinct from normal chat vision.
Source accepts absolute local JPEG/PNG/WebP path or public HTTPS URL, ≤8 MiB.
Ask Pi to call `minimax_speech` with `text` + absolute `outputPath` for MP3 synthesis using `speech-2.8-turbo` + verified stock voice `English_Graceful_Lady`.
Text accepts ≤10000 characters; output ≤12 MiB, no overwrite.
Voice creation, cloning, other voices remain unverified.

Use `minimax_video` with `action: "submit"`, unique `job`, `prompt` to start `MiniMax-H3` text-to-video.
Defaults: 4 seconds, 768P, 1:1; supported duration 4–15, resolution 768P | 2K, ratio 21:9 | 16:9 | 4:3 | 1:1 | 3:4 | 9:16.
Submission returns persisted task identity immediately, not finished media.
Use `action: "status"` + `job` for one bounded query; `list` recovers session-owned jobs after reload.
Use `retrieve` + `job` + absolute `outputPath` for completed MP4 ≤128 MiB.
Saved MP3 and MP4 paths are clickable `file://` links in terminals with hyperlink support; clicking opens your default player.
With `ffmpeg` on `PATH`, a retrieved video row shows a four-frame preview strip when Pi displays inline images.
The preview is display-only: it never reaches the model or codemode, stays under 96 KB per retrieval, and is kept in session history.
Without `ffmpeg`, or if preview generation fails, retrieval still succeeds with the link only.
Use `cancel` + `job` for queued work only; racing completion can instead delete terminal upstream record.
Local abort never guarantees remote cancellation or refunded usage.
Unknown completion never triggers automatic resubmission; inspect recorded job before starting another.
Jobs belong to originating session + credential identity, not inherited forks or unrelated PiPi sessions.
Upstream query covers last seven days; signed download expiry remains unknown.
Go has no included H3; Explore/Build document included H3, but account entitlement remains unverified until explicitly authorized operation succeeds.

Call `minimax_capabilities` for local discovery, credential blockers, H3 approval mode, documented plan differences, explicit unavailable conditional capabilities.
Remote retrieval pins validated public DNS addresses, rejects redirects, caps bytes + 30-second download time; HTTP URLs upgrade to HTTPS without downgrade.
Downloads never receive API credentials; signed URLs stay out of ordinary status output.
Image API responses cap at 32 MiB; image/speech/status requests cap at 120 seconds.
No automatic artifact directories or overwrite; choose existing parent directory + new filename.

Image generation, understanding, and speech run without any approval dialog, including noninteractive, codemode, and PiPi use.
H3 submit asks in the UI with duration, resolution, catalog estimate, and weekly-only allowance: submit once, allow H3 for the current session, or cancel.
Cancel sends nothing; the session allowance lives in memory and resets on every session start.
Noninteractive H3 submit needs USER setting or environment approval:

```json
{ "minimax": { "videoApproval": "always" } }
```

Project settings never approve H3, including trusted projects; invalid values fail closed.
Purchased Credits, if ever bought, could be consumed once the included allowance runs out.

After each consuming operation, the extension reads remaining M Plan allowance without consuming it and shows `M Plan left 5h … · wk …` in the result.
It also emits `quota:provider-activity` so the quota extension refreshes; a failed allowance read never fails the operation.
No consuming discovery, quota-based enforcement, automatic retries, PAYG fallback, cross-region fallback.
CN routes remain unavailable.
Catalog estimates do not establish provider charges, allowance consumption, or Credits usage; missing measurements remain unknown.
Native result usage carries catalog estimates for returned image count, understanding requests, provider-reported speech characters, and provider-reported H3 output seconds.
Zero token counts mean no reported chat tokens, not free service; video token-equivalent counts remain separate provider measurements.
Status/download repetition does not repeat H3 accounting; requested/provider-reported seconds do not establish encoded duration.
Cancellation racing terminal record deletion can leave consumed usage unrecoverable; missing usage never establishes a zero charge.

[Installation](../../README.md#install)

## Reference

<!-- config:start -->
### Setting names

| Setting | Environment |
| --- | --- |
| `minimax.region` | `PI_MINIMAX_REGION` |
| `minimax.videoApproval` | `PI_MINIMAX_VIDEO_APPROVAL` |

#### Setting values

| Setting | Default | Valid values | Purpose |
| --- | --- | --- | --- |
| `minimax.region` | `"global"` | `"global"`, `"cn"` | Service region: Only global M Plan routes are established; cn reports unavailable. |
| `minimax.videoApproval` | `"ask"` | `"ask"`, `"always"` | H3 video approval: USER or env only: ask confirms each H3 submit in the UI (or allows it for the session); always submits without a dialog, including noninteractive use. Project settings never authorize. |
<!-- config:end -->