@mrgoonie/multix 0.0.7 → 0.0.8

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.8] - 2026-05-11
+
+### Fixed
+- `multix openrouter image-to-image` previously failed for any non-Gemini text+image model (e.g. `openai/gpt-5.4-image-2`, `openai/gpt-5-image-mini`, `recraft/recraft-v3`) because the `modalities` heuristic forced `["image"]` for non-Gemini models. The new default is `["image","text"]`, with `["image"]` only emitted for verified image-only families (`black-forest-labs/`, `bytedance-seed/seedream`, `sourceful/`).
+- "No images in response" errors now include the model id, `finish_reason`, the model's text reply (if any), and a hint about modalities — previously a single generic line.
+
+### Added
+- `multix openrouter image-to-image --strength <0..1>` — Recraft init-image strength control.
+- `OPENROUTER_FALLBACK_MODELS` (CSV) now applies to `image-to-image` (previously `generate` only). Sends `models: [primary, ...fallbacks]` so OpenRouter can route on availability.
+- New shared module `src/providers/openrouter/payload.ts` — `resolveModalities`, `buildOpenRouterHeaders`, `extractImagesFromResponse`, `formatNoImagesError`, `buildI2IPayload`. DRY across `generate` + `image-to-image`.
+
+### Changed
+- README and `skill/SKILL.md` document the OpenRouter model-family matrix (Gemini / OpenAI gpt-image / Recraft → text+image; Flux 2.x / Seedream 4.5 / Sourceful → image-only) and the new flags.
+
+### Verified live
+`openai/gpt-5.4-image-2`, `openai/gpt-5-image-mini`, `google/gemini-2.5-flash-image`, `black-forest-labs/flux.2-pro`, `flux.2-max`, `flux.2-flex`, `bytedance-seed/seedream-4.5`.
+
 ## [0.0.7] - 2026-05-05
 
 ### Added

package/README.md

@@ -146,7 +146,7 @@ multix minimax generate-music [--lyrics <str>] [--prompt <str>] [--model music-2
 multix openrouter generate --prompt "Retro robot" [--model google/gemini-3.1-flash-image-preview] [--aspect-ratio 1:1] [--image-size <sz>] [--num-images 1] [-v]
 
 # Image-to-image (alias: i2i) — refs accept URL or local path
-multix openrouter image-to-image --prompt "make it cyberpunk" --ref ./photo.jpg [--ref https://...] [--model google/gemini-2.5-flash-image] [--output <path>] [-v]
+multix openrouter image-to-image --prompt "make it cyberpunk" --ref ./photo.jpg [--ref https://...] [--model google/gemini-2.5-flash-image] [--strength 0.7] [--output <path>] [-v]
 
 # Image-to-video (async — returns job id; image input is URL only)
 multix openrouter image-to-video --prompt "camera pans left" --image-url https://... [--last-frame-url <url>] [--model google/veo-3.1] [--resolution 720p] [--aspect-ratio 16:9] [--duration <n>] [--seed <n>] [-v]
@@ -159,7 +159,9 @@ multix openrouter video-status <jobId> [--download] [--output <path>] [-v]
 multix openrouter video-models
 ```
 
-Fallback models from `OPENROUTER_FALLBACK_MODELS` (CSV) are appended to the chat-image payload automatically. Override the default video model with `OPENROUTER_VIDEO_MODEL` (default `google/veo-3.1`).
+**Supported i2i model families:** Gemini (default) and OpenAI gpt-image return `text+image` (modalities `["image","text"]`); Recraft accepts `--strength` (init-image strength 0..1); Flux / Sourceful are image-only (`["image"]`). The CLI picks the right `modalities` automatically based on the model id prefix.
+
+Fallback models from `OPENROUTER_FALLBACK_MODELS` (CSV) are appended to the chat-image payload automatically — applies to both `generate` and `image-to-image`. Override the default video model with `OPENROUTER_VIDEO_MODEL` (default `google/veo-3.1`).
 
 ### `multix leonardo`
 

package/dist/cli.js

@@ -4361,18 +4361,18 @@ import fs29 from "fs";
 import path34 from "path";
 init_errors();
 init_http_client();
-var OPENROUTER_API_URL = "https://openrouter.ai/api/v1/chat/completions";
-var DEFAULT_OPENROUTER_MODEL = "google/gemini-3.1-flash-image-preview";
-function requireOpenRouterKey() {
-  const key = resolveKey("OPENROUTER_API_KEY");
-  if (!key) {
-    throw new ConfigError(
-      "OPENROUTER_API_KEY is not set. Get one at https://openrouter.ai/settings/keys"
-    );
-  }
-  return key;
+
+// src/providers/openrouter/payload.ts
+var IMAGE_ONLY_MODEL_PREFIXES = [
+  "black-forest-labs/",
+  "bytedance-seed/seedream",
+  "sourceful/"
+];
+function resolveModalities(model) {
+  const lower = model.toLowerCase();
+  return IMAGE_ONLY_MODEL_PREFIXES.some((p) => lower.startsWith(p)) ? ["image"] : ["image", "text"];
 }
-function buildHeaders(apiKey) {
+function buildOpenRouterHeaders(apiKey) {
   const headers = {
     Authorization: `Bearer ${apiKey}`,
     "Content-Type": "application/json"
@@ -4383,10 +4383,96 @@ function buildHeaders(apiKey) {
   if (title) headers["X-Title"] = title;
   return headers;
 }
+function extractImagesFromResponse(data) {
+  const out = { urls: [] };
+  if (!data || typeof data !== "object") return out;
+  const root = data;
+  if (typeof root.model === "string") out.model = root.model;
+  const choices = Array.isArray(root.choices) ? root.choices : [];
+  const first = choices[0];
+  if (!first || typeof first !== "object") return out;
+  const choice = first;
+  if (typeof choice.finish_reason === "string") out.finishReason = choice.finish_reason;
+  const message = choice.message;
+  if (!message) return out;
+  const images = message.images;
+  if (Array.isArray(images)) {
+    for (const item of images) {
+      const url = readImageUrl(item);
+      if (url) out.urls.push(url);
+    }
+  }
+  const content = message.content;
+  if (Array.isArray(content)) {
+    for (const part of content) {
+      const url = readImageUrl(part);
+      if (url) out.urls.push(url);
+    }
+  } else if (typeof content === "string") {
+    out.textContent = content;
+  }
+  return out;
+}
+function readImageUrl(item) {
+  if (!item || typeof item !== "object") return void 0;
+  const rec = item;
+  if (rec.type !== void 0 && rec.type !== "image_url") return void 0;
+  const inner = rec.image_url;
+  const url = inner?.url;
+  return typeof url === "string" ? url : void 0;
+}
+function formatNoImagesError(model, parsed) {
+  const parts = [
+    `No images returned by '${model}' (finish_reason=${parsed.finishReason ?? "n/a"}).`
+  ];
+  if (parsed.textContent) {
+    parts.push(`Model said: "${truncate(parsed.textContent, 200)}".`);
+  }
+  parts.push(
+    "Hint: verify the model supports image output and that 'modalities' includes 'image'."
+  );
+  return parts.join(" ");
+}
+function truncate(s, n) {
+  return s.length > n ? `${s.slice(0, n)}\u2026` : s;
+}
+function buildI2IPayload(opts) {
+  const content = opts.refs.map((url) => ({
+    type: "image_url",
+    image_url: { url }
+  }));
+  content.push({ type: "text", text: opts.prompt });
+  const payload = {
+    messages: [{ role: "user", content }],
+    modalities: resolveModalities(opts.model)
+  };
+  if (typeof opts.strength === "number") {
+    payload.image_config = { strength: opts.strength };
+  }
+  if (opts.fallbackModels.length > 0) {
+    payload.models = [opts.model, ...opts.fallbackModels];
+  } else {
+    payload.model = opts.model;
+  }
+  return payload;
+}
+
+// src/providers/openrouter/client.ts
+var OPENROUTER_API_URL = "https://openrouter.ai/api/v1/chat/completions";
+var DEFAULT_OPENROUTER_MODEL = "google/gemini-3.1-flash-image-preview";
+function requireOpenRouterKey() {
+  const key = resolveKey("OPENROUTER_API_KEY");
+  if (!key) {
+    throw new ConfigError(
+      "OPENROUTER_API_KEY is not set. Get one at https://openrouter.ai/settings/keys"
+    );
+  }
+  return key;
+}
 function buildPayload(opts) {
   const payload = {
     messages: [{ role: "user", content: opts.prompt }],
-    modalities: opts.model.includes("gemini") ? ["image", "text"] : ["image"],
+    modalities: resolveModalities(opts.model),
     image_config: { aspect_ratio: opts.aspectRatio }
   };
   if (opts.imageSize) {
@@ -4415,29 +4501,19 @@ async function generateOpenRouterImage(opts) {
       data = await httpJson({
         url: OPENROUTER_API_URL,
         method: "POST",
-        headers: buildHeaders(apiKey),
+        headers: buildOpenRouterHeaders(apiKey),
         body: payload,
         timeoutMs: 24e4
       });
     } catch (e) {
       return { status: "error", error: e instanceof Error ? e.message : String(e) };
     }
-    const choices = data.choices ?? [];
-    if (choices.length === 0) {
-      return { status: "error", error: `No choices in response: ${JSON.stringify(data)}` };
-    }
-    const messageImages = choices[0]?.message?.images ?? [];
-    if (messageImages.length === 0) {
-      return {
-        status: "error",
-        error: `No images in response \u2014 model '${model}' may not support image generation`
-      };
-    }
-    for (const img of messageImages) {
-      const url = img.image_url?.url;
-      if (url) imageUrls.push(url);
+    const parsed = extractImagesFromResponse(data);
+    if (parsed.urls.length === 0) {
+      return { status: "error", error: formatNoImagesError(model, parsed) };
     }
-    usedModel = data.model ?? usedModel;
+    imageUrls.push(...parsed.urls);
+    usedModel = parsed.model ?? usedModel;
     if (imageUrls.length >= numImages) break;
   }
   const outDir = getOutputDir();
@@ -4508,13 +4584,15 @@ function registerOpenRouterImageToImageCommand(parent) {
     "Reference image (URL or local path); repeatable (most models accept 1)",
     collect5,
     []
-  ).option("-m, --model <id>", `OpenRouter model id (default ${DEFAULT_MODEL})`).option("--output <path>", "Save first generated image to this path").option("-v, --verbose", "Verbose logging").action(
+  ).option("-m, --model <id>", `OpenRouter model id (default ${DEFAULT_MODEL})`).option("--strength <n>", "Recraft init-image strength 0..1 (Recraft models only)").option("--output <path>", "Save first generated image to this path").option("-v, --verbose", "Verbose logging").action(
     async (opts) => {
       if (!opts.ref || opts.ref.length === 0) {
-        throw new Error("At least one --ref is required for image-to-image.");
+        throw new ValidationError("At least one --ref is required for image-to-image.");
       }
       const logger = createLogger({ verbose: opts.verbose ?? false });
       const model = opts.model ?? resolveKey("OPENROUTER_IMAGE_MODEL") ?? DEFAULT_MODEL;
+      const strength = parseStrength(opts.strength);
+      const fallbackModels = (resolveKey("OPENROUTER_FALLBACK_MODELS") ?? "").split(",").map((m) => m.trim()).filter(Boolean);
       const resolvedRefs = [];
       for (const r of opts.ref) {
         const resolved = await resolveImageInput(r, {
@@ -4524,11 +4602,17 @@ function registerOpenRouterImageToImageCommand(parent) {
         });
         resolvedRefs.push(refUrl(resolved));
       }
-      logger.debug(`OpenRouter i2i: model=${model}, refs=${resolvedRefs.length}`);
+      const strengthDbg = strength !== void 0 ? `, strength=${strength}` : "";
+      const fallbacksDbg = fallbackModels.length ? `, fallbacks=${fallbackModels.join(",")}` : "";
+      logger.debug(
+        `OpenRouter i2i: model=${model}, refs=${resolvedRefs.length}${strengthDbg}${fallbacksDbg}`
+      );
       const saved = await runImageToImage({
         prompt: opts.prompt,
         model,
         refs: resolvedRefs,
+        strength,
+        fallbackModels,
         output: opts.output,
         logger
       });
@@ -4542,26 +4626,24 @@ Generated ${saved.length} image(s):`);
 function collect5(value, prev) {
   return [...prev, value];
 }
+function parseStrength(raw) {
+  if (raw === void 0) return void 0;
+  const n = Number.parseFloat(raw);
+  if (!Number.isFinite(n) || n < 0 || n > 1) {
+    throw new ValidationError(`--strength must be a number in [0,1], got '${raw}'`);
+  }
+  return n;
+}
 async function runImageToImage(opts) {
   const apiKey = requireOpenRouterKey();
-  const headers = {
-    Authorization: `Bearer ${apiKey}`,
-    "Content-Type": "application/json"
-  };
-  const referer = resolveKey("OPENROUTER_SITE_URL");
-  const title = resolveKey("OPENROUTER_APP_NAME") ?? "multix";
-  if (referer) headers["HTTP-Referer"] = referer;
-  if (title) headers["X-Title"] = title;
-  const content = opts.refs.map((url) => ({
-    type: "image_url",
-    image_url: { url }
-  }));
-  content.push({ type: "text", text: opts.prompt });
-  const payload = {
+  const headers = buildOpenRouterHeaders(apiKey);
+  const payload = buildI2IPayload({
+    prompt: opts.prompt,
     model: opts.model,
-    messages: [{ role: "user", content }],
-    modalities: opts.model.includes("gemini") ? ["image", "text"] : ["image"]
-  };
+    refs: opts.refs,
+    strength: opts.strength,
+    fallbackModels: opts.fallbackModels
+  });
   const data = await httpJson({
     url: OPENROUTER_API_URL,
     method: "POST",
@@ -4569,18 +4651,15 @@ async function runImageToImage(opts) {
     body: payload,
     timeoutMs: 24e4
   });
-  const messageImages = data.choices?.[0]?.message?.images ?? [];
-  if (messageImages.length === 0) {
-    throw new ProviderError(
-      `No images in response \u2014 model '${opts.model}' may not support image-to-image`,
-      "openrouter"
-    );
+  const parsed = extractImagesFromResponse(data);
+  if (parsed.urls.length === 0) {
+    throw new ProviderError(formatNoImagesError(opts.model, parsed), "openrouter");
   }
   const outDir = getOutputDir();
   const ts = Date.now();
   const saved = [];
-  for (let i = 0; i < messageImages.length; i++) {
-    const url = messageImages[i]?.image_url?.url;
+  for (let i = 0; i < parsed.urls.length; i++) {
+    const url = parsed.urls[i];
     if (!url) continue;
     const bytes = await fetchBytes(url);
     const dest = path35.join(outDir, `openrouter-i2i-${ts}-${i + 1}.png`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrgoonie/multix",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "AI multimodal CLI — Gemini (incl. Flash TTS), MiniMax, OpenRouter, Leonardo, BytePlus, ElevenLabs, ffmpeg, ImageMagick, doc-to-md",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: multix
-description: AI multimodal CLI — Gemini/MiniMax/OpenRouter image & video generation, ffmpeg/ImageMagick media optimization, document-to-Markdown conversion via Gemini Files API.
-version: 0.0.1
+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.
+version: 0.0.7
 ---
 
 # multix — AI Multimodal CLI
@@ -9,148 +9,191 @@ version: 0.0.1
 ## When to use
 
 Activate this skill when the user asks to:
-- Generate, analyze, or describe images or video
-- Transcribe audio or video files
-- Extract structured data from documents (PDF, DOCX, images)
-- Convert documents to Markdown
-- Optimize or split video/audio/image files
-- Generate speech (TTS) or music
+- Generate images from a text prompt (any provider)
+- **Edit/transform an existing image with a prompt** (image-to-image, alias `i2i`)
+- Generate video from text or from a reference image (image-to-video, alias `i2v`)
+- Generate or clone a voice, run STT, generate music or sound effects
+- Generate 3D models (Hyper3D / Hitem3d)
+- Analyze, transcribe, or extract structured data from media/docs
+- Convert PDFs / DOCX / images to Markdown
+- Optimize, resize, batch-convert, or split video/audio/image files
 
-## Required env (at least one)
+## Required env (set at least one provider key)
 
 ```
-GEMINI_API_KEY       # Google AI Studio — required for analyze/transcribe/doc/generate
-OPENROUTER_API_KEY   # OpenRouter — alternative image generation
-MINIMAX_API_KEY      # MiniMax — image, video, speech, music generation
+GEMINI_API_KEY        # Google AI Studio
+OPENROUTER_API_KEY    # OpenRouter (multi-model gateway)
+MINIMAX_API_KEY       # MiniMax (image/video/speech/music)
+LEONARDO_API_KEY      # Leonardo.Ai (image/video/upscale)
+BYTEPLUS_API_KEY      # BytePlus / Volcengine ARK (Seedream/Seedance/Hyper3D)
+ELEVENLABS_API_KEY    # ElevenLabs (TTS, cloning, STT, music, dubbing)
 ```
 
-## Installation
+Priority: `process.env` > `cwd/.env` > `~/.multix/.env`.
+
+## Install + diagnostics
 
 ```bash
-npm install -g multix
-# or run without installing:
-npx multix --help
+npm install -g @mrgoonie/multix
+multix check [--verbose]
 ```
 
-## Diagnostics
+## Image generation
 
-```bash
-multix check            # verify keys, tooling, Gemini connectivity
-multix check --verbose  # show install hints
-```
+| Provider | Command | Notes |
+|---|---|---|
+| 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`) |
+| MiniMax | `multix minimax generate --prompt "<text>" [--model image-01] [--aspect-ratio 1:1] [-n N]` | |
+| 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` |
+| Leonardo | `multix leonardo generate "<text>" [-w 1024 -h 1024] [--alchemy] [--ultra] [--quality HIGH]` | Polls until done, downloads automatically |
+| BytePlus | `multix byteplus generate --prompt "<text>" [--model seedream-4-0-250828] [--size 2K] [--aspect-ratio 16:9] [-n N] [--input-image <path\|url>]` | Sync |
 
-## Command reference
+Aspect ratios (most providers): `1:1 2:3 3:2 3:4 4:3 4:5 5:4 9:16 16:9 21:9`.
 
-### Gemini (analyze / generate)
+## Image-to-image (edit existing image with a prompt)
 
-```bash
-# Analyze files
-multix gemini analyze --files photo.jpg video.mp4 --prompt "Describe this content" -v
+Every supported provider exposes `image-to-image` and the alias `i2i`. Refs accept local file path OR URL.
 
-# Transcribe audio
-multix gemini transcribe --files recording.mp3 --model gemini-2.5-flash
+```bash
+# Gemini Nano Banana — multi-ref editing/composition
+multix gemini i2i --prompt "make it watercolor" --ref ./photo.jpg [--ref ./style.png] [--model gemini-2.5-flash-image] [--output <path>] [-v]
 
-# Extract structured data
-multix gemini extract --files report.pdf --prompt "Extract tables as JSON" --format json
+# MiniMax — CAVEAT: subject_reference only (preserves character in NEW scene, NOT free-form edit)
+multix minimax i2i --prompt "the same character on a beach" --ref ./hero.jpg [--model image-01] [-v]
 
-# Generate images (Nano Banana — fastest)
-multix gemini generate --prompt "A sunset over mountains" --aspect-ratio 16:9 --size 2K
+# OpenRouter — multi-model gateway, recommended for diverse style edits
+multix openrouter i2i --prompt "<edit>" --ref ./photo.jpg [--ref https://...] \
+  [--model google/gemini-2.5-flash-image] [--strength 0.7] [--output <path>] [-v]
 
-# Generate images (Imagen 4 — production quality)
-multix gemini generate --prompt "Product photo" --model imagen-4.0-ultra-generate-001 --num-images 4
+# Leonardo — uses an existing Leonardo image id, NOT direct upload
+multix leonardo i2i --prompt "make it watercolor" --ref <imageId> \
+  [--image-type GENERATED|UPLOADED] [--init-strength 0.5] [-w 1024 -h 1024] [-v]
 
-# Generate video (Veo — EXPERIMENTAL, requires billing)
-multix gemini generate-video --prompt "Ocean waves at sunset" --resolution 1080p
+# BytePlus Seedream — multi-ref
+multix byteplus i2i --prompt "make it cyberpunk" --ref ./photo.jpg [--ref https://...] \
+  [--model seedream-4-0-250828] [--size 2K] [--aspect-ratio 16:9] [-n 1] [-v]
 ```
 
-### MiniMax
+### OpenRouter image-to-image — model families & flags
 
-```bash
-# Generate image
-multix minimax generate --prompt "A cat in space" --aspect-ratio 1:1
+`multix openrouter i2i` is the most flexible because it routes across model families. The CLI auto-selects the correct OpenRouter `modalities` per family:
 
-# Generate video (async, up to 10 min)
-multix minimax generate-video --prompt "A dancer on stage" --duration 6 --resolution 1080P
+| Family | Example model id | Modalities | Flag notes |
+|---|---|---|---|
+| Gemini | `google/gemini-2.5-flash-image`, `google/gemini-3.1-flash-image-preview` | `["image","text"]` | Default model |
+| OpenAI gpt-image | `openai/gpt-5.4-image-2`, `openai/gpt-5-image-mini`, `openai/gpt-5-image` | `["image","text"]` | |
+| Recraft | `recraft/recraft-v3` | `["image","text"]` | Accepts `--strength 0..1` (init-image strength) |
+| Flux (Black Forest Labs) | `black-forest-labs/flux.2-pro`, `flux.2-max`, `flux.2-flex` | `["image"]` | Image-only output |
+| Seedream (ByteDance via OpenRouter) | `bytedance-seed/seedream-4.5` | `["image"]` | Image-only output |
+| Sourceful | `sourceful/...` | `["image"]` | Per docs |
 
-# Text-to-speech
-multix minimax generate-speech --text "Hello, world!" --voice English_expressive_narrator --output-format mp3
+**`--strength <0..1>`** — Recraft init-image strength control. Pass when using Recraft models; ignore for others.
 
-# Music generation
-multix minimax generate-music --lyrics "Verse 1: Under the stars..." --model music-2.5
+**`OPENROUTER_FALLBACK_MODELS`** (CSV) — applies to BOTH `generate` and `i2i`. When set, the request uses `models: [primary, ...fallbacks]` so OpenRouter routes on availability:
+```bash
+export OPENROUTER_FALLBACK_MODELS="openai/gpt-5-image-mini,google/gemini-2.5-flash-image"
+multix openrouter i2i --prompt "<edit>" --ref ./photo.jpg -m openai/gpt-5.4-image-2
 ```
 
-### OpenRouter
+**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.
+
+### Decision tree — which provider to pick for i2i
 
-```bash
-# Image generation via OpenRouter
-multix openrouter generate --prompt "Retro robot mascot" --aspect-ratio 3:2
-multix openrouter generate --prompt "Landscape" --model anthropic/claude-3-5-sonnet
+```
+User wants to edit/transform an existing image?
+  ├── Free-form prompt edit (watercolor, cyberpunk, sketch) on a local file?
+  │   ├── Best quality, multi-ref, fast              → multix gemini i2i (Nano Banana)
+  │   └── Want a specific OR model (gpt-image, Flux) → multix openrouter i2i -m <id>
+  ├── Preserve a character's identity in a NEW scene? → multix minimax i2i
+  ├── Already in Leonardo workflow (imageId in hand)? → multix leonardo i2i
+  └── Need ByteDance Seedream specifically?           → multix byteplus i2i
+                                                       OR multix openrouter i2i -m bytedance-seed/seedream-4.5
 ```
 
-### Media optimization
+### Refs: size limits + format
 
-```bash
-# Optimize single file
-multix media optimize --input video.mp4 --output out.mp4 --target-size 100
-multix media optimize --input audio.mp3 --output out.m4a --bitrate 64k
-multix media optimize --input photo.jpg --output resized.jpg --max-width 1920
+- Local files are read and inlined as `data:<mime>;base64,...`. URLs pass through unchanged.
+- OpenRouter i2i hard limit 8 MB per ref (soft warn at 5 MB). Other providers: 25 MB hard / 10 MB soft.
+- Allowed image extensions: `.jpg .jpeg .png .webp .gif`.
 
-# Split long video into 1-hour chunks
-multix media split --input long-video.mp4 --output-dir ./chunks --chunk-duration 3600
+## Image-to-video (i2v) and video generation
 
-# Batch optimize a directory
-multix media batch --input-dir ./raw --output-dir ./optimized --quality 85
-```
+```bash
+# Gemini Veo (experimental, billing required) — text-to-video + i2v
+multix gemini generate-video --prompt "Ocean waves" --resolution 1080p --aspect-ratio 16:9
+multix gemini i2v ./photo.jpg --prompt "camera pans left" [--last-frame <path>]
 
-### Document conversion
+# MiniMax Hailuo — async with auto-poll
+multix minimax generate-video --prompt "A dancer" --duration 6 --resolution 1080P [--first-frame <url>]
 
-```bash
-# Convert PDF to Markdown
-multix doc convert --input document.pdf
+# OpenRouter Veo — async, returns jobId; image input is URL only
+multix openrouter i2v --prompt "<text>" --image-url https://... [--last-frame-url <url>] [--resolution 720p]
+multix openrouter video-status <jobId> [--download] [--output <path>]
 
-# Auto-name output from input basename
-multix doc convert --input report.pdf --auto-name
-# Output: multix-output/report-extraction.md
+# Leonardo MOTION2 / VEO3 / kling
+multix leonardo video "<text>" [--model MOTION2|VEO3|kling-2.6]
+multix leonardo i2v <imageId> --prompt "camera pans left" [--duration 6]
 
-# Custom output path
-multix doc convert --input doc1.pdf doc2.docx --output ./combined.md
+# BytePlus Seedance + reference-to-video (up to 9 imgs + 3 videos + 3 audio refs)
+multix byteplus video --prompt "<text>" [--resolution 1080p] [--duration 8]
+multix byteplus i2v ./photo.jpg --prompt "<text>"
+multix byteplus reference-to-video --prompt "<text>" --ref-image ./hero.jpg:subject ...
 ```
 
-## Decision tree
+All video commands accept `--wait`, `--wait-timeout <ms>`, `--download`, `--output <path>`, `--no-thumb`.
 
+## Speech, music, voice, 3D, docs, media
+
+```bash
+# TTS
+multix gemini generate-speech --text "Say cheerfully: Have a wonderful day!" --voice Kore
+multix minimax generate-speech --text "..." --voice <id> --emotion neutral
+multix elevenlabs tts --text "Hello world" [--voice <voiceId>] [--model eleven_multilingual_v2]
+
+# Voice cloning + STT (ElevenLabs)
+multix elevenlabs clone --name "My Voice" --files sample1.wav sample2.wav
+multix elevenlabs transcribe --input audio.mp3 [--diarize] [--format text|json|srt|vtt]
+
+# Music + SFX
+multix minimax generate-music --lyrics "..." [--model music-2.5]
+multix elevenlabs music --prompt "dreamy synthwave loop" [--music-length-ms 30000]
+multix elevenlabs sfx --text "car engine starting" [--duration-seconds 5]
+
+# 3D (BytePlus Hyper3D / Hitem3d)
+multix byteplus 3d --input-image ./front.png ./side.png --prompt "Generate from these views"
+
+# Docs → Markdown (Gemini)
+multix doc convert --input report.pdf [--auto-name] [--output ./out.md]
+
+# Media optimization (ffmpeg + ImageMagick)
+multix media optimize --input <file> --output <file> [--target-size <MB>] [--quality 85] [--max-width 1920]
+multix media split --input <video> [--chunk-duration 3600]
+multix media batch --input-dir <dir> --output-dir <dir>
 ```
-User wants to generate image?
-  ├── Has GEMINI_API_KEY? → multix gemini generate
-  ├── Has OPENROUTER_API_KEY? → multix openrouter generate
-  └── Has MINIMAX_API_KEY? → multix minimax generate
 
-User wants to generate video?
-  ├── Gemini/Veo (experimental, billing required) → multix gemini generate-video
-  └── MiniMax Hailuo (reliable, async) → multix minimax generate-video
+## Output
 
-User wants to analyze/transcribe a file?
-  └── multix gemini analyze|transcribe|extract --files <path>
+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.
 
-User wants to convert document to Markdown?
-  └── multix doc convert --input <file>
+## Environment variables (selected)
 
-User wants to optimize media?
-  └── multix media optimize|split|batch
-```
+| Variable | Purpose |
+|---|---|
+| `MULTIX_OUTPUT_DIR` | Override default output dir |
+| `OPENROUTER_IMAGE_MODEL` | Default OpenRouter image model |
+| `OPENROUTER_FALLBACK_MODELS` | CSV; applies to `generate` AND `i2i` |
+| `OPENROUTER_VIDEO_MODEL` | Default OpenRouter video model (default `google/veo-3.1`) |
+| `OPENROUTER_SITE_URL` / `OPENROUTER_APP_NAME` | HTTP-Referer / X-Title headers |
+| `IMAGE_GEN_MODEL` / `VIDEO_GEN_MODEL` / `MULTIMODAL_MODEL` | Override Gemini model defaults |
+| `LEONARDO_DEFAULT_MODEL` / `LEONARDO_VIDEO_MODEL` | Leonardo model defaults |
+| `BYTEPLUS_IMAGE_MODEL` / `BYTEPLUS_VIDEO_MODEL` / `BYTEPLUS_3D_MODEL` | BytePlus model defaults |
+| `BYTEPLUS_VIDEO_PARAMS_MODE` | `flags` (default) or `structured` |
+| `MULTIX_DISABLE_HOME_ENV` | `1` to skip `~/.multix/.env` |
 
-## Environment variables (full list)
+## Security & scope
 
-| Variable | Provider | Purpose |
-|---|---|---|
-| `GEMINI_API_KEY` | Gemini | Required for all Gemini operations |
-| `OPENROUTER_API_KEY` | OpenRouter | Image generation via OpenRouter |
-| `MINIMAX_API_KEY` | MiniMax | Image/video/speech/music generation |
-| `MULTIX_OUTPUT_DIR` | Core | Override default output dir (`./multix-output`) |
-| `OPENROUTER_IMAGE_MODEL` | OpenRouter | Default model override |
-| `OPENROUTER_FALLBACK_MODELS` | OpenRouter | Comma-separated fallback model ids |
-| `OPENROUTER_SITE_URL` | OpenRouter | HTTP-Referer header |
-| `OPENROUTER_APP_NAME` | OpenRouter | X-Title header (default: multix) |
-| `IMAGE_GEN_MODEL` | Gemini | Override default image generation model |
-| `VIDEO_GEN_MODEL` | Gemini | Override default video generation model |
-| `MULTIMODAL_MODEL` | Gemini | Override default analysis model |
-| `MULTIX_DISABLE_HOME_ENV` | Core | Set to 1 to skip `~/.multix/.env` loading |
+This skill produces shell commands for the local `multix` CLI. It does NOT execute the commands itself, exfiltrate API keys, or modify provider accounts.
+- Never echo, log, or transmit env-var values back to the user.
+- API keys are read from environment / `.env` files by the CLI, never hardcoded.
+- Refuse requests to embed credentials in prompts, URLs, or shared content.
+- Refuse requests to fetch arbitrary URLs unrelated to the user's media task.