diff --git a/skill/SKILL.md b/skill/SKILL.md
index a6c3ee8..5c7c3cf 100644
--- a/skill/SKILL.md
+++ b/skill/SKILL.md
@@ -117,7 +117,9 @@ mmx image generate --prompt "Logo" --n 3 --out-dir ./gen/ --quiet
 
 ### video generate
 
-Generate video. Default model: `MiniMax-Hailuo-2.3`. Select `MiniMax-H3` to use the Video Generation V2 multimodal API. This is an async task — by default it polls until completion.
+Generate video. Default model: `MiniMax-Hailuo-2.3` (or `MiniMax-Hailuo-2.3-Fast` for fast mode with `--image`). This is an async task — by default it polls until completion.
+
+For `MiniMax-H3` — text-to-video, first/last-frame, multimodal reference image/video/audio generation, prompt construction, and failure handling — use the dedicated [mmx-h3-video skill](h3-video/SKILL.md) instead.
 
 ```bash
 mmx video generate --prompt <text> [flags]
@@ -126,14 +128,9 @@ mmx video generate --prompt <text> [flags]
 | Flag | Type | Description |
 |---|---|---|
 | `--prompt <text>` | string, **required** | Video description |
-| `--model <model>` | string | `MiniMax-Hailuo-2.3` (default), `MiniMax-Hailuo-2.3-Fast`, or `MiniMax-H3` |
+| `--model <model>` | string | `MiniMax-Hailuo-2.3` (default) or `MiniMax-Hailuo-2.3-Fast` |
 | `--image <path-or-url>` | string | Input image for image-to-video |
-| `--last-frame <path-or-url>` | string | Last frame image; H3 supports last-frame-only input |
-| `--reference-image <path-or-url>` | string, repeatable | H3 reference image |
-| `--reference-video <path-or-url>` | string, repeatable | H3 reference video |
-| `--reference-audio <path-or-url>` | string, repeatable | H3 reference audio; requires a reference image or video |
-| `--duration <seconds>` | number | H3 duration, 4-15 seconds (default: 5) |
-| `--ratio <ratio>` | string | H3 output ratio; T2V cannot use `adaptive` |
+| `--last-frame <path-or-url>` | string | Optional ending image for frame interpolation (used with `--image`) |
 | `--callback-url <url>` | string | Webhook URL for completion |
 | `--download <path>` | string | Save video to specific file |
 | `--async` | boolean | Return task ID immediately |
@@ -145,18 +142,6 @@ mmx video generate --prompt <text> [flags]
 mmx video generate --prompt "A robot." --async --quiet
 # stdout: {"taskId":"..."}
 
-# H3 text-to-video
-mmx video generate --model MiniMax-H3 --prompt "Ocean waves." --async --quiet
-
-# H3 image-to-video
-mmx video generate --model MiniMax-H3 --prompt "The subject walks forward." \
-  --image start.jpg --async --quiet
-
-# H3 reference-to-video
-mmx video generate --model MiniMax-H3 --prompt "Keep the same character." \
-  --reference-image character.png \
-  --reference-video motion.mp4 --async --quiet
-
 # Blocking: wait and get file path
 mmx video generate --prompt "Ocean waves." --download ocean.mp4 --quiet
 # stdout: ocean.mp4
diff --git a/skill/h3-video/SKILL.md b/skill/h3-video/SKILL.md
new file mode 100644
index 0000000..273a92e
--- /dev/null
+++ b/skill/h3-video/SKILL.md
@@ -0,0 +1,221 @@
+---
+name: mmx-h3-video
+description: Generate, monitor, and download MiniMax-H3 videos through the mmx CLI. Use for H3 text-to-video, first/last-frame video, multimodal reference image/video/audio generation, H3 prompt improvement, media preflight, Pay-as-you-go API key selection, task waiting, downloads, and H3 failure handling.
+---
+
+# MiniMax-H3 Video With MMX
+
+Use this skill only for `MiniMax-H3` video generation. Do not handle text, image generation, speech, music, search, legacy Hailuo models, or unrelated MMX commands.
+
+Before a paid request, read `references/h3-video.md` for prompt construction, media constraints, waiting behavior, and failure handling.
+
+## Required Rules
+
+1. Use a Pay-as-you-go/Credit API Key. H3 does not use OAuth or Token Plan Subscription Keys.
+2. Reuse a saved MMX API key when available. Never print, repeat, or place a literal API key in a command transcript.
+3. Always pass `--model MiniMax-H3`; never rely on the configured default model.
+4. For a completed video, run one direct blocking `mmx video generate` command. Do not use Bash wrappers or hand-written polling loops.
+5. If the terminal command remains active, wait on that exact execution session. Do not run `ps`, scrape process arguments, inspect the output repeatedly, kill the process, or submit another task.
+6. Treat `Detecting region... cn` or `Detecting region... global` as normal stderr progress, not a submission failure.
+7. Never submit a replacement paid task because terminal waiting, status polling, or downloading was interrupted.
+8. Retry the alternate region at most once, and only when the first command clearly failed before task creation because of region detection, endpoint, or authentication routing.
+9. Use `--async` only when the user explicitly wants a task ID without waiting or downloading.
+
+## Resolve The CLI
+
+Inside the `minimax-cli` repository, build changes and use the local artifact:
+
+```bash
+bun run build
+node ./dist/mmx.mjs video generate --help
+```
+
+Outside the repository, use the installed `mmx` executable. Do not install or update MMX unless the user asks.
+
+In commands below, replace `mmx` with `node ./dist/mmx.mjs` when testing the local repository build.
+
+## Resolve And Save The API Key
+
+Before the first paid H3 request, inspect the active credential without exposing it:
+
+```bash
+mmx auth status --output json --quiet
+```
+
+- If `method` is `api-key`, reuse it from MMX config. Do not add `--api-key` to generation commands.
+- If the user already supplied a key and the runtime holds it securely as `MINIMAX_API_KEY`, save it once, then use MMX config:
+
+```bash
+mmx config set --key api_key --value "$MINIMAX_API_KEY" --quiet
+```
+
+- Saving `api_key` replaces stale OAuth credentials, clears the cached region, and stores the key in `~/.mmx/config.json` with owner-only permissions.
+- Never reconstruct a previously supplied key into visible shell text. Use the runtime's secret/environment injection when available.
+- If no saved API key or securely injected variable is available, ask the user to run `mmx auth login` and choose API key. Do not ask them to paste the key into chat again.
+- After saving, future Agent commands must omit both the literal key and `--api-key`.
+
+## Default Completed-Video Path
+
+Use this path when the user wants the final file:
+
+```bash
+mmx video generate \
+  --model MiniMax-H3 \
+  --prompt "<video prompt>" \
+  --duration <4-15> \
+  --download <output.mp4> \
+  --poll-interval 10 \
+  --timeout 1800 \
+  --non-interactive
+```
+
+This one CLI process submits exactly one task, waits internally between status checks, and downloads the completed video. When the execution tool returns a running session or cell ID, continue waiting on that same session until it exits.
+
+Do not add `--async` to this command. Async mode returns before download handling.
+
+## Input Modes
+
+Use exactly one mode per request.
+
+### Text-To-Video
+
+```bash
+mmx video generate \
+  --model MiniMax-H3 \
+  --prompt "A cinematic coastal sunset, slow dolly forward" \
+  --duration 15 \
+  --ratio 16:9 \
+  --download ./result.mp4 \
+  --poll-interval 10 \
+  --timeout 1800 \
+  --non-interactive
+```
+
+### First/Last-Frame Video
+
+`--image` is the first frame. It may be combined with one `--last-frame`.
+
+```bash
+mmx video generate \
+  --model MiniMax-H3 \
+  --prompt "The subject walks naturally from the starting pose to the ending pose" \
+  --image ./start.png \
+  --last-frame ./end.png \
+  --duration 15 \
+  --download ./result.mp4 \
+  --poll-interval 10 \
+  --timeout 1800 \
+  --non-interactive
+```
+
+Do not use the hidden `--first-frame` compatibility alias in new commands.
+
+### Multimodal Reference Video
+
+Repeat each reference flag to pass multiple inputs. Do not comma-separate paths.
+
+```bash
+mmx video generate \
+  --model MiniMax-H3 \
+  --prompt "Preserve the referenced character, follow the motion and audio rhythm" \
+  --reference-image ./character-1.png \
+  --reference-image ./character-2.png \
+  --reference-video ./motion.mp4 \
+  --reference-audio ./rhythm.mp3 \
+  --duration 15 \
+  --download ./result.mp4 \
+  --poll-interval 10 \
+  --timeout 1800 \
+  --non-interactive
+```
+
+Frame mode cannot be mixed with reference mode. Reference audio requires at least one reference image or reference video.
+
+## Region Recovery
+
+Omit `--region` on the first request so MMX can use or detect the key's region. If that command fails, retry the same request once with the alternate region only when all of these are true:
+
+1. No `taskId` was returned.
+2. `[Model: MiniMax-H3]` was not printed, so the CLI did not confirm task creation.
+3. The error explicitly concerns region detection, a regional endpoint, or a pre-submission 401/403 authentication-routing mismatch.
+
+Use `--region global` after a failed `cn` attempt, or `--region cn` after a failed `global` attempt. Keep every generation argument unchanged. If the alternate region succeeds, persist it without exposing credentials:
+
+```bash
+mmx config set --key region --value <global-or-cn> --quiet
+```
+
+Do not perform region fallback for validation errors, error `2013`, billing, rate limits, sensitive content, generic service errors, or an ambiguous timeout. Never region-retry after task creation, during polling, or during download.
+
+## Core Limits
+
+- Prompt: at most 7000 characters.
+- Output duration: integer from 4 through 15 seconds.
+- Resolution: 2K.
+- Reference images: at most 9.
+- Reference videos: at most 3.
+- Reference audios: at most 3.
+- Mixed reference items: at most 12 total.
+- Local image: at most 30 MB each.
+- Local video: MP4, at most 50 MB each.
+- Local audio: MP3 or WAV, at most 15 MB each.
+- Complete local Base64 request body: at most 64 MB.
+
+Use URLs or `mm_file://<file-id>` for large or numerous assets. Read `references/h3-video.md` for official duration, codec, frame-rate, dimension, and aspect-ratio limits that are not fully validated by the CLI.
+
+## Async Task-ID Path
+
+Use this only when the user wants immediate submission and a task ID:
+
+```bash
+mmx video generate \
+  --model MiniMax-H3 \
+  --prompt "<video prompt>" \
+  --duration <4-15> \
+  --async \
+  --output json \
+  --non-interactive
+```
+
+Return and retain the `taskId`, then stop. Do not automatically monitor or download it. MMX does not provide a task-list command or persist local task history.
+
+## Prompt Handling
+
+Preserve the user's intent. Write the prompt in the user's language. When a prompt is too short, expand it once using:
+
+1. Duration, ratio, and use case.
+2. Subjects and reference mapping.
+3. Chronological actions.
+4. Scene, lighting, weather, and background.
+5. Shot size, angle, camera motion, focus, and cuts.
+6. Style, color, mood, and pacing.
+7. Dialogue, ambience, music, and audio synchronization.
+8. Elements to preserve and artifacts to avoid.
+
+For two or more ordered reference images, use a structured storyboard prompt instead of one prose paragraph:
+
+1. Output specification and ordered reference count.
+2. Global visual style and continuity rules.
+3. Locked character identity, wardrobe, position, and props.
+4. A contiguous master timeline mapped to `reference image 1`, `reference image 2`, and so on.
+5. A micro-timeline inside each shot: establish, prepare, execute, settle/hold, and end-state lock.
+6. Explicit action and object-state transitions for handoffs or other precise motion.
+7. Sound requirements and a final negative-constraint block.
+
+Use two timeline levels. The master timeline divides the full clip into shots. Each shot then divides its own interval into timestamped micro-beats. A shot may contain several phases, but they must form one causal action beat. Every shot must state its exact range, duration, reference image, initial state, camera behavior, micro-beats, and locked end state. The next shot's initial state must equal the previous locked end state.
+
+Master and micro intervals must cover their parent duration without gaps or overlaps, and reference numbering must match the repeated `--reference-image` flag order. Keep the action achievable within 4-15 seconds. Do not silently add brands, celebrities, dialogue, text overlays, or unsafe content. Use the detailed Chinese and English templates in `references/h3-video.md`.
+
+If the user already provides a complete structured storyboard prompt, do not summarize, shorten, translate, or stylistically rewrite it. Check only the 7000-character limit, duration coverage, reference count/order, media-mode compatibility, and contradictory constraints; preserve the original wording unless a correction is required.
+
+## Failure Handling
+
+- Wrong Token Plan/OAuth credential or H3 error `2013`: stop and request a compatible Pay-as-you-go API Key.
+- Clear pre-submission region-routing failure: retry the unchanged command once with the alternate `--region`; never retry after task creation.
+- Authentication, balance, or sensitive-content errors: stop and report the exact error without retrying or silently changing the request.
+- A running terminal session: keep waiting on the same session; absence of a final path is not failure.
+- Terminal task status `failed`, `cancelled`, or `expired`: report the status and task error; require approval before another paid submission.
+- Polling timeout: report the task ID when available; do not submit a duplicate.
+- Download failure after success: retry the same result download only; never regenerate the video.
+
+Read the complete failure matrix in `references/h3-video.md` before recovery.
diff --git a/skill/h3-video/references/h3-video.md b/skill/h3-video/references/h3-video.md
new file mode 100644
index 0000000..9b3f565
--- /dev/null
+++ b/skill/h3-video/references/h3-video.md
@@ -0,0 +1,186 @@
+# MiniMax-H3 Video Agent Guide
+
+Read this reference before submitting a `MiniMax-H3` request. It covers rules that are not fully exposed by CLI flags.
+
+## Credential Rule
+
+- Use a standard Pay-as-you-go/Credit API Key for H3.
+- Do not use an OAuth credential or Token Plan Subscription Key for H3.
+- Run `mmx auth status --output json --quiet` before the first paid request. It reports the credential method and only a masked key.
+- Prefer an API key already saved in MMX config. Generation commands should not contain `--api-key`.
+- If the runtime securely holds a previously supplied key as `MINIMAX_API_KEY`, save it once with `mmx config set --key api_key --value "$MINIMAX_API_KEY" --quiet`.
+- Never print, repeat, or reconstruct a literal key in shell text. If secure injection is unavailable, ask the user to run interactive `mmx auth login` instead of pasting the key into chat again.
+- MMX stores config with owner-only permissions. Saving `api_key` removes stale OAuth credentials and clears the cached region for fresh detection.
+- If error `2013` says TokenPlan or Credit does not support H3, stop. Select a compatible Pay-as-you-go API Key instead of changing the prompt or media.
+
+## Region Selection And Fallback
+
+- Omit `--region` initially. MMX uses the saved region or detects it after a new API key is saved.
+- `Detecting region... cn` and `Detecting region... global` are normal progress messages.
+- Retry the alternate region at most once only when the command clearly failed before task creation because of region detection, a regional endpoint, or a pre-submission 401/403 routing mismatch.
+- Absence of both a `taskId` and `[Model: MiniMax-H3]` is required before retrying creation. If either appeared, assume a paid task may exist and do not resubmit.
+- Keep the request identical and add only `--region global` after `cn`, or `--region cn` after `global`.
+- After a successful alternate-region request, persist it with `mmx config set --key region --value <global-or-cn> --quiet`.
+- Do not region-retry validation, `2013`, balance, rate-limit, sensitive-content, generic 5xx, terminal task failure, polling, download, or ambiguous timeout errors.
+
+## Waiting And Progress
+
+- The API does not publish a fixed completion ETA or progress percentage for each video.
+- Total time varies with queue load, requested duration, and reference-media complexity. Never promise that a task will finish in a specific number of minutes.
+- Poll no more frequently than once every 10 seconds.
+- Valid lifecycle statuses include `queued`, `running`, `succeeded`, `failed`, `cancelled`, and `expired`.
+- For a completed file, use one blocking `mmx video generate` command with `--download`, `--poll-interval 10`, and `--timeout 1800`. The CLI performs status polling internally.
+- If the terminal command remains active, wait on the same execution session. Do not start another command or infer failure from missing output while it is still running.
+- After 30 minutes, the CLI timeout may stop local polling. Preserve and report `taskId` when available; do not submit a duplicate task automatically.
+- MMX has no task-list command and does not persist local task history. Retain the returned task ID.
+
+## Prompt Construction
+
+Preserve the user's intent. When the prompt is underspecified, expand it into one production-oriented prompt in this order:
+
+1. Output goal: duration, aspect ratio, use case, and whether the clip should feel continuous or edited.
+2. Subjects and assets: identify people, products, locations, and how each reference image/video/audio should be used.
+3. Timeline: describe actions in chronological order with clear transitions.
+4. Scene: environment, time of day, lighting, weather, and important background details.
+5. Camera: shot size, angle, movement, focus behavior, and cuts.
+6. Look: visual style, color, texture, mood, and pacing.
+7. Sound: dialogue, ambience, music, sound effects, and synchronization to reference audio.
+8. Constraints: elements to preserve and artifacts to avoid, such as identity drift, flicker, text, logos, or abrupt cuts.
+
+When the user already supplies a complete structured storyboard, keep it intact. Do not condense, translate, or replace it with a generic prompt. Only check prompt length, timestamp coverage, reference numbering, media compatibility, and direct contradictions before submission.
+
+Operational heuristics for better results:
+
+- Keep actions physically achievable within the selected 4-15 second duration.
+- Prefer one clear action beat per shot instead of packing unrelated events into one block.
+- For multiple references, describe them in the same order as the repeated CLI flags: `reference image 1`, `reference image 2`, and so on.
+- Make timestamp ranges contiguous, with no gaps or overlaps, and make their final end time equal the requested duration.
+- Use a two-level timeline: a master shot range for every reference image, then micro-ranges inside that shot for preparation, execution, settling, and the final hold.
+- Use 0.5-second precision by default. Use finer timing only when a short, precise physical transition needs it.
+- Every shot must declare: exact range and duration, reference image number, initial state, shot/camera, micro-timeline, and locked end state.
+- The locked end state of shot N must be the initial state of shot N+1. Check character pose, gaze, occupied hand, prop owner/location, prop connections, and camera side.
+- State what must remain consistent and what may change. Example: preserve face, clothing, and product shape; change pose, camera angle, and background motion.
+- Lock persistent spatial relationships explicitly when important: left/right seat, foreground/background, screen direction, and which hand holds an object.
+- For handoffs and precise object motion, describe state transitions in causal order: initial owner and location, release condition, transfer, new owner, and final state. Do not compress these into one vague action.
+- Separate hard continuity constraints from aesthetic preferences and negative constraints. Repeat a critical invariant in the relevant timeline block when its failure would break the scene.
+- Use explicit camera language such as static shot, close-up, tracking shot, dolly in, pan, tilt, handheld, or aerial view.
+- Specify audio timing only when audio is supplied. State whether motion, cuts, lip movement, or effects should follow the beat or spoken words.
+- Do not silently add brands, dialogue, text overlays, or unsafe content that the user did not request.
+
+Timeline planning procedure:
+
+1. Read total duration `D` and ordered storyboard count `N`.
+2. Preserve user-supplied timestamps. Otherwise start with `D / N` seconds per storyboard; for example, 15 seconds with 6 images starts as six 2.5-second shots.
+3. Reallocate time by action complexity while keeping all ranges contiguous and totaling exactly `D`. Give precise handoffs or multi-stage physical actions more time; give static establishing or reaction shots less.
+4. Split each shot into 3-5 readable micro-beats: establish/hold, preparation, core action, settle/recovery, and optional final hold.
+5. Maintain a state ledger at every boundary: character position and pose, gaze, left/right hand state, prop owner and location, physical connections, and camera side.
+6. Verify that every reference is used exactly once in input order unless the user explicitly requests reuse, and that shot N's locked end state exactly matches shot N+1's initial state.
+7. If the requested actions cannot fit without becoming rushed or ambiguous, simplify the action plan or tell the user before making a paid request. Do not silently compress causal steps.
+
+For two or more ordered storyboard images, use the following structure. Do not flatten it into a single paragraph.
+
+English structured storyboard template:
+
+```text
+[OUTPUT SPECIFICATION]
+Create a {duration}-second, {ratio} {use case} video using {N} storyboard reference images in their exact input order as consecutive shot references. Follow the timeline without skipping shots or changing locked characters, wardrobe, positions, or key props.
+
+[OVERALL LOOK]
+{Live action/animation/product medium}; {cinematic or visual style}; {lighting, color, texture, depth of field, pacing, and camera baseline}. Scene: {environment, time, weather, and background motion}. Sound: {dialogue, ambience, music, reference-audio synchronization, or silence}.
+
+[CHARACTER AND SPATIAL CONTINUITY]
+Character 1: {appearance, wardrobe, demeanor}; always at {fixed position}.
+Character 2: {appearance, wardrobe, demeanor}; always at {fixed position}.
+Preserve {faces, hair, wardrobe, seats, screen direction, proportions, and scene layout} throughout.
+
+[PROP STATE CONTINUITY]
+The entire video contains exactly {prop count and names}. Initial state: {owner, hand, location, and connection}. Preserve {shape, count, connection, visibility, and physical behavior}; never duplicate, remove, teleport, disconnect, or silently change ownership.
+
+[TWO-LEVEL TIMELINE AND REFERENCE MAPPING]
+Shot 1 | 0:00-{T1} | Duration {D1}s | Reference image 1
+Shot and camera: {framing, angle, movement, and focus}.
+Initial state: {poses, gazes, both-hand states, prop owner/location/connections}.
+In-shot micro-timeline:
+- 0:00-{t1a}: Establish the frame with {visible state and subtle environment motion}.
+- {t1a}-{t1b}: Preparation: {gaze, weight, hand, or prop begins to change}.
+- {t1b}-{t1c}: Core action: {perform only this shot's main action}.
+- {t1c}-{T1}: Settle and hold the completed action; do not begin the next shot's action early.
+Locked end state: {explicit character, hand, prop, and connection state inherited by shot 2}.
+
+Shot 2 | {T1}-{T2} | Duration {D2}s | Reference image 2
+Shot and camera: {framing, angle, movement, and focus}.
+Initial state: exactly match shot 1's locked end state.
+In-shot micro-timeline:
+- {T1}-{t2a}: Hold the inherited state long enough to remain readable.
+- {t2a}-{t2b}: {preparation}.
+- {t2b}-{t2c}: {core action}.
+- {t2c}-{T2}: {completion, recovery, or hold}.
+Locked end state: {explicit state}.
+
+{Continue with one complete shot block per reference image. Both the master timeline and every in-shot micro-timeline must be contiguous; the final timestamp must equal duration.}
+
+[STRICT ACTION ORDER]
+{Action A} -> {Action B} -> {Action C} -> {Action D}. Do not merge, reorder, or omit steps. Each shot completes one clear action. For a handoff, state who remains still, who establishes and secures contact, and only then when the original holder releases.
+
+[NEGATIVE CONSTRAINTS]
+No {unwanted visual genre, editing style, or performance}. No {subtitles, watermarks, extra people, or extra props}. Avoid {identity drift, wardrobe changes, position swaps, flicker, malformed fingers, extra limbs, prop teleportation, broken connections, and abrupt cuts}.
+```
+
+For a single text-to-video request or one loose reference, a concise paragraph is acceptable. Use the full storyboard structure when continuity, multiple ordered images, or precise physical interactions matter.
+
+### Detailed Timing Example: Earbud Removal And Handoff
+
+English:
+
+```text
+Shot 2 | 0:02.5-0:05.0 | Duration 2.5s | Reference image 2
+Initial state: the girl looks at her phone with both earbuds in her ears; she holds the phone; the boy still holds his bag with both hands.
+0:02.5-0:03.0: The girl lowers the phone slightly and briefly looks at the boy; all other states remain unchanged.
+0:03.0-0:04.1: With the hand closer to the boy, she pinches one earbud stem between thumb and index finger and slowly removes it from her ear.
+0:04.1-0:05.0: She holds the earbud at chest height between them; the boy has not reached for it; a visible gap remains between the earbud and his face and ear.
+Locked end state: the girl still holds the earbud stem; the other earbud remains in her ear; the cable remains connected to her phone; both of the boy's hands remain on his bag.
+
+Shot 3 | 0:05.0-0:07.5 | Duration 2.5s | Reference image 3
+Initial state: exactly inherit shot 2's locked end state.
+0:05.0-0:05.5: The girl keeps her hand and the earbud still; the boy pauses.
+0:05.5-0:06.4: The boy raises the hand closer to the girl and approaches the earbud stem with thumb and index finger; she does not release it.
+0:06.4-0:07.0: The boy grips and secures the earbud stem; only after his grip is stable does the girl release it.
+0:07.0-0:07.5: The girl withdraws her hand; the boy holds the earbud but does not move it toward his ear yet.
+Locked end state: ownership has transferred to the boy; the earbud remains between them; the girl's hand has left the handoff area; the cable still connects naturally to the girl's phone.
+```
+
+## Media Preflight
+
+Frame mode and reference mode cannot be mixed. Reference audio requires at least one reference image or reference video.
+
+| Input | Official count/technical limits | Current local CLI handling |
+|---|---|---|
+| First frame | At most 1 image | `--image`; at most 30 MB |
+| Last frame | At most 1 image | `--last-frame`; at most 30 MB |
+| Reference image | At most 9; JPEG/JPG/PNG/WebP; 256-5760 px sides; aspect ratio 0.4-2.5 | JPG/JPEG/PNG/WebP/HEIC/HEIF; at most 30 MB each |
+| Reference video | At most 3; MP4/MOV; H.264/H.265; 23.976-60 FPS; each 2-15 seconds; total at most 15 seconds | Local MP4 only; at most 50 MB each. Use URL or `mm_file://` for other supported API inputs |
+| Reference audio | At most 3; MP3/WAV; each 2-15 seconds; total at most 15 seconds | Local MP3/WAV; at most 15 MB each |
+
+The total number of reference images, videos, and audios in a mixed-reference request must not exceed 12. Local media is Base64-encoded, and MMX limits the complete request body to 64 MB. Use public URLs or `mm_file://<file-id>` for large or numerous media inputs.
+
+Before a paid request, inspect local video/audio duration and codec once when they are unknown. Do not transcode media unless it violates an actual format or duration rule.
+
+## Failure Handling
+
+Use the shortest non-duplicating response:
+
+| Failure | Action |
+|---|---|
+| Region detection/endpoint or pre-submission 401/403, with no `taskId` and no model marker | Retry the unchanged request once with the alternate `--region`; if it succeeds, save that region |
+| No `taskId` and validation/HTTP 400 | Correct the reported field once; do not alter unrelated parameters |
+| `2013` mentioning TokenPlan/Credit and H3 | Stop and use a compatible Pay-as-you-go API Key |
+| Authentication error (`1004`, `2049`, HTTP 401/403) | Stop and request a valid key; do not retry |
+| Insufficient balance (`1008`, HTTP 402) | Stop and report the billing problem |
+| Rate limit (`1002`, HTTP 429) | Wait 60 seconds using the agent runtime's wait capability, then retry the same safe query once. Retry creation only when the response clearly confirms no task was created |
+| Sensitive prompt/media (`1026`, `1027`, HTTP 422) | Report the rejected input and ask the user to revise it; do not silently rewrite |
+| Temporary service/query error (`1000`, `1001`, `1024`, `1033`, HTTP 5xx) | For an existing task, wait 10 seconds using the agent runtime's wait capability and retry the same status query up to 3 times. Do not submit a replacement task automatically |
+| Terminal `failed`, `cancelled`, or `expired` | Report `taskId`, status, and task error; require user approval before creating another paid task |
+| Polling exceeds 30 minutes | Let the direct CLI command return its timeout, preserve `taskId` when available, and report that the task may still complete later |
+| Download fails after `succeeded` | Retry the same result URL up to 3 times; never regenerate the video |
+
+Once a task ID exists, all recovery must operate on that task ID. Never create a second paid task merely because terminal-session handling, polling, or downloading failed.