@heyamiko/amiko-cli 0.16.3 → 0.16.4

package/README.md

@@ -879,16 +879,16 @@ Generate a video (Create Studio)
 
 | Flag | Default | Description |
 |---|---|---|
-| `--model <model>` |  | Video model: MiniMax-Hailuo-02 (default for prompt-only; T2V+I2V), MiniMax-Hailuo-2.3-Fast (default with --first-frame; I2V only), MiniMax-Hailuo-2.3 (T2V+I2V), MiniMax-H3 (aliases h3, hailuo-03; T2V+I2V+reference-to-video, 768P\|2K, any 4–15s, billed per second), veo-3.1[-fast\|-lite]-generate-preview (Google; durations clamp to 4/6/8s), grok-imagine-video (xAI), dreamina-seedance-2-5-260628 (BytePlus Seedance 2.5; any whole 4–30s, billed per token so a long 1080p clip runs into dollars — quote it), other dreamina-seedance-* (BytePlus, ≤15s). ONLY these — kling and other ids are not supported |
+| `--model <model>` |  | Video model: MiniMax-Hailuo-02 (default for prompt-only; T2V+I2V), MiniMax-Hailuo-2.3-Fast (default with --first-frame; I2V only), MiniMax-Hailuo-2.3 (T2V+I2V), S2V-01 (default with --subject-reference; the only MiniMax model that accepts subject_reference), MiniMax-H3 (aliases h3, hailuo-03; T2V+I2V+reference-to-video, 768P\|2K, any 4–15s, billed per second), veo-3.1[-fast\|-lite]-generate-preview (Google; durations clamp to 4/6/8s), grok-imagine-video (xAI), dreamina-seedance-2-5-260628 (BytePlus Seedance 2.5; any whole 4–30s, billed per token so a long 1080p clip runs into dollars — quote it), other dreamina-seedance-* (BytePlus, ≤15s). ONLY these — kling and other ids are not supported |
 | `--resolution <res>` | `768P` | 512P, 720P, 768P, 1080P (MiniMax, Grok, Seedance); 720p, 1080p, 4k (Veo); 768P or 2K (MiniMax-H3) |
 | `--seconds <n>` | `6` | Clip length: 6 or 10 (Hailuo), 4/6/8 (Veo), 4/6/8/10 (Grok, Seedance 2.0), any whole number 4–15 (MiniMax-H3), any whole number 4–30 (Seedance 2.5) |
 | `--aspect <ratio>` |  | Aspect ratio (provider-dependent). MiniMax-H3 text-to-video needs a concrete ratio (21:9, 16:9, 4:3, 1:1, 3:4, 9:16); defaults to 16:9 when omitted |
 | `--first-frame <file|url>` |  | Image-to-video: first frame — local file path, https URL, or data URI |
 | `--last-frame <file|url>` |  | First-and-last-frame video: ending frame — local file path, https URL, or data URI. MiniMax-H3, Seedance and Veo only (Seedance/Veo also need --first-frame) |
-| `--reference-image <file|url>` |  | Reference-to-video: local file path or https URL (repeatable). MiniMax-H3 / Seedance / Grok: max 9; Veo: max 3; Hailuo v1: NOT supported — use --subject-reference |
+| `--reference-image <file|url>` |  | Reference-to-video: local file path or https URL (repeatable). MiniMax-H3 / Seedance / Grok: max 9; Veo: max 3; Hailuo v1: NOT supported — use --model MiniMax-H3 |
 | `--reference-video <file|url>` |  | Reference-to-video: local file path or https URL (repeatable, max 3). MiniMax-H3 and Seedance only; combined reference video+audio must be ≤15s, and H3 bills 15 input-seconds whenever any is attached |
 | `--reference-audio <file|url>` |  | Reference-to-video: local file path or https URL (repeatable, max 3). MiniMax-H3 and Seedance only; needs an image or video reference alongside, H3 wants 2–15s per clip |
-| `--subject-reference <file|url>` |  | MiniMax S2V / H3: subject/character reference image — local file path or https URL. Takes the place of --reference-image rather than adding to it |
+| `--subject-reference <file|url>` |  | Subject/character reference image — local file path or https URL. Takes the place of --reference-image rather than adding to it. Selects S2V-01 unless --model says otherwise; Hailuo 02/2.3/2.3-Fast reject it, use MiniMax-H3 for reference-to-video |
 | `--generate-audio` |  | Seedance: generate audio in the output video |
 | `--no-generate-audio` |  | Seedance: output silent video |
 | `--watermark` |  | Seedance: burn in a watermark |
@@ -2617,6 +2617,13 @@ npm publish
 
 ## Changelog
 
+### 0.16.4
+
+- **`--subject-reference` now works at all.** MiniMax accepts `subject_reference` on **S2V-01 and nothing else**, so every job that used the flag was rejected upstream with `param 'subject_reference' is incompatible with model MiniMax-Hailuo-02` — including the CLI's own documented example, because with no `--model` the flag resolved to exactly that id. The flag now selects `S2V-01` on its own (checked before `--first-frame`: the model follows the reference, not the frame), and naming a Hailuo model beside it is refused **before the quote**, with an error that points at `--model S2V-01` or `--model MiniMax-H3`. This corrects the 0.16.1 note below, which said Hailuo v1 accepts the flag — it reads the field's *shape*, but MiniMax rejects the *pairing*.
+- **A permanently-invalid model/flag pairing answers 400, not 502.** It had no branch in the video error classifier, so it took the 502 default — which reads "transient, retry", and callers were resubmitting a request that can never succeed.
+- **`--seconds` help no longer cites the one table Seedance 2.5 isn't subject to.** It still read "4/6/8/10 (Grok, Seedance)" after 2.5 gained its 4–30s range. The README command reference is generated from that string, so both were wrong together.
+- **Reference video and audio counts are enforced, not just images.** The validator capped images at 9 but let any number of clips through. The CLI and the studio both apply 3/3, so only a direct API caller reached it — where BytePlus either rejects after the reservation is taken, or accepts, silently drops the extras, and bills for what it ran.
+
 ### 0.16.3
 
 - **Seedance 2.5 (`dreamina-seedance-2-5-260628`) is a supported `create video --model`**, and it is the only model that goes past 15s — any whole `--seconds` from **4 to 30**. The 4|6|8|10 set never applied to it, and neither does H3's 4–15 range, so `--seconds 22` is now accepted rather than rejected against a table it was never subject to.

package/dist/index.js

@@ -29399,6 +29399,11 @@ var VIDEO_CAPS = {
     label: "MiniMax Hailuo"
   }
 };
+function acceptsSubjectReference(model) {
+  if (videoFamily(model) !== "hailuo")
+    return true;
+  return /^S2V-/i.test(model);
+}
 function effectiveReferenceImageCount(input) {
   if (VIDEO_CAPS[videoFamily(input.model)].subjectReferenceNative) {
     return input.referenceImageUrls.length;
@@ -29411,8 +29416,11 @@ function validateVideoReferences(input) {
   const images = effectiveReferenceImageCount(input);
   const videos = input.referenceVideoUrls.length;
   const audio = input.referenceAudioUrls.length;
+  if (input.subjectReference && !acceptsSubjectReference(input.model)) {
+    return `${caps.label} rejects --subject-reference: MiniMax accepts subject_reference on S2V-01 only, and ${input.model} fails the submit with "param 'subject_reference' is incompatible with model ${input.model}". Use --model S2V-01, or --model MiniMax-H3 for reference-to-video, or --first-frame to start from an image.`;
+  }
   if (input.referenceImageUrls.length > 0 && caps.referenceImages === 0) {
-    return `${caps.label} ignores --reference-image — mpp's ${family} branch never reads it, so the video would be generated and billed without it. Use --subject-reference for a single character image, or --model MiniMax-H3 for true reference-to-video.`;
+    return `${caps.label} ignores --reference-image — mpp's ${family} branch never reads it, so the video would be generated and billed without it. Use --model S2V-01 with --subject-reference for a single character image, or --model MiniMax-H3 for true reference-to-video.`;
   }
   if (videos > 0 && caps.referenceVideos === 0) {
     return `${caps.label} ignores --reference-video — it would be dropped and the job billed anyway. Only MiniMax-H3 and Seedance read reference clips.`;
@@ -29972,8 +29980,8 @@ function registerCreateCommand(create2) {
       }
     });
   });
-  create2.command("video <prompt>").description("Generate a video (Create Studio)").option("--model <model>", "Video model: MiniMax-Hailuo-02 (default for prompt-only; T2V+I2V), MiniMax-Hailuo-2.3-Fast (default with --first-frame; I2V only), MiniMax-Hailuo-2.3 (T2V+I2V), MiniMax-H3 (aliases h3, hailuo-03; T2V+I2V+reference-to-video, 768P|2K, any 4–15s, billed per second), veo-3.1[-fast|-lite]-generate-preview (Google; durations clamp to 4/6/8s), grok-imagine-video (xAI), dreamina-seedance-2-5-260628 (BytePlus Seedance 2.5; any whole 4–30s, billed per token so a long 1080p clip runs into dollars — quote it), other dreamina-seedance-* (BytePlus, ≤15s). ONLY these — kling and other ids are not supported").option("--resolution <res>", "512P, 720P, 768P, 1080P (MiniMax, Grok, Seedance); 720p, 1080p, 4k (Veo); 768P or 2K (MiniMax-H3)", "768P").option("--seconds <n>", "Clip length: 6 or 10 (Hailuo), 4/6/8 (Veo), 4/6/8/10 (Grok, Seedance 2.0), any whole number 4–15 (MiniMax-H3), any whole number 4–30 (Seedance 2.5)", "6").option("--aspect <ratio>", "Aspect ratio (provider-dependent). MiniMax-H3 text-to-video needs a concrete ratio (21:9, 16:9, 4:3, 1:1, 3:4, 9:16); defaults to 16:9 when omitted").option("--first-frame <file|url>", "Image-to-video: first frame — local file path, https URL, or data URI").option("--last-frame <file|url>", "First-and-last-frame video: ending frame — local file path, https URL, or data URI. MiniMax-H3, Seedance and Veo only (Seedance/Veo also need --first-frame)").option("--reference-image <file|url>", "Reference-to-video: local file path or https URL (repeatable). MiniMax-H3 / Seedance / Grok: max 9; Veo: max 3; Hailuo v1: NOT supported — use --subject-reference", collectOption, []).option("--reference-video <file|url>", "Reference-to-video: local file path or https URL (repeatable, max 3). MiniMax-H3 and Seedance only; combined reference video+audio must be ≤15s, and H3 bills 15 input-seconds whenever any is attached", collectOption, []).option("--reference-audio <file|url>", "Reference-to-video: local file path or https URL (repeatable, max 3). MiniMax-H3 and Seedance only; needs an image or video reference alongside, H3 wants 2–15s per clip", collectOption, []).option("--subject-reference <file|url>", "MiniMax S2V / H3: subject/character reference image — local file path or https URL. Takes the place of --reference-image rather than adding to it").option("--generate-audio", "Seedance: generate audio in the output video").option("--no-generate-audio", "Seedance: output silent video").option("--watermark", "Seedance: burn in a watermark").option("--no-watermark", "Seedance: no watermark").option("--camera-fixed", "Seedance: hold the camera still").option("--no-camera-fixed", "Seedance: allow camera movement").option("--prompt-optimizer", "MiniMax (H3 and Hailuo v1): let the model rewrite the prompt before generating").option("--no-prompt-optimizer", "MiniMax: use the prompt verbatim").option("--fast-pretreatment", "MiniMax Hailuo v1: faster input pre-processing (ignored by H3, Veo, Grok and Seedance)").option("--no-fast-pretreatment", "MiniMax Hailuo v1: standard input pre-processing").option("--token <symbol>", "Preferred charge token: AMIKO, USDC, USDT, SOL").option("--pay <method>", "Payment method: credits (Amiko account credits, default) or wallet (twin wallet)", "credits").option("--raw", "Output raw JSON").option("--yes", "Skip the pre-spend confirmation (required in non-interactive shells)").action(async (prompt, opts) => {
-    const model = opts.model ?? (opts.firstFrame ? "MiniMax-Hailuo-2.3-Fast" : "MiniMax-Hailuo-02");
+  create2.command("video <prompt>").description("Generate a video (Create Studio)").option("--model <model>", "Video model: MiniMax-Hailuo-02 (default for prompt-only; T2V+I2V), MiniMax-Hailuo-2.3-Fast (default with --first-frame; I2V only), MiniMax-Hailuo-2.3 (T2V+I2V), S2V-01 (default with --subject-reference; the only MiniMax model that accepts subject_reference), MiniMax-H3 (aliases h3, hailuo-03; T2V+I2V+reference-to-video, 768P|2K, any 4–15s, billed per second), veo-3.1[-fast|-lite]-generate-preview (Google; durations clamp to 4/6/8s), grok-imagine-video (xAI), dreamina-seedance-2-5-260628 (BytePlus Seedance 2.5; any whole 4–30s, billed per token so a long 1080p clip runs into dollars — quote it), other dreamina-seedance-* (BytePlus, ≤15s). ONLY these — kling and other ids are not supported").option("--resolution <res>", "512P, 720P, 768P, 1080P (MiniMax, Grok, Seedance); 720p, 1080p, 4k (Veo); 768P or 2K (MiniMax-H3)", "768P").option("--seconds <n>", "Clip length: 6 or 10 (Hailuo), 4/6/8 (Veo), 4/6/8/10 (Grok, Seedance 2.0), any whole number 4–15 (MiniMax-H3), any whole number 4–30 (Seedance 2.5)", "6").option("--aspect <ratio>", "Aspect ratio (provider-dependent). MiniMax-H3 text-to-video needs a concrete ratio (21:9, 16:9, 4:3, 1:1, 3:4, 9:16); defaults to 16:9 when omitted").option("--first-frame <file|url>", "Image-to-video: first frame — local file path, https URL, or data URI").option("--last-frame <file|url>", "First-and-last-frame video: ending frame — local file path, https URL, or data URI. MiniMax-H3, Seedance and Veo only (Seedance/Veo also need --first-frame)").option("--reference-image <file|url>", "Reference-to-video: local file path or https URL (repeatable). MiniMax-H3 / Seedance / Grok: max 9; Veo: max 3; Hailuo v1: NOT supported — use --model MiniMax-H3", collectOption, []).option("--reference-video <file|url>", "Reference-to-video: local file path or https URL (repeatable, max 3). MiniMax-H3 and Seedance only; combined reference video+audio must be ≤15s, and H3 bills 15 input-seconds whenever any is attached", collectOption, []).option("--reference-audio <file|url>", "Reference-to-video: local file path or https URL (repeatable, max 3). MiniMax-H3 and Seedance only; needs an image or video reference alongside, H3 wants 2–15s per clip", collectOption, []).option("--subject-reference <file|url>", "Subject/character reference image — local file path or https URL. Takes the place of --reference-image rather than adding to it. Selects S2V-01 unless --model says otherwise; Hailuo 02/2.3/2.3-Fast reject it, use MiniMax-H3 for reference-to-video").option("--generate-audio", "Seedance: generate audio in the output video").option("--no-generate-audio", "Seedance: output silent video").option("--watermark", "Seedance: burn in a watermark").option("--no-watermark", "Seedance: no watermark").option("--camera-fixed", "Seedance: hold the camera still").option("--no-camera-fixed", "Seedance: allow camera movement").option("--prompt-optimizer", "MiniMax (H3 and Hailuo v1): let the model rewrite the prompt before generating").option("--no-prompt-optimizer", "MiniMax: use the prompt verbatim").option("--fast-pretreatment", "MiniMax Hailuo v1: faster input pre-processing (ignored by H3, Veo, Grok and Seedance)").option("--no-fast-pretreatment", "MiniMax Hailuo v1: standard input pre-processing").option("--token <symbol>", "Preferred charge token: AMIKO, USDC, USDT, SOL").option("--pay <method>", "Payment method: credits (Amiko account credits, default) or wallet (twin wallet)", "credits").option("--raw", "Output raw JSON").option("--yes", "Skip the pre-spend confirmation (required in non-interactive shells)").action(async (prompt, opts) => {
+    const model = opts.model ?? (opts.subjectReference ? "S2V-01" : opts.firstFrame ? "MiniMax-Hailuo-2.3-Fast" : "MiniMax-Hailuo-02");
     const isH3 = isH3VideoModel(model);
     const seconds = Number(opts.seconds);
     if (isH3) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyamiko/amiko-cli",
-  "version": "0.16.3",
+  "version": "0.16.4",
   "description": "Amiko CLI — swap tokens, manage credits, bridge cross-chain, and call marketplace agents",
   "type": "module",
   "bin": {

package/skills/SKILL.md

@@ -231,7 +231,7 @@ This twin has **two** optional TTS ids. They are **not** the same:
 | Image-to-video (single start frame) | `create image "cover art" --yes` → later `create status <jobId>` for URL → `create video "animate this" --first-frame <url> --yes` |
 | First + last frame | `create video "morph between frames" --first-frame <startUrl> --last-frame <endUrl> --yes` |
 | Seedance multimodal refs | `create video "dance to this beat" --model dreamina-seedance-2-0-fast-260128 --reference-image <url> --reference-audio ./beat.wav --generate-audio --yes` (repeat `--reference-image` up to 9×, `--reference-video`/`--reference-audio` up to 3×) |
-| MiniMax subject reference (S2V) | `create video "character walks forward" --subject-reference <portraitUrl> --yes` |
+| MiniMax subject reference (S2V) | `create video "character walks forward" --model S2V-01 --subject-reference <portraitUrl> --yes` — **`S2V-01` is the only MiniMax model that accepts `subject_reference`**; passing `--subject-reference` alone now selects it for you, but naming any Hailuo model beside it is rejected up front |
 | MiniMax H3 long clip (per-second billing) | `create video "slow pan over dunes at dusk" --model MiniMax-H3 --seconds 12 --resolution 2K --aspect 21:9 --yes` — quote first; cost scales with `--seconds`, and 2K bills more per second than 768P |
 | MiniMax H3 reference-to-video | `create video "same character, now dancing" --model MiniMax-H3 --reference-image <url> --reference-video ./clip.mp4 --yes` — never mix `--first-frame`/`--last-frame` with reference flags on H3; the CLI/server reject the combination |
 
@@ -243,11 +243,12 @@ This twin has **two** optional TTS ids. They are **not** the same:
 | **Seedance** | 9 | 3 | 3 | both, `--last-frame` needs `--first-frame` | frames exclusive with image/video references; audio needs an image or video reference beside it; video+audio combined ≤15s |
 | **Veo 3.1** | 3 | — | — | both, `--last-frame` needs `--first-frame` | frames exclusive with references; `-lite` is prompt-only |
 | **Grok** | 9 | — | — | `--first-frame` only | |
-| **Hailuo v1** (02 / 2.3 / 2.3-Fast) | — | — | — | `--first-frame` only | `--reference-image` is silently dropped — use `--subject-reference`, which Hailuo does read |
+| **Hailuo v1** (02 / 2.3 / 2.3-Fast) | — | — | — | `--first-frame` only | takes **no** reference media: `--reference-image` is silently dropped, and `--subject-reference` is rejected by MiniMax. Want a character reference? `--model S2V-01`, or `--model MiniMax-H3` for reference-to-video |
+| **S2V-01** | — | — | — | `--subject-reference` only | the one MiniMax model with `subject_reference`; one portrait, no other reference media, no frames |
 
 Seedance 2.5 advertises up to **50** multimodal references upstream, but the CLI, the studio and mpp all still cap it at 9/3/3 with the ≤15s reference budget — BytePlus has not published what the longer-reference rules become at that ceiling, and a cap we can't verify is one that fails by generating and billing. Don't promise the owner 50; 2.5's usable win today is **duration** (30s vs 15s), not reference count.
 
-`--subject-reference` **replaces** a reference-image slot rather than adding one (except on Hailuo v1, where it's a separate field). The ≤15s combined budget and H3's 2–15s per-clip audio window are checked from the **local file's bytes** — so they're verified for `.wav` / `.mp4` / `.mov` paths and skipped (allowed through) for https URLs and `.mp3`, where the server has the last word.
+`--subject-reference` **replaces** a reference-image slot rather than adding one, and only `S2V-01` reads it — every other MiniMax model fails the submit with `param 'subject_reference' is incompatible with model …`. The CLI refuses that pairing before the quote, so it costs nothing; it's still the wrong flag to reach for on Hailuo 02/2.3/2.3-Fast. The ≤15s combined budget and H3's 2–15s per-clip audio window are checked from the **local file's bytes** — so they're verified for `.wav` / `.mp4` / `.mov` paths and skipped (allowed through) for https URLs and `.mp3`, where the server has the last word.
 
 **Provider toggles** (each has a `--no-…` form): `--generate-audio`, `--watermark`, `--camera-fixed` (Seedance); `--prompt-optimizer` (MiniMax H3 + Hailuo v1); `--fast-pretreatment` (Hailuo v1). Passing one to a model that ignores it is harmless — the server drops it.