@mrgoonie/multix 0.0.6 → 0.0.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/CHANGELOG.md +36 -0
  2. package/README.md +77 -3
  3. package/dist/cli.js +1109 -253
  4. package/package.json +2 -2
  5. package/skill/SKILL.md +144 -101
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@mrgoonie/multix",
3
- "version": "0.0.6",
4
- "description": "AI multimodal CLI — Gemini (incl. Flash TTS), MiniMax, OpenRouter, Leonardo, BytePlus, ffmpeg, ImageMagick, doc-to-md",
3
+ "version": "0.0.8",
4
+ "description": "AI multimodal CLI — Gemini (incl. Flash TTS), MiniMax, OpenRouter, Leonardo, BytePlus, ElevenLabs, ffmpeg, ImageMagick, doc-to-md",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "multix": "./dist/cli.js"
package/skill/SKILL.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: multix
3
- description: AI multimodal CLI — Gemini/MiniMax/OpenRouter image & video generation, ffmpeg/ImageMagick media optimization, document-to-Markdown conversion via Gemini Files API.
4
- version: 0.0.1
3
+ description: AI multimodal CLI — generate and edit images (Gemini Nano Banana, Imagen, MiniMax, OpenRouter, Leonardo, BytePlus Seedream), generate video (Veo, Hailuo, Seedance, Leonardo), TTS/music (Gemini Flash TTS, MiniMax, ElevenLabs), 3D models (Hyper3D), analyze/transcribe media, convert documents to Markdown, optimize media via ffmpeg/ImageMagick. Use whenever the user wants to create, edit, or transform images/video/audio/documents from a CLI, mentions any of: image-to-image, i2i, image edit, watercolor/cyberpunk style transfer, reference image, OpenRouter, Nano Banana, Flux, Seedream, Veo, Hailuo, ElevenLabs voice cloning, or asks for batch media optimization.
4
+ version: 0.0.7
5
5
  ---
6
6
 
7
7
  # multix — AI Multimodal CLI
@@ -9,148 +9,191 @@ version: 0.0.1
9
9
  ## When to use
10
10
 
11
11
  Activate this skill when the user asks to:
12
- - Generate, analyze, or describe images or video
13
- - Transcribe audio or video files
14
- - Extract structured data from documents (PDF, DOCX, images)
15
- - Convert documents to Markdown
16
- - Optimize or split video/audio/image files
17
- - Generate speech (TTS) or music
12
+ - Generate images from a text prompt (any provider)
13
+ - **Edit/transform an existing image with a prompt** (image-to-image, alias `i2i`)
14
+ - Generate video from text or from a reference image (image-to-video, alias `i2v`)
15
+ - Generate or clone a voice, run STT, generate music or sound effects
16
+ - Generate 3D models (Hyper3D / Hitem3d)
17
+ - Analyze, transcribe, or extract structured data from media/docs
18
+ - Convert PDFs / DOCX / images to Markdown
19
+ - Optimize, resize, batch-convert, or split video/audio/image files
18
20
 
19
- ## Required env (at least one)
21
+ ## Required env (set at least one provider key)
20
22
 
21
23
  ```
22
- GEMINI_API_KEY # Google AI Studio — required for analyze/transcribe/doc/generate
23
- OPENROUTER_API_KEY # OpenRouter — alternative image generation
24
- MINIMAX_API_KEY # MiniMax — image, video, speech, music generation
24
+ GEMINI_API_KEY # Google AI Studio
25
+ OPENROUTER_API_KEY # OpenRouter (multi-model gateway)
26
+ MINIMAX_API_KEY # MiniMax (image/video/speech/music)
27
+ LEONARDO_API_KEY # Leonardo.Ai (image/video/upscale)
28
+ BYTEPLUS_API_KEY # BytePlus / Volcengine ARK (Seedream/Seedance/Hyper3D)
29
+ ELEVENLABS_API_KEY # ElevenLabs (TTS, cloning, STT, music, dubbing)
25
30
  ```
26
31
 
27
- ## Installation
32
+ Priority: `process.env` > `cwd/.env` > `~/.multix/.env`.
33
+
34
+ ## Install + diagnostics
28
35
 
29
36
  ```bash
30
- npm install -g multix
31
- # or run without installing:
32
- npx multix --help
37
+ npm install -g @mrgoonie/multix
38
+ multix check [--verbose]
33
39
  ```
34
40
 
35
- ## Diagnostics
41
+ ## Image generation
36
42
 
37
- ```bash
38
- multix check # verify keys, tooling, Gemini connectivity
39
- multix check --verbose # show install hints
40
- ```
43
+ | Provider | Command | Notes |
44
+ |---|---|---|
45
+ | Gemini | `multix gemini generate --prompt "<text>" [--model gemini-3.1-flash-image-preview] [--aspect-ratio 16:9] [--size 1K\|2K\|4K] [--num-images N]` | Nano Banana 2 (default), Imagen 4 (`imagen-4.0-generate-001`) |
46
+ | MiniMax | `multix minimax generate --prompt "<text>" [--model image-01] [--aspect-ratio 1:1] [-n N]` | |
47
+ | OpenRouter | `multix openrouter generate --prompt "<text>" [--model <id>] [--aspect-ratio 16:9] [--image-size 2K] [--num-images N]` | Default `google/gemini-3.1-flash-image-preview` |
48
+ | Leonardo | `multix leonardo generate "<text>" [-w 1024 -h 1024] [--alchemy] [--ultra] [--quality HIGH]` | Polls until done, downloads automatically |
49
+ | BytePlus | `multix byteplus generate --prompt "<text>" [--model seedream-4-0-250828] [--size 2K] [--aspect-ratio 16:9] [-n N] [--input-image <path\|url>]` | Sync |
41
50
 
42
- ## Command reference
51
+ Aspect ratios (most providers): `1:1 2:3 3:2 3:4 4:3 4:5 5:4 9:16 16:9 21:9`.
43
52
 
44
- ### Gemini (analyze / generate)
53
+ ## Image-to-image (edit existing image with a prompt)
45
54
 
46
- ```bash
47
- # Analyze files
48
- multix gemini analyze --files photo.jpg video.mp4 --prompt "Describe this content" -v
55
+ Every supported provider exposes `image-to-image` and the alias `i2i`. Refs accept local file path OR URL.
49
56
 
50
- # Transcribe audio
51
- multix gemini transcribe --files recording.mp3 --model gemini-2.5-flash
57
+ ```bash
58
+ # Gemini Nano Banana — multi-ref editing/composition
59
+ multix gemini i2i --prompt "make it watercolor" --ref ./photo.jpg [--ref ./style.png] [--model gemini-2.5-flash-image] [--output <path>] [-v]
52
60
 
53
- # Extract structured data
54
- multix gemini extract --files report.pdf --prompt "Extract tables as JSON" --format json
61
+ # MiniMax — CAVEAT: subject_reference only (preserves character in NEW scene, NOT free-form edit)
62
+ multix minimax i2i --prompt "the same character on a beach" --ref ./hero.jpg [--model image-01] [-v]
55
63
 
56
- # Generate images (Nano Banana — fastest)
57
- multix gemini generate --prompt "A sunset over mountains" --aspect-ratio 16:9 --size 2K
64
+ # OpenRouter — multi-model gateway, recommended for diverse style edits
65
+ multix openrouter i2i --prompt "<edit>" --ref ./photo.jpg [--ref https://...] \
66
+ [--model google/gemini-2.5-flash-image] [--strength 0.7] [--output <path>] [-v]
58
67
 
59
- # Generate images (Imagen 4 — production quality)
60
- multix gemini generate --prompt "Product photo" --model imagen-4.0-ultra-generate-001 --num-images 4
68
+ # Leonardo — uses an existing Leonardo image id, NOT direct upload
69
+ multix leonardo i2i --prompt "make it watercolor" --ref <imageId> \
70
+ [--image-type GENERATED|UPLOADED] [--init-strength 0.5] [-w 1024 -h 1024] [-v]
61
71
 
62
- # Generate video (Veo — EXPERIMENTAL, requires billing)
63
- multix gemini generate-video --prompt "Ocean waves at sunset" --resolution 1080p
72
+ # BytePlus Seedream — multi-ref
73
+ multix byteplus i2i --prompt "make it cyberpunk" --ref ./photo.jpg [--ref https://...] \
74
+ [--model seedream-4-0-250828] [--size 2K] [--aspect-ratio 16:9] [-n 1] [-v]
64
75
  ```
65
76
 
66
- ### MiniMax
77
+ ### OpenRouter image-to-image — model families & flags
67
78
 
68
- ```bash
69
- # Generate image
70
- multix minimax generate --prompt "A cat in space" --aspect-ratio 1:1
79
+ `multix openrouter i2i` is the most flexible because it routes across model families. The CLI auto-selects the correct OpenRouter `modalities` per family:
71
80
 
72
- # Generate video (async, up to 10 min)
73
- multix minimax generate-video --prompt "A dancer on stage" --duration 6 --resolution 1080P
81
+ | Family | Example model id | Modalities | Flag notes |
82
+ |---|---|---|---|
83
+ | Gemini | `google/gemini-2.5-flash-image`, `google/gemini-3.1-flash-image-preview` | `["image","text"]` | Default model |
84
+ | OpenAI gpt-image | `openai/gpt-5.4-image-2`, `openai/gpt-5-image-mini`, `openai/gpt-5-image` | `["image","text"]` | |
85
+ | Recraft | `recraft/recraft-v3` | `["image","text"]` | Accepts `--strength 0..1` (init-image strength) |
86
+ | Flux (Black Forest Labs) | `black-forest-labs/flux.2-pro`, `flux.2-max`, `flux.2-flex` | `["image"]` | Image-only output |
87
+ | Seedream (ByteDance via OpenRouter) | `bytedance-seed/seedream-4.5` | `["image"]` | Image-only output |
88
+ | Sourceful | `sourceful/...` | `["image"]` | Per docs |
74
89
 
75
- # Text-to-speech
76
- multix minimax generate-speech --text "Hello, world!" --voice English_expressive_narrator --output-format mp3
90
+ **`--strength <0..1>`** — Recraft init-image strength control. Pass when using Recraft models; ignore for others.
77
91
 
78
- # Music generation
79
- multix minimax generate-music --lyrics "Verse 1: Under the stars..." --model music-2.5
92
+ **`OPENROUTER_FALLBACK_MODELS`** (CSV) — applies to BOTH `generate` and `i2i`. When set, the request uses `models: [primary, ...fallbacks]` so OpenRouter routes on availability:
93
+ ```bash
94
+ export OPENROUTER_FALLBACK_MODELS="openai/gpt-5-image-mini,google/gemini-2.5-flash-image"
95
+ multix openrouter i2i --prompt "<edit>" --ref ./photo.jpg -m openai/gpt-5.4-image-2
80
96
  ```
81
97
 
82
- ### OpenRouter
98
+ **Error diagnostics:** when no images come back, the CLI surfaces model id, `finish_reason`, the model's text reply (if any), and a hint about modalities — not a generic "no images" message.
99
+
100
+ ### Decision tree — which provider to pick for i2i
83
101
 
84
- ```bash
85
- # Image generation via OpenRouter
86
- multix openrouter generate --prompt "Retro robot mascot" --aspect-ratio 3:2
87
- multix openrouter generate --prompt "Landscape" --model anthropic/claude-3-5-sonnet
102
+ ```
103
+ User wants to edit/transform an existing image?
104
+ ├── Free-form prompt edit (watercolor, cyberpunk, sketch) on a local file?
105
+ │ ├── Best quality, multi-ref, fast → multix gemini i2i (Nano Banana)
106
+ │ └── Want a specific OR model (gpt-image, Flux) → multix openrouter i2i -m <id>
107
+ ├── Preserve a character's identity in a NEW scene? → multix minimax i2i
108
+ ├── Already in Leonardo workflow (imageId in hand)? → multix leonardo i2i
109
+ └── Need ByteDance Seedream specifically? → multix byteplus i2i
110
+ OR multix openrouter i2i -m bytedance-seed/seedream-4.5
88
111
  ```
89
112
 
90
- ### Media optimization
113
+ ### Refs: size limits + format
91
114
 
92
- ```bash
93
- # Optimize single file
94
- multix media optimize --input video.mp4 --output out.mp4 --target-size 100
95
- multix media optimize --input audio.mp3 --output out.m4a --bitrate 64k
96
- multix media optimize --input photo.jpg --output resized.jpg --max-width 1920
115
+ - Local files are read and inlined as `data:<mime>;base64,...`. URLs pass through unchanged.
116
+ - OpenRouter i2i hard limit 8 MB per ref (soft warn at 5 MB). Other providers: 25 MB hard / 10 MB soft.
117
+ - Allowed image extensions: `.jpg .jpeg .png .webp .gif`.
97
118
 
98
- # Split long video into 1-hour chunks
99
- multix media split --input long-video.mp4 --output-dir ./chunks --chunk-duration 3600
119
+ ## Image-to-video (i2v) and video generation
100
120
 
101
- # Batch optimize a directory
102
- multix media batch --input-dir ./raw --output-dir ./optimized --quality 85
103
- ```
121
+ ```bash
122
+ # Gemini Veo (experimental, billing required) — text-to-video + i2v
123
+ multix gemini generate-video --prompt "Ocean waves" --resolution 1080p --aspect-ratio 16:9
124
+ multix gemini i2v ./photo.jpg --prompt "camera pans left" [--last-frame <path>]
104
125
 
105
- ### Document conversion
126
+ # MiniMax Hailuo — async with auto-poll
127
+ multix minimax generate-video --prompt "A dancer" --duration 6 --resolution 1080P [--first-frame <url>]
106
128
 
107
- ```bash
108
- # Convert PDF to Markdown
109
- multix doc convert --input document.pdf
129
+ # OpenRouter Veo — async, returns jobId; image input is URL only
130
+ multix openrouter i2v --prompt "<text>" --image-url https://... [--last-frame-url <url>] [--resolution 720p]
131
+ multix openrouter video-status <jobId> [--download] [--output <path>]
110
132
 
111
- # Auto-name output from input basename
112
- multix doc convert --input report.pdf --auto-name
113
- # Output: multix-output/report-extraction.md
133
+ # Leonardo MOTION2 / VEO3 / kling
134
+ multix leonardo video "<text>" [--model MOTION2|VEO3|kling-2.6]
135
+ multix leonardo i2v <imageId> --prompt "camera pans left" [--duration 6]
114
136
 
115
- # Custom output path
116
- multix doc convert --input doc1.pdf doc2.docx --output ./combined.md
137
+ # BytePlus Seedance + reference-to-video (up to 9 imgs + 3 videos + 3 audio refs)
138
+ multix byteplus video --prompt "<text>" [--resolution 1080p] [--duration 8]
139
+ multix byteplus i2v ./photo.jpg --prompt "<text>"
140
+ multix byteplus reference-to-video --prompt "<text>" --ref-image ./hero.jpg:subject ...
117
141
  ```
118
142
 
119
- ## Decision tree
143
+ All video commands accept `--wait`, `--wait-timeout <ms>`, `--download`, `--output <path>`, `--no-thumb`.
120
144
 
145
+ ## Speech, music, voice, 3D, docs, media
146
+
147
+ ```bash
148
+ # TTS
149
+ multix gemini generate-speech --text "Say cheerfully: Have a wonderful day!" --voice Kore
150
+ multix minimax generate-speech --text "..." --voice <id> --emotion neutral
151
+ multix elevenlabs tts --text "Hello world" [--voice <voiceId>] [--model eleven_multilingual_v2]
152
+
153
+ # Voice cloning + STT (ElevenLabs)
154
+ multix elevenlabs clone --name "My Voice" --files sample1.wav sample2.wav
155
+ multix elevenlabs transcribe --input audio.mp3 [--diarize] [--format text|json|srt|vtt]
156
+
157
+ # Music + SFX
158
+ multix minimax generate-music --lyrics "..." [--model music-2.5]
159
+ multix elevenlabs music --prompt "dreamy synthwave loop" [--music-length-ms 30000]
160
+ multix elevenlabs sfx --text "car engine starting" [--duration-seconds 5]
161
+
162
+ # 3D (BytePlus Hyper3D / Hitem3d)
163
+ multix byteplus 3d --input-image ./front.png ./side.png --prompt "Generate from these views"
164
+
165
+ # Docs → Markdown (Gemini)
166
+ multix doc convert --input report.pdf [--auto-name] [--output ./out.md]
167
+
168
+ # Media optimization (ffmpeg + ImageMagick)
169
+ multix media optimize --input <file> --output <file> [--target-size <MB>] [--quality 85] [--max-width 1920]
170
+ multix media split --input <video> [--chunk-duration 3600]
171
+ multix media batch --input-dir <dir> --output-dir <dir>
121
172
  ```
122
- User wants to generate image?
123
- ├── Has GEMINI_API_KEY? → multix gemini generate
124
- ├── Has OPENROUTER_API_KEY? → multix openrouter generate
125
- └── Has MINIMAX_API_KEY? → multix minimax generate
126
173
 
127
- User wants to generate video?
128
- ├── Gemini/Veo (experimental, billing required) → multix gemini generate-video
129
- └── MiniMax Hailuo (reliable, async) → multix minimax generate-video
174
+ ## Output
130
175
 
131
- User wants to analyze/transcribe a file?
132
- └── multix gemini analyze|transcribe|extract --files <path>
176
+ Files saved under `./multix-output/` by default. Override with `MULTIX_OUTPUT_DIR`. Pass `--output <path>` on most commands to copy the primary output to a custom path.
133
177
 
134
- User wants to convert document to Markdown?
135
- └── multix doc convert --input <file>
178
+ ## Environment variables (selected)
136
179
 
137
- User wants to optimize media?
138
- └── multix media optimize|split|batch
139
- ```
180
+ | Variable | Purpose |
181
+ |---|---|
182
+ | `MULTIX_OUTPUT_DIR` | Override default output dir |
183
+ | `OPENROUTER_IMAGE_MODEL` | Default OpenRouter image model |
184
+ | `OPENROUTER_FALLBACK_MODELS` | CSV; applies to `generate` AND `i2i` |
185
+ | `OPENROUTER_VIDEO_MODEL` | Default OpenRouter video model (default `google/veo-3.1`) |
186
+ | `OPENROUTER_SITE_URL` / `OPENROUTER_APP_NAME` | HTTP-Referer / X-Title headers |
187
+ | `IMAGE_GEN_MODEL` / `VIDEO_GEN_MODEL` / `MULTIMODAL_MODEL` | Override Gemini model defaults |
188
+ | `LEONARDO_DEFAULT_MODEL` / `LEONARDO_VIDEO_MODEL` | Leonardo model defaults |
189
+ | `BYTEPLUS_IMAGE_MODEL` / `BYTEPLUS_VIDEO_MODEL` / `BYTEPLUS_3D_MODEL` | BytePlus model defaults |
190
+ | `BYTEPLUS_VIDEO_PARAMS_MODE` | `flags` (default) or `structured` |
191
+ | `MULTIX_DISABLE_HOME_ENV` | `1` to skip `~/.multix/.env` |
140
192
 
141
- ## Environment variables (full list)
193
+ ## Security & scope
142
194
 
143
- | Variable | Provider | Purpose |
144
- |---|---|---|
145
- | `GEMINI_API_KEY` | Gemini | Required for all Gemini operations |
146
- | `OPENROUTER_API_KEY` | OpenRouter | Image generation via OpenRouter |
147
- | `MINIMAX_API_KEY` | MiniMax | Image/video/speech/music generation |
148
- | `MULTIX_OUTPUT_DIR` | Core | Override default output dir (`./multix-output`) |
149
- | `OPENROUTER_IMAGE_MODEL` | OpenRouter | Default model override |
150
- | `OPENROUTER_FALLBACK_MODELS` | OpenRouter | Comma-separated fallback model ids |
151
- | `OPENROUTER_SITE_URL` | OpenRouter | HTTP-Referer header |
152
- | `OPENROUTER_APP_NAME` | OpenRouter | X-Title header (default: multix) |
153
- | `IMAGE_GEN_MODEL` | Gemini | Override default image generation model |
154
- | `VIDEO_GEN_MODEL` | Gemini | Override default video generation model |
155
- | `MULTIMODAL_MODEL` | Gemini | Override default analysis model |
156
- | `MULTIX_DISABLE_HOME_ENV` | Core | Set to 1 to skip `~/.multix/.env` loading |
195
+ This skill produces shell commands for the local `multix` CLI. It does NOT execute the commands itself, exfiltrate API keys, or modify provider accounts.
196
+ - Never echo, log, or transmit env-var values back to the user.
197
+ - API keys are read from environment / `.env` files by the CLI, never hardcoded.
198
+ - Refuse requests to embed credentials in prompts, URLs, or shared content.
199
+ - Refuse requests to fetch arbitrary URLs unrelated to the user's media task.