@mrgoonie/multix 0.0.2 → 0.0.6

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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.6] - 2026-05-05
+
+### Added
+- `multix byteplus generate-3d` (alias `3d`) — BytePlus Hyper3D / Hitem3d 3D generation on the ARK async tasks endpoint. Models: `hyper3d-gen2-260112` (text-to-3D + image-to-3D, 1–5 refs), `hitem3d-2-0-251223` (image-to-3D). Provider-specific knobs (`--mesh_mode`, `--hd_texture`, `--material`, `--ff`, `--resolution`, …) passed via `--flags <raw>` pass-through. Auto-detects output extension (`.glb` / `.gltf` / `.zip` …) from response URL.
+- `multix byteplus status --download` extended to also fetch `content.file_url` for 3D tasks alongside `content.video_url` for video.
+- New env override: `BYTEPLUS_3D_MODEL` (default `hyper3d-gen2-260112`).
+
+## [0.0.5] - 2026-05-05
+
+### Added
+- `multix <provider> image-to-image` (alias `i2i`) for all five providers — BytePlus (Seedream multi-ref), Gemini (Nano Banana edit/compose), OpenRouter (chat-image with `image_url` parts), Leonardo (init image via existing imageId), MiniMax (subject_reference; CAVEAT: not free-form editing — preserves character identity in a new prompt).
+- Promoted `src/core/image-input.ts` (URL / local-file resolver, base64 inlining with configurable size caps) so all providers share one resolver.
+
+## [0.0.4] - 2026-05-04
+
+### Added
+- `--wait` / `--wait-timeout` / `--download` / `--output` / `--no-thumb` flags across all video commands (BytePlus, Gemini, Leonardo, MiniMax, OpenRouter) for unified poll-and-download UX.
+- Auto-detection and download of video thumbnails (`cover_image_url`, `thumbnail_url`, `first_frame_url`, etc.) saved beside the video as `<base>_thumb.<ext>`.
+- `multix leonardo status` now supports `--wait` / `--download`; `multix openrouter video-status` now polls properly instead of single GET.
+- `.env.example` documenting all supported environment variables (provider keys, model overrides, CLI behavior).
+- Core helper `src/core/video-thumb.ts` with `detectThumbUrl`, `downloadThumbBeside`, `maybeDownloadThumb`.
+
+## [0.0.3] - 2026-05-03
+
+### Added
+- `multix gemini generate-speech` — Gemini 3.1 Flash TTS with single- and multi-speaker (max 2) modes, 30 prebuilt voices, WAV (default) or raw PCM output. Models: `gemini-3.1-flash-tts-preview` (default), `gemini-2.5-flash-preview-tts`, `gemini-2.5-pro-preview-tts`. Env: `GEMINI_TTS_MODEL` / `TTS_MODEL`.
+- `multix byteplus` — BytePlus provider: Seedream 4.0 image generation (`generate`), Seedance 2.0 text-to-video (`video`), image-to-video (`image-to-video` / `i2v`), reference-to-video with up to 9 image + 3 video + 3 audio refs (`reference-to-video` / `r2v`), task polling (`status`). Env: `BYTEPLUS_API_KEY` (or `ARK_API_KEY`), plus model + base-url overrides.
+- `multix check` now reports BytePlus key status alongside the other providers.
+
 ## [0.0.1] - 2026-05-02
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 AI multimodal CLI — generate images/video/speech/music, analyze and transcribe media files, convert documents to Markdown, and optimize media with ffmpeg/ImageMagick.
 
-Supports **Gemini** (analyze, transcribe, generate, Veo video), **MiniMax** (image, video, speech, music), and **OpenRouter** (image generation).
+Supports **Gemini** (analyze, transcribe, generate, Veo video, Flash TTS), **MiniMax** (image, video, speech, music), **OpenRouter** (image generation), **Leonardo.Ai** (image, video, upscale), and **BytePlus** (Seedream image, Seedance video, Hyper3D / Hitem3d 3D).
 
 ## Install
 
@@ -42,12 +42,24 @@ Set at least one provider key. Add to `.env` in your project root or `~/.multix/
 | `GEMINI_API_KEY` | For Gemini | [AI Studio](https://aistudio.google.com/apikey) |
 | `OPENROUTER_API_KEY` | For OpenRouter | [OpenRouter](https://openrouter.ai/settings/keys) |
 | `MINIMAX_API_KEY` | For MiniMax | [MiniMax](https://platform.minimax.io/user-center/basic-information/interface-key) |
+| `LEONARDO_API_KEY` | For Leonardo | [Leonardo](https://app.leonardo.ai/settings/api-keys) |
+| `LEONARDO_BASE_URL` | No | Override Leonardo API base (default `https://cloud.leonardo.ai/api/rest/v1`) |
+| `LEONARDO_DEFAULT_MODEL` | No | Default Leonardo image model UUID |
+| `LEONARDO_VIDEO_MODEL` | No | Default Leonardo video model (default `MOTION2`) |
+| `BYTEPLUS_API_KEY` | For BytePlus | [BytePlus](https://console.byteplus.com/auth/api-keys) |
+| `ARK_API_KEY` | No | Fallback for `BYTEPLUS_API_KEY` (Volcengine ARK shared name) |
+| `BYTEPLUS_BASE_URL` | No | Override BytePlus base (default `https://ark.ap-southeast.bytepluses.com/api/v3`) |
+| `BYTEPLUS_IMAGE_MODEL` | No | Default Seedream model (default `seedream-4-0-250828`) |
+| `BYTEPLUS_VIDEO_MODEL` | No | Default Seedance model (default `seedance-2.0`) |
+| `BYTEPLUS_VIDEO_PARAMS_MODE` | No | `flags` (default) or `structured` — how video params are encoded |
+| `BYTEPLUS_3D_MODEL` | No | Default 3D model (default `hyper3d-gen2-260112`) |
 | `MULTIX_OUTPUT_DIR` | No | Override default output dir (`./multix-output`) |
 | `OPENROUTER_IMAGE_MODEL` | No | Default OpenRouter model |
 | `OPENROUTER_FALLBACK_MODELS` | No | Comma-separated fallback model ids |
 | `IMAGE_GEN_MODEL` | No | Override Gemini image generation model |
 | `VIDEO_GEN_MODEL` | No | Override Gemini video generation model |
 | `MULTIMODAL_MODEL` | No | Override Gemini analysis model |
+| `GEMINI_TTS_MODEL` / `TTS_MODEL` | No | Override Gemini TTS model (default `gemini-3.1-flash-tts-preview`) |
 
 Priority: `process.env` > `cwd/.env` > `~/.multix/.env`.
 
@@ -78,23 +90,43 @@ multix gemini extract --files report.pdf --prompt "Extract tables as JSON" [--fo
 # Generate images
 multix gemini generate --prompt "A mountain lake" [--model <id>] [--aspect-ratio 16:9] [--num-images 1] [--size 1K|2K|4K] [--output <path>] [-v]
 
+# Image-to-image (Nano Banana — edit/compose from refs, alias: i2i)
+multix gemini image-to-image --prompt "make it watercolor" --ref ./photo.jpg [--ref ./style.png] [--model gemini-2.5-flash-image] [--output <path>] [-v]
+
 # Generate video [EXPERIMENTAL — requires billing]
 multix gemini generate-video --prompt "Ocean waves" [--model veo-3.1-generate-preview] [--resolution 720p|1080p] [--aspect-ratio 16:9] [--reference-images first.png last.png] [-v]
+
+# Image-to-video with Veo (alias: i2v) [EXPERIMENTAL]
+multix gemini image-to-video <imagePath> --prompt "camera pans left" [--last-frame <path>] [--model veo-3.1-generate-preview] [--resolution 1080p] [--aspect-ratio 16:9] [--output <path>] [-v]
+
+# Text-to-speech (Gemini 3.1 Flash TTS — single & multi-speaker)
+multix gemini generate-speech (--text|--prompt) "Say cheerfully: Have a wonderful day!" [--model gemini-3.1-flash-tts-preview] [--voice Kore] [--output-format wav|pcm] [--output <path>] [-v]
+
+# Multi-speaker (max 2): repeat --speaker name:voice; prompt should prefix lines with "<name>:"
+multix gemini generate-speech --text "Joe: How's it going? Jane: Not too bad!" \
+  --speaker Joe:Kore --speaker Jane:Puck
 ```
 
 **Gemini models:**
 - Analysis: `gemini-2.5-flash` (default)
 - Image gen: `gemini-3.1-flash-image-preview` (Nano Banana 2, fastest), `gemini-3-pro-image-preview` (4K text), `imagen-4.0-generate-001` (production)
 - Video: `veo-3.1-generate-preview` (requires billing)
+- TTS: `gemini-3.1-flash-tts-preview` (default), `gemini-2.5-flash-preview-tts`, `gemini-2.5-pro-preview-tts`
 
 **Aspect ratios:** `1:1 2:3 3:2 3:4 4:3 4:5 5:4 9:16 16:9 21:9`
 
+**TTS voices (30 prebuilt):** Zephyr, Puck, Charon, Kore, Fenrir, Leda, Orus, Aoede, Callirrhoe, Autonoe, Enceladus, Iapetus, Umbriel, Algieba, Despina, Erinome, Algenib, Rasalgethi, Laomedeia, Achernar, Alnilam, Schedar, Gacrux, Pulcherrima, Achird, Zubenelgenubi, Vindemiatrix, Sadachbia, Sadaltager, Sulafat. Audio is PCM s16le @ 24 kHz mono — saved as WAV (default) or raw PCM. Style is controlled via natural language in the prompt (`[whispers]`, `Say excitedly:`, etc.). No streaming; max 2 speakers; ~32k token context.
+
 ### `multix minimax`
 
 ```bash
 # Generate image
 multix minimax generate --prompt "A cat in space" [--model image-01] [--aspect-ratio 1:1] [--num-images 1] [-v]
 
+# Image-to-image (alias: i2i) — CAVEAT: subject_reference only, NOT free-form editing
+# Preserves a character/subject's identity in a NEW scene described by --prompt.
+multix minimax image-to-image --prompt "the same character on a beach" --ref ./hero.jpg [--model image-01] [-v]
+
 # Generate video (async, polls until done)
 multix minimax generate-video --prompt "A dancer" [--model MiniMax-Hailuo-2.3] [--duration 6|10] [--resolution 720P|1080P] [--first-frame <url>] [-v]
 
@@ -111,9 +143,113 @@ multix minimax generate-music [--lyrics <str>] [--prompt <str>] [--model music-2
 
 ```bash
 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]
+
+# 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]
+# alias: multix openrouter i2v --prompt "..." --image-url https://...
+
+# Poll a video job (use --download to fetch when completed)
+multix openrouter video-status <jobId> [--download] [--output <path>] [-v]
+
+# List available video models
+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`).
+
+### `multix leonardo`
+
+```bash
+# Account info / remaining credits
+multix leonardo me
+
+# List image platform models
+multix leonardo models [--limit <n>]
+
+# List video models (static enum)
+multix leonardo video-models
+
+# Generate images (polls until COMPLETE, downloads to MULTIX_OUTPUT_DIR)
+multix leonardo generate "a cyberpunk cat" [-m <modelId>] [-w 1024] [-h 1024] [-n 1] [--alchemy] [--ultra] [--style <uuid>] [--seed <n>] [--negative <text>] [--enhance] [--quality HIGH] [--output <path>] [--no-download] [--wait-timeout 480000] [-v]
+
+# Image-to-image (alias: i2i) — uses an existing Leonardo image id as init image
+# Direct upload from local path is not yet supported; pass an existing imageId.
+multix leonardo image-to-image --prompt "make it watercolor" --ref <imageId> [--image-type GENERATED|UPLOADED] [--init-strength 0.5] [-m <modelId>] [-w 1024] [-h 1024] [-n 1] [--seed <n>] [--negative <text>] [--output <path>] [--no-download] [-v]
+
+# Generate text-to-video (async — returns generationId)
+multix leonardo video "a dancer" [--model MOTION2|VEO3|kling-2.6|...] [--resolution RESOLUTION_720] [--enhance] [--frame-interpolation] [-v]
+
+# Generate image-to-video (async — returns generationId)
+multix leonardo image-to-video <imageId> --prompt "camera pans left" [--image-type GENERATED|UPLOADED] [--model MOTION2] [--resolution RESOLUTION_720] [--duration 6] [--seed <n>] [--negative <text>] [--enhance] [--frame-interpolation] [-v]
+# alias: multix leonardo i2v <imageId> --prompt "..."
+
+# Check a generation
+multix leonardo status <generationId>
+
+# Universal Upscaler (async)
+multix leonardo upscale <generatedImageId> [--style GENERAL] [--strength 0.35] [--multiplier 1.5]
+multix leonardo variation <variationId>
 ```
 
-Fallback models from `OPENROUTER_FALLBACK_MODELS` (CSV) are appended to the payload automatically.
+GPT Image models (`gpt-image-*`) and v2 video models (kling/hailuo/ltxv/seedance) are dispatched to Leonardo's `/api/rest/v2` endpoint automatically.
+
+### `multix byteplus`
+
+```bash
+# Image generation (Seedream 4.0, sync)
+multix byteplus generate --prompt "a cyberpunk cat" [--model seedream-4-0-250828] [--size 2K|1024x1024] [--aspect-ratio 16:9] [-n 1] [--seed <n>] [--no-watermark] [--input-image <path|url>] [--output <path>] [-v]
+
+# Image-to-image (alias: i2i) — Seedream with one or more reference images
+multix byteplus image-to-image --prompt "make it cyberpunk" --ref ./photo.jpg [--ref https://...] [--model seedream-4-0-250828] [--size 2K] [--aspect-ratio 16:9] [-n 1] [--seed <n>] [--no-watermark] [--output <path>] [-v]
+
+# Text-to-video (Seedance 2.0, async with auto-poll)
+multix byteplus video --prompt "ocean waves" [--model seedance-2.0|seedance-2.0-fast|seedance-2.0-pro] [--resolution 1080p] [--duration 8] [--aspect-ratio 16:9] [--audio|--no-audio] [--seed <n>] [--negative <text>] [--camera-fixed] [--async] [--wait-timeout 600000] [--output <path>] [-v]
+
+# Image-to-video (alias: i2v)
+multix byteplus image-to-video <imagePath|url> --prompt "camera pans left" [--last-frame <path|url>] [--model ...] [video flags] [-v]
+multix byteplus i2v ./photo.jpg --prompt "..."
+
+# Reference-to-video (alias: r2v) — up to 9 images + 3 videos + 3 audio refs (total ≤12)
+multix byteplus reference-to-video --prompt "..." \
+  --ref-image ./hero.jpg:subject \
+  --ref-image ./bg.jpg:environment \
+  --ref-video ./style.mp4:style \
+  --ref-audio ./music.mp3:audio \
+  [video flags] [-v]
+# On Windows, escape literal colons in paths with `\:` or use URLs.
+
+# 3D model generation (alias: 3d) — Hyper3D / Hitem3d, async with auto-poll + download
+multix byteplus generate-3d --prompt "Quadrupedal mech robot" \
+  --flags "--mesh_mode Raw --hd_texture true --material PBR" \
+  [--model hyper3d-gen2-260112] [--seed 8648] [--async] [--output model.glb] [-v]
+
+# Image-to-3D (1–5 reference images, path or URL)
+multix byteplus 3d --input-image ./front.png ./side.png ./back.png \
+  --prompt "Generate from these views" [--model hyper3d-gen2-260112]
+
+# Hitem3d uses different flags
+multix byteplus 3d --input-image ./cat.png --model hitem3d-2-0-251223 \
+  --flags "--ff 2 --resolution 1536pro"
+
+# Poll a task / download MP4
+multix byteplus status <taskId> [--wait] [--wait-timeout 600000] [--download] [--output <path>] [-v]
+```
+
+**BytePlus models:**
+- Image: `seedream-4-0-250828`
+- Video: `seedance-2.0-fast`, `seedance-2.0` (default), `seedance-2.0-pro`
+- 3D: `hyper3d-gen2-260112` (Hyper3D Gen2, default — text-to-3D + image-to-3D), `hitem3d-2-0-251223` (Hitem3d 2.0 — image-to-3D)
+
+**Notes:**
+- Auth: `BYTEPLUS_API_KEY` is preferred; `ARK_API_KEY` is accepted as a fallback for compatibility with the Volcengine ARK SDK ecosystem.
+- Video params can be encoded as flags inside the prompt text (default, e.g. `--rs 1080p --dur 8 --rt 16:9`) or as a top-level `parameters` object — set `BYTEPLUS_VIDEO_PARAMS_MODE=structured` to switch.
+- 3D model knobs are passed via `--flags <raw>`, appended to the prompt text. Hyper3D supports `--mesh_mode`, `--hd_texture`, `--material`, `--addons`, `--quality_override`, `--use_original_alpha`, `--bbox_condition`, `--TAPose`. Hitem3d supports `--ff`, `--resolution`. See [BytePlus 3D docs](https://docs.byteplus.com/en/docs/ModelArk/2279947).
+- 3D output is a textured model file (`.glb`/`.gltf`/`.zip` depending on flags). The CLI auto-detects the extension from the response URL.
+- `multix byteplus status <taskId> --download` works for both video (`content.video_url`) and 3D (`content.file_url`) tasks.
+- **Task cancellation is not supported** — there is no verified DELETE endpoint on the ARK API. Submitted tasks must run to completion.
 
 ### `multix media`
 
@@ -148,6 +284,22 @@ Multiple inputs are concatenated with `---` separators into a single output.
 
 All generated files are saved to `./multix-output/` by default. Override with `MULTIX_OUTPUT_DIR`.
 
+### Polling and downloading videos
+
+Every video-generating subcommand accepts a uniform set of polling/download flags:
+
+| Flag | Description |
+|------|-------------|
+| `--wait` | Poll the provider until the job reaches a terminal status (skip with the provider's `--async` flag where present). |
+| `--wait-timeout <ms>` | Polling timeout (default `600000` = 10 min). |
+| `--download` | Stream the resulting MP4 to disk on success — implies `--wait`. |
+| `--output <path>` | Copy the saved MP4 to a custom path. The thumbnail is copied beside it as `<base>_thumb.<ext>`. |
+| `--no-thumb` | Skip thumbnail download. |
+
+Thumbnail detection is automatic: if the provider response includes any of `cover_image_url`, `thumbnail_url`, `thumb_url`, `preview_url`, `first_frame_url`, `poster_url`, or `image_url` (and the value is an `https://…(.jpg|.png|.webp|.gif|.bmp)` URL), the file is downloaded next to the video as `<basename>_thumb.<ext>`. Providers that don't expose a thumbnail simply skip this step.
+
+`leonardo video`, `leonardo image-to-video`, and `openrouter image-to-video` are async-by-default for backward compatibility — pass `--wait` (or `--download`) to opt into the synchronous flow.
+
 ## Troubleshooting
 
 **No API key found:** Run `multix check` — it prints setup instructions.