quickmagic-cli 1.4.0 → 1.9.0

package/README.md

@@ -8,7 +8,7 @@
 images/videos, product photoshoots, virtual try-on, hook ad videos, auto-subtitles/dubbing
 and more, through the Quick Magic REST API. Sign-in is browser-based **OAuth PKCE** — no API
 keys to copy around. Requires Node.js **≥ 18** (uses built-in `fetch`/`crypto`/`http`, no
-`axios`). Also ships with 9 Claude **Agent Skills** and an **MCP server** integration for
+`axios`). Also ships with 10 Claude **Agent Skills** and an **MCP server** integration for
 coding agents. Everything below this line is in Vietnamese (tiếng Việt) — quickstart only:
 
 ```bash
@@ -127,7 +127,8 @@ Ghi chú chung trước khi xem bảng:
 | Lệnh | Mô tả | Credit |
 |---|---|---|
 | `qm cutout` | Tách nền / PNG trong suốt / remix scene | Có |
-| `qm edit <image> --tool <t>` | restore / upscale (2k,4k) / beauty / muscle / color_boost | Có |
+| `qm edit <image> --tool <t>` | restore / beauty / muscle / color_boost (upscale → dùng `qm upscale`) | Có |
+| `qm upscale <file...> [--video]` | Upscale ảnh (2k/4k/8k) hoặc video (nâng nét/tăng fps) — 1 lệnh nhiều file = mỗi file 1 job | Có |
 
 ### Video quảng cáo / Marketing
 
@@ -147,10 +148,14 @@ Ghi chú chung trước khi xem bảng:
 | `qm subtitle <video_url>` | Thêm phụ đề (+ lồng tiếng, dịch) | Có |
 | `qm split <video_url>` | Cắt video dài → clip ngắn | Có |
 | `qm motion <video_url> --image <url...>` | Áp chuyển động video vào ảnh (Kling) | Có |
-| `qm tts (--text <t>\|--file <path>) --voice <v>` | Chuyển văn bản → giọng nói (5 model qimi_1.5/2.5/3/5/5.5) | Có |
+| `qm tts (--text <t>\|--file <path>) --voice <v>` | Chuyển văn bản → giọng nói (6 model qimi_1.5/2.5/3/3.5/5/5.5; qimi_3.5 có kiểu đọc `--style`) | Có |
 | `qm voices list --model <m>` | Liệt kê giọng theo model + giá (`pricing`) | — |
 | `qm voices clone --audio <file\|url> --name <n>` | Nhân bản giọng riêng (dùng cho qimi_5/5.5) | Có |
 | `qm voices delete <id>` | Xoá giọng đã clone | — |
+| `qm music models` | Bảng model nhạc + giá + ETA + hàng chờ | — |
+| `qm music lyrics --desc <d>` | AI viết lời bài hát | Không (0đ) |
+| `qm music create (--desc <d>\|--lyrics <l>)` | Tạo bài hát AI (mode simple/custom, 2 model melo-3/melo-2) | Có (thường miễn phí giai đoạn ra mắt) |
+| `qm music get <id>` | Xem chi tiết job nhạc | — |
 
 ### Nhập liệu (miễn phí)
 
@@ -160,6 +165,21 @@ Ghi chú chung trước khi xem bảng:
 | `qm import <url>` | Nhập ảnh/video từ link TikTok/Instagram | — |
 | `qm assets <kind>` | Liệt kê tài sản đã lưu: `products`\|`outfits`\|`kols` | — |
 
+### Ứng dụng web (React SSR trên `<slug>.quickmagic.app`)
+
+| Lệnh | Mô tả | Credit |
+|---|---|---|
+| `qm apps create --title "…" [--subdomain s] [--from <app_id>]` | Tạo app mới từ template (`--from` = remix app công khai đã duyệt) | — |
+| `qm apps list` | App của tôi | — |
+| `qm apps status <app_id> [--json]` | Trạng thái deploy/duyệt/build | — |
+| `qm apps repo-access <app_id>` | URL git clone có token 15 phút (push code) | — |
+| `qm apps deploy <app_id> [--wait]` | Build + deploy nhánh main | — |
+| `qm apps publish <app_id> [--unlist]` | Lên feed (cần cover; tự kiểm duyệt; app đầu tiên duyệt tay) | — |
+| `qm apps remove <app_id> --yes` | Xoá vĩnh viễn (subdomain khoá mãi) | — |
+
+Người dùng app trả credit của **chính họ** khi tạo ảnh/video trong app; bạn (creator) nhận 5% trên mỗi lượt.
+Không có `apps db` / `apps secrets` trên CLI (chỉ agent dùng qua MCP).
+
 ## Tạo ảnh
 
 ```bash
@@ -182,8 +202,39 @@ qm generate video --prompt "..." --model grok-imagine --wait --out ./out
 
 - `--image` cũng nhận URL hoặc file local (như `--ref`).
 - `--mode reference|frames` — `reference` (nhiều ảnh tham chiếu) hoặc `frames` (khung
-  đầu/cuối, tối đa 2). Một số model (họ Seedance 2.x) **từ chối ảnh chứa người thật** ở mọi
-  `--mode` — xem cột `IMAGES` của `qm models list --type video` (đánh dấu `*`).
+  đầu/cuối, tối đa 2). Model họ Seedance 2.x (`seedance-2-0`, `-fast`, `-mini`) giờ **tự động
+  chấp nhận ảnh người thật** ở mọi `--mode` — xem mục "Ảnh người thật" ngay dưới.
+
+### Ảnh người thật (Seedance 2.x)
+
+Model họ Seedance 2.x không còn chặn cứng ảnh có người thật: hệ thống tự chuẩn bị (đăng ký)
+ảnh trước khi render, **có thể mất thêm ~1–3 phút** ở lần đầu dùng 1 ảnh cụ thể. Trong lúc đó
+`qm jobs wait`/`--wait` in dòng `đang chuẩn bị ảnh có người thật (tối đa ~10 phút) — đừng tạo
+job mới…` — **đừng bấm Ctrl+C rồi chạy lại lệnh**, cứ để CLI tự chờ tiếp (script/agent gọi
+`jobs get`/`wait_for_job` cũng áp dụng y hệt — xem `docs/mcp-integration-guide.md` phía repo
+backend). Ảnh bị bộ lọc nội dung của model từ chối (bản quyền/chính sách; khi bật kiểm tra sớm:
+người nổi tiếng/nhân vật công chúng, trẻ em, nội dung nhạy cảm) → job `failed` kèm message rõ lý do
++ 1 `error_code` trong bảng dưới (credit hoàn), CLI tự in gợi ý xử lý:
+
+| `error_code` | Ý nghĩa | Gợi ý |
+|---|---|---|
+| `PORTRAIT_PUBLIC_FIGURE` | Ảnh có người nổi tiếng/nhân vật công chúng | Dùng ảnh người thường |
+| `PORTRAIT_MINOR` | Ảnh có trẻ em | Dùng ảnh người lớn |
+| `PORTRAIT_NSFW` | Ảnh vi phạm nội dung nhạy cảm | Dùng ảnh khác |
+| `PORTRAIT_GEMINI_UNAVAILABLE` | Chưa kiểm được ảnh (hệ thống bận) | Thử lại sau vài phút |
+| `PORTRAIT_ASSET_FAILED` | Ảnh không được chấp nhận (mờ/nhiều người/định dạng lạ) | Thử ảnh khác |
+| `PORTRAIT_ASSET_REJECTED` | Ảnh vẫn bị bộ lọc nội dung từ chối sau khi xử lý (người nổi tiếng/trẻ em/nhạy cảm/bản quyền) | Dùng ảnh khác |
+| `PORTRAIT_TIMEOUT` | Chuẩn bị ảnh quá lâu (>10 phút) | Thử lại |
+| `PORTRAIT_QUOTA_FULL` | Hệ thống đang bận (đầy quota tạm) | Thử lại sau vài phút |
+| `PORTRAIT_IMAGE_HOST` | Ảnh không thuộc host Quick Magic | Dùng `--image <file local>` (CLI tự upload) thay URL ngoài |
+| `PORTRAIT_IMAGE_FETCH_FAILED` | Không tải được ảnh | Thử lại |
+| `PORTRAIT_PROVIDER_ERROR` | Hệ thống đang bận (lỗi tạm thời) | Thử lại sau ít phút |
+| `PORTRAIT_PROVIDER_FAILED` | Ảnh bị từ chối theo chính sách nội dung (người nổi tiếng/trẻ em/nhạy cảm/bản quyền) | Dùng ảnh khác |
+| `PORTRAIT_COPYRIGHT` | Ảnh bị từ chối vì bản quyền/quyền hình ảnh (người nổi tiếng, nhân vật/tác phẩm/thương hiệu được bảo hộ) | Dùng ảnh khác |
+| `PORTRAIT_DISABLED` | Tính năng ảnh người thật đang tắt | Đổi `--model gemini-omni` |
+| `PORTRAIT_TOO_MANY_IMAGES` | Vượt số ảnh người thật cho phép của model | Bớt `--image` |
+| `PORTRAIT_VIDEO_REF_UNSUPPORTED` | Video tham chiếu có người thật chưa hỗ trợ | Dùng `--image` thay `--video-ref`, hoặc đổi model |
+| `REAL_PERSON_BLOCKED` | (mã cũ) Model không nhận ảnh người thật | Đổi `--model gemini-omni` |
 
 ## Job
 
@@ -232,6 +283,18 @@ qm voices list --model qimi_1.5 --language "Tiếng Việt"
 qm tts --text "Xin chào Quick Magic" --voice <voice_id> --model qimi_3 --wait --out ./out
 qm voices clone --audio ./sample.wav --name "Giọng của tôi" --wait
 
+# Qimi 3.5 — giọng của qimi_3, giá cố định mỗi lần (xem dòng "Giá:" của qm voices list --model qimi_3.5), tối đa 30.000 ký tự, chọn kiểu đọc:
+#   --style: tối đa 1 tốc độ (fast|default|slow) + 1 cảm xúc (cheerful|sad|storytelling|emotional), nối bằng "+"
+#            hoặc tự mô tả tiếng Việt "custom:<mô tả ≤200 ký tự>"; bỏ trống = đọc tự nhiên
+qm voices list --model qimi_3.5
+qm tts --file ./truyen.txt --voice <voice_id> --model qimi_3.5 --style "slow+storytelling" --wait --out ./out
+qm tts --text "Ngày xửa ngày xưa..." --voice <voice_id> --model qimi_3.5 --style "custom:giọng trầm ấm, chậm rãi như kể chuyện đêm khuya" --wait --out ./out
+
+# Tạo nhạc AI — xem giá trước khi chạy (thường miễn phí giai đoạn ra mắt)
+qm music models
+qm music lyrics --desc "bài hát vui về buổi sáng cà phê Sài Gòn"
+qm music create --mode simple --desc "lofi chill guitar, rainy night" --instrumental --model melo-2 --wait --out ./out
+
 # Video marketing theo mode + phân tích video đối thủ → kịch bản
 qm marketing modes
 qm marketing video --mode 3 --product-id 42 --duration 10
@@ -267,7 +330,7 @@ qm credits          # chạy không cần browser
 
 ## Agent Skills
 
-CLI này đi kèm 9 **Agent Skills** (`skills/quickmagic-*/SKILL.md`) để coding agent
+CLI này đi kèm 10 **Agent Skills** (`skills/quickmagic-*/SKILL.md`) để coding agent
 (Claude Code...) dùng CLI trực tiếp — báo giá + xin xác nhận trước khi tốn credit,
 tự `jobs wait` thay vì poll tay, chủ động báo Qimi free-window. Danh sách đầy đủ và quy ước
 chung: xem `skills/README.md`.
@@ -278,7 +341,7 @@ Cách 1 — `npx skills` (nếu dùng công cụ [`skills`](https://www.npmjs.co
 quản lý Agent Skills từ GitHub):
 
 ```bash
-npx skills add Tungbillee/cli-quickmagic --skills quickmagic-account,quickmagic-generate,quickmagic-product-photoshoot,quickmagic-fashion,quickmagic-cutout,quickmagic-hook-video,quickmagic-edit-image,quickmagic-subtitle-split,quickmagic-tts
+npx skills add Tungbillee/cli-quickmagic --skills quickmagic-account,quickmagic-generate,quickmagic-product-photoshoot,quickmagic-fashion,quickmagic-cutout,quickmagic-hook-video,quickmagic-edit-image,quickmagic-subtitle-split,quickmagic-tts,quickmagic-music
 ```
 
 Cách 2 — copy thủ công vào thư mục skills của Claude Code:
@@ -293,8 +356,8 @@ cp -r skills/quickmagic-* ~/.claude/skills/      # user (mọi project trên má
 Quick Magic cũng có MCP server dùng **chung tài khoản/ví credit** — cho phép Claude Code
 (và các MCP client khác) gọi thẳng `generate_image`, `generate_video`, `get_job`,
 `wait_for_job`, `list_models`, `get_credit_balance`, `list_voices`, `text_to_speech`,
-`create_voice_clone`, `delete_voice_clone`... mà không cần qua CLI. Xác thực OAuth 2.1 qua
-trình duyệt, không cần API key.
+`create_voice_clone`, `delete_voice_clone`, `generate_music`, `write_lyrics`... mà không cần
+qua CLI. Xác thực OAuth 2.1 qua trình duyệt, không cần API key.
 
 - MCP endpoint: `https://api.quickmagic.vn/mcp`
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "quickmagic-cli",
-  "version": "1.4.0",
-  "description": "Quick Magic CLI — generate AI images/videos, product photoshoots, virtual try-on, hook ad videos, subtitles, text-to-speech/voice cloning and more via the Quick Magic REST API, with browser-based OAuth PKCE login (no API keys to manage). Ships with 9 Claude Agent Skills and an MCP server integration.",
+  "version": "1.9.0",
+  "description": "Quick Magic CLI — generate AI images/videos, product photoshoots, virtual try-on, hook ad videos, subtitles, text-to-speech/voice cloning, AI song generation, image upscaling and more via the Quick Magic REST API, with browser-based OAuth PKCE login (no API keys to manage). Ships with 11 Claude Agent Skills and an MCP server integration.",
   "bin": {
     "quickmagic": "src/index.js",
     "qm": "src/index.js"
@@ -32,7 +32,10 @@
     "claude-code",
     "agent-skills",
     "product-photography",
-    "virtual-try-on"
+    "virtual-try-on",
+    "text-to-speech",
+    "voice-cloning",
+    "music-generation"
   ],
   "homepage": "https://github.com/Tungbillee/cli-quickmagic#readme",
   "repository": {

package/skills/README.md

@@ -1,6 +1,6 @@
 # Quick Magic CLI — Agent Skills
 
-9 Agent Skills that wrap the `quickmagic` / `qm` CLI so a coding agent (Claude
+11 Agent Skills that wrap the `quickmagic` / `qm` CLI so a coding agent (Claude
 Code and compatible tools) can drive Quick Magic directly from the terminal —
 mirroring the `npx skills add higgsfield-ai/skills` pattern (`/higgsfield:generate`
 etc.), tailored to Quick Magic's own REST API and CLI.
@@ -18,7 +18,7 @@ when to load the skill).
 Option 1 — `npx skills` (if this repo is published as a skills package):
 
 ```bash
-npx skills add Tungbillee/cli-quickmagic --skills quickmagic-account,quickmagic-generate,quickmagic-product-photoshoot,quickmagic-fashion,quickmagic-cutout,quickmagic-hook-video,quickmagic-edit-image,quickmagic-subtitle-split,quickmagic-tts
+npx skills add Tungbillee/cli-quickmagic --skills quickmagic-account,quickmagic-generate,quickmagic-product-photoshoot,quickmagic-fashion,quickmagic-cutout,quickmagic-hook-video,quickmagic-edit-image,quickmagic-upscale,quickmagic-subtitle-split,quickmagic-tts,quickmagic-music
 ```
 
 Option 2 — copy directly into a project's or your user's Claude skills folder:
@@ -35,17 +35,19 @@ mkdir -p ~/.claude/skills && cp -r cli-quickmagic/skills/quickmagic-* ~/.claude/
 
 | Skill | Wraps | Use for |
 |---|---|---|
-| `quickmagic-account` | `auth`, `credits`, `models list`, `jobs get/wait` | login/status, credit balance + Qimi free-window benefit, model catalog, job polling — **foundation** the other 8 skills reference |
+| `quickmagic-account` | `auth`, `credits`, `models list`, `jobs get/wait` | login/status, credit balance + Qimi free-window benefit, model catalog, job polling — **foundation** the other 9 skills reference |
 | `quickmagic-generate` | `generate image`, `generate video` | text/reference-to-image or -video |
 | `quickmagic-product-photoshoot` | `product` | studio/marketing photos of a product (packshot/poster/infographic/composite) |
 | `quickmagic-fashion` | `fashion`, `tryon` | outfit lookbook shoots vs. virtual try-on on a specific person photo |
 | `quickmagic-cutout` | `cutout` | transparent PNG cutouts / scene remix |
 | `quickmagic-hook-video` | `hook presets`, `hook video` | ~10s comedy ad video from a character + product photo (18 presets) |
-| `quickmagic-edit-image` | `edit` | restore / upscale (2k/4k) / beauty / muscle / color_boost on an existing image |
+| `quickmagic-edit-image` | `edit` | restore / beauty / muscle / color_boost on an existing image |
+| `quickmagic-upscale` | `upscale` | upscale images to 2K/4K/8K (crisp/standard/seedvr2/ultra) or videos (standard/pro/seedvr2/fps) |
 | `quickmagic-subtitle-split` | `subtitle`, `split` | auto subtitles/dubbing, long-video → short clips |
-| `quickmagic-tts` | `tts`, `voices list/clone/delete` | text-to-speech (5 models) + custom voice cloning |
+| `quickmagic-tts` | `tts`, `voices list/clone/delete` | text-to-speech (6 models; `qimi_3.5` adds reading styles — presets or your own Vietnamese description — at a flat price per call) + custom voice cloning |
+| `quickmagic-music` | `music create/lyrics/models/get` | AI song generation (vocals or instrumental) from a description or your own lyrics |
 
-## Shared conventions (all 9 skills)
+## Shared conventions (all 11 skills)
 
 - Check `qm auth status` first; if not logged in, tell the user to run
   `qm auth login`.
@@ -60,7 +62,7 @@ mkdir -p ~/.claude/skills && cp -r cli-quickmagic/skills/quickmagic-* ~/.claude/
   shortfall and a link to top up (https://quickmagic.vn/pricing).
 - Never poll `jobs get` manually — use `qm jobs wait <id> [--out dir]`. Note that
   `--out` only auto-downloads for job types with a single `result_url`
-  (image/video/tryon/edit/hook/subtitle/tts); product/fashion/cutout/split
+  (image/video/tryon/edit/upscale/hook/subtitle/tts/music); product/fashion/cutout/split
   return arrays and must be read back with `qm jobs get <id>` after
   completion, and voice-clone jobs (`voc_`) have no `result_url` at all (read
   `voice`/`sample_url`/`status` instead). See `quickmagic-account` for the

package/skills/quickmagic-account/SKILL.md

@@ -66,6 +66,11 @@ qm models list --type video    # columns: KEY | LABEL | CREDIT | IMAGES
   `ref 9 · frames 2`. A trailing `*` means that mode **rejects photos containing
   real people** for that model — switch models (e.g. `gemini-omni`, a `seedance
   1.x` key, `wan-2-7`) if the user's reference photos have people in them.
+  No `*` = people photos are fine. Seedance 2.x currently accepts real-people
+  photos (the server prints an ℹ note under the table): the first use of a given
+  photo may add ~1–3 min of preparation — `qm jobs wait` handles it, do NOT
+  resubmit. If the model's content filter rejects a photo (copyright/policy), the
+  job fails with an explicit reason and the credit is refunded — use another photo.
 - The table does not print quality tiers or max-ref-image counts for image
   models — image quality levels are commonly `1K`/`2K`/`4K`, priced per level; if
   the exact enum for a model is unknown, omit `--quality` and let the server
@@ -103,13 +108,16 @@ generating command's own `--wait` flag, where available).
 | `stt_` | `stt` | text result (no dedicated skill) |
 | `tts_` | `tts` | single `result_url` (mp3) + `model`/`voice`/`character` — see `quickmagic-tts` |
 | `voc_` | `voices clone` | **no** `result_url`: `voice` (name to use with `--voice`), `sample_url`, `is_free` — see `quickmagic-tts` |
+| `mus_` | `music create` | single `result_url` (mp3) + `title`/`duration_ms` — see `quickmagic-music` |
+| `ups_` | `upscale` (image) | single `result_url` — see `quickmagic-upscale` |
+| `vup_` | `upscale` (video, `--video`/auto-detected) | single `result_url` + `duration_sec` — see `quickmagic-upscale` |
 
 **Important caveat**: `jobs wait --out <dir>` only **auto-downloads** for the
-single-`result_url` types (`img_`/`vid_`/`vto_`/`edt_`/`hok_`/`sub_`/`tts_`). For the
-array types (`pai_`/`fsh_`/`cut_`/`spl_`) and `voc_` (voice clone — no file, read
-`voice`/`sample_url` via `qm jobs get`), `--out` still polls status correctly
-but downloads nothing — after status is `completed`, call `qm jobs get <id>` and
-read the array field yourself, then report each URL to the user.
+single-`result_url` types (`img_`/`vid_`/`vto_`/`edt_`/`hok_`/`sub_`/`tts_`/`mus_`/
+`ups_`/`vup_`). For the array types (`pai_`/`fsh_`/`cut_`/`spl_`) and `voc_` (voice
+clone — no file, read `voice`/`sample_url` via `qm jobs get`), `--out` still polls
+status correctly but downloads nothing — after status is `completed`, call
+`qm jobs get <id>` and read the array field yourself, then report each URL to the user.
 
 Statuses: `queued` → `in_progress` → `completed` (success) or `failed` (relay the
 job's `error` field). A `queued` status stuck past ~15 minutes is reported as

package/skills/quickmagic-edit-image/SKILL.md

@@ -1,14 +1,16 @@
 ---
 name: quickmagic-edit-image
 description: >-
-  Restore, upscale (2k/4k), beauty-retouch, muscle-enhance, or color-boost a
-  single existing image via `qm edit`. Use for enhancing an existing photo,
-  not generating a new one. Triggers: "upscale ảnh lên 4k", "phục hồi ảnh cũ",
-  "làm đẹp da trong ảnh", "chỉnh màu ảnh", "restore old photo", "upscale
-  image resolution".
+  Restore, beauty-retouch, muscle-enhance, or color-boost a single existing
+  image via `qm edit`. Use for enhancing an existing photo, not generating a new
+  one. For enlarging / sharpening (2k/4k/8k) use the `quickmagic-upscale` skill
+  (`qm upscale`) instead. Triggers: "phục hồi ảnh cũ", "làm đẹp da trong ảnh",
+  "chỉnh màu ảnh", "restore old photo", "retouch skin".
 ---
 
-# quickmagic-edit-image — Photo Restore / Upscale / Retouch
+# quickmagic-edit-image — Photo Restore / Retouch
+
+> Phóng to & làm nét ảnh đã tách sang skill `quickmagic-upscale` (`qm upscale`).
 
 Wraps `qm edit <image>`. Edits **one existing image** in place — restoring
 damage, upscaling resolution, beauty retouch, muscle enhancement, or color
@@ -18,22 +20,21 @@ grading. Not for generating a new image from a text prompt (use
 ## Command
 
 ```
-qm edit <image> --tool <t> [--model qimi_2.5|qimi_3] [--upscale-target 2k|4k] [--style <s...>] [--crid <id>]
+qm edit <image> --tool <t> [--model qimi_2.5|qimi_3] [--style <s...>] [--crid <id>]
 ```
 
 | Flag | Notes |
 |---|---|
 | `<image>` **required** (positional) | URL or local file path |
-| `--tool <t>` **required** | one of `restore` \| `upscale` \| `beauty` \| `muscle` \| `color_boost` |
+| `--tool <t>` **required** | one of `restore` \| `beauty` \| `muscle` \| `color_boost` |
 | `--model` | `qimi_2.5` or `qimi_3` (default `qimi_3`) |
-| `--upscale-target` | **required when `--tool upscale`** — `2k` or `4k` |
 | `--style <s...>` | **required when `--tool beauty`** — up to 3 style keywords, repeatable flag |
 | `--crid <id>` | idempotency key |
 
-Map the user's request to a tool: "ảnh cũ/rách/mờ" → `restore`; "phóng to/nét
-hơn/4K" → `upscale` (ask 2k or 4k if not specified); "làm đẹp da/mặt" → `beauty`
-(ask for up to 3 style keywords); "cơ bắp săn chắc hơn" → `muscle`; "màu sắc rực
-rỡ hơn" → `color_boost`.
+Map the user's request to a tool: "ảnh cũ/rách/mờ" → `restore`; "làm đẹp da/mặt"
+→ `beauty` (ask for up to 3 style keywords); "cơ bắp săn chắc hơn" → `muscle`;
+"màu sắc rực rỡ hơn" → `color_boost`. "Phóng to / nét hơn / 4K / 8K" KHÔNG thuộc
+lệnh này — dùng skill `quickmagic-upscale` (`qm upscale`).
 
 ## Before running
 
@@ -55,15 +56,14 @@ No `--wait` flag. Copy the job id from the hint
 ## Errors
 
 `Không đủ credit: ...` → state shortfall + https://quickmagic.vn/pricing.
-Missing `--upscale-target` on `upscale`, or missing `--style` on `beauty` →
-plain `Lỗi: <message>`; add the missing flag and retry. Full reference:
+Missing `--style` on `beauty` → plain `Lỗi: <message>`; add the flag and retry.
+`tool_moved` → tool `upscale` đã dời sang `qm upscale` (skill `quickmagic-upscale`). Full reference:
 `quickmagic-account` skill.
 
 ## Example
 
 ```bash
 qm edit ./old-photo.jpg --tool restore --model qimi_3
-qm edit ./portrait.jpg --tool upscale --upscale-target 4k
 qm edit ./selfie.jpg --tool beauty --style smooth-skin soft-light
 qm jobs wait edt_3 --out ./out
 ```

package/skills/quickmagic-generate/SKILL.md

@@ -36,7 +36,11 @@ studio photos see `quickmagic-product-photoshoot`.
 `KEY | LABEL | CREDIT` (+ `IMAGES` column for video, showing max reference images
 per mode, e.g. `ref 9 · frames 2`; a `*` after a number means that mode **rejects
 real photos of real people** — pick a different model if the user's refs contain
-people, e.g. `gemini-omni` / a `seedance 1.x` key / `wan-2-7`).
+people, e.g. `gemini-omni` / a `seedance 1.x` key / `wan-2-7`). No `*` = people
+photos are accepted; Seedance 2.x currently accepts them (first use of a photo may
+add ~1–3 min of server-side preparation — keep waiting with `qm jobs wait`, do not
+resubmit; a content-filter rejection — copyright/policy — fails the job with an
+explicit reason and refunds the credit → try another photo).
 
 - This table doesn't print quality tiers — image quality levels are commonly
   `1K`/`2K`/`4K`, priced differently per level. If `--quality` matters, mention the

package/skills/quickmagic-music/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: quickmagic-music
+description: >-
+  Generate an AI song (with vocals or instrumental) from a text description
+  or your own lyrics, via the Quick Magic CLI (`qm music create/lyrics/models/get`).
+  2 models (melo-3 default, melo-2), simple mode (AI writes lyrics) or custom
+  mode (your own lyrics), fair 1-song-per-account queue. Triggers:
+  "tạo nhạc AI", "sáng tác nhạc", "viết bài hát", "viết lời bài hát",
+  "làm nhạc nền", "generate a song", "AI music", "write song lyrics",
+  "compose a song", "make music", "text to music".
+---
+
+# quickmagic-music — AI Song Generation (Xưởng Nhạc "Melo")
+
+Wraps `qm music create/lyrics/models/get`. Use whenever the user wants an AI-
+generated song (vocals or instrumental) or just wants lyrics written for them.
+
+## Commands
+
+| Command | Required flags | Key optional flags |
+|---|---|---|
+| `qm music models` | — | prints KEY/LABEL/GIÁ/ETA/HÀNG CHỜ table |
+| `qm music lyrics` | `--desc <d>` | `--title <t>`, `--language <l>`, `--instrumental` |
+| `qm music create` | `--desc <d>` (mode simple/instrumental) or `--lyrics <l>`/`--lyrics-file <path>` (mode custom) | `--mode <m>` (default `simple`), `--model <m>` (default `melo-3`), `--styles <s>`, `--title <t>`, `--instrumental`, `--gender <g>`, `--crid <id>`, `--wait`, `--out <dir>` |
+| `qm music get <id>` | `<id>` (`mus_12` or bare `12`) | — |
+
+## Two modes
+
+- **`--mode simple`** (default): pass `--desc` describing the vibe/topic —
+  the server's internal AI songwriter writes the lyrics automatically. Good
+  default when the user just describes what they want.
+- **`--mode custom`**: pass `--lyrics` (inline) or `--lyrics-file <path>`
+  (local UTF-8 text file, ≤3500 chars) with lyrics the user already has or
+  that you drafted with `qm music lyrics` first.
+- **`--instrumental`**: no vocals at all — only `--styles`/`--desc` matter,
+  `--lyrics`/`--gender` are ignored.
+
+## Pricing — always read at runtime, never hardcode
+
+```bash
+qm music models
+```
+
+Prices are **runtime-only** — currently **free during the launch phase**
+(check the `GIÁ` column / `free_launch` in the raw JSON), but this can change
+at any time. `qm music create` already re-reads this internally right before
+submitting and passes it as a price guard — if the price changed between your
+quote and the actual submit, the command fails with `price_changed` instead
+of silently charging a different amount. If that happens, just re-run
+`qm music models`, tell the user the new price, and get confirmation again
+before retrying `qm music create`.
+
+## Queue — fair, 1 song running per account
+
+Each account runs **1 song at a time**; extra requests queue fairly (FIFO
+across users, not first-come-first-served within a single user hogging
+slots). `qm music create` prints `queue_position`/`eta_seconds` right after
+submitting. **Don't poll manually** — always use `--wait` (or
+`qm jobs wait mus_<n> --out <dir>` afterwards), which polls automatically and
+auto-downloads the mp3 once done (single `result_url`, like `tts`/`generate
+image`). A song typically finishes in under 2 minutes once it starts running,
+longer if queued behind other users' jobs. A long `queued` job is **not**
+necessarily an error — check `queue_position`/`eta_seconds` in `qm music get`;
+`status` only flips to `stalled` once the job stops making queue progress at
+all (well past the ETA), not just because it has been waiting a while.
+
+## Workflow
+
+```bash
+qm music models                                          # 1. check current price + ETA
+qm music lyrics --desc "lofi chill về mùa thu Hà Nội"      # 2. optional — preview/edit lyrics first
+# ... quote the price, get explicit user confirmation ...
+qm music create --mode simple --desc "lofi chill về mùa thu Hà Nội" \
+  --model melo-3 --wait --out ./out                       # 3. submit + wait + auto-download mp3
+```
+
+Custom lyrics example:
+
+```bash
+qm music create --mode custom --lyrics-file ./loi-bai-hat.txt \
+  --styles "V-pop, Ballad, Piano" --title "Chiều Thu" --gender female --wait --out ./out
+```
+
+Instrumental example:
+
+```bash
+qm music create --mode simple --desc "epic cinematic trailer music, orchestral, rising tension" \
+  --instrumental --model melo-2 --wait --out ./out
+```
+
+## Errors
+
+CLI prints `Lỗi [code]: message`. Common codes:
+
+| Code | Meaning | What to do |
+|---|---|---|
+| `rate_limited` | more than 3 song submits/minute for this account | wait, then retry |
+| `feature_disabled` | Xưởng Nhạc temporarily off | tell the user, don't retry |
+| `price_changed` | price shifted between quote and submit | re-run `qm music models`, re-quote, re-confirm |
+| `invalid_input` | missing/invalid `--desc`/`--lyrics`/`--model`/`--mode` for the chosen mode | check the mode's required field (see "Two modes" above) |
+| `insufficient_credit` / `negative_balance` | not enough balance (only matters once pricing is no longer free) | state the exact shortfall and https://quickmagic.vn/pricing |
+| `busy` | `qm music lyrics` internal writer overloaded | wait a bit, then retry `qm music lyrics`, or just supply lyrics yourself |
+| `lyrics_failed` | AI songwriter couldn't produce valid lyrics after retry | try a clearer/different `--desc`, or write lyrics yourself with `--lyrics` |
+| `feature_unavailable` | account temporarily blocked from this feature | tell the user, don't retry |
+| `concurrent_limit` | too many jobs already running at once for the account's plan | wait for one of the running jobs to finish, then retry |
+| `INVALID_PROMPT` | (uppercase, REST-only) `--lyrics` over 3500 chars or `--desc` over 500 chars | shorten the text and resubmit |
+
+Full auth/job/error-code reference: `quickmagic-account` skill.
+
+## Examples
+
+```bash
+qm auth status
+qm music models
+qm music lyrics --desc "bài hát vui về buổi sáng cà phê Sài Gòn" --title "Sài Gòn Sáng Cà Phê"
+qm music create --mode simple --desc "bài hát vui về buổi sáng cà phê Sài Gòn" --wait --out ./out
+qm music get mus_12
+```

package/skills/quickmagic-tts/SKILL.md

@@ -2,12 +2,15 @@
 name: quickmagic-tts
 description: >-
   Convert text to speech, or clone a custom voice, via the Quick Magic CLI
-  (`qm tts`, `qm voices list/clone/delete`). Covers 5 TTS engines (qimi_1.5,
-  qimi_2.5, qimi_3, qimi_5, qimi_5.5) — the last two add 310 built-in system
-  voices across 16 languages plus optional user voice cloning. Triggers:
-  "đọc văn bản thành giọng nói", "chuyển text thành giọng nói", "clone giọng",
-  "tạo giọng riêng", "nhân bản giọng nói", "text to speech", "voice clone",
-  "TTS", "read this text aloud", "convert text to audio".
+  (`qm tts`, `qm voices list/clone/delete`). Covers 6 TTS engines (qimi_1.5,
+  qimi_2.5, qimi_3, qimi_3.5, qimi_5, qimi_5.5) — qimi_3.5 reads the qimi_3
+  voices with a chosen reading style (speed/emotion presets or your own
+  Vietnamese description), at a flat price per call; qimi_5/qimi_5.5 add 310
+  built-in system voices across 16 languages plus optional user voice
+  cloning. Triggers: "đọc văn bản thành giọng nói", "chuyển text thành giọng
+  nói", "đọc truyện", "giọng kể chuyện", "đọc chậm", "giọng vui tươi",
+  "clone giọng", "tạo giọng riêng", "nhân bản giọng nói", "text to speech",
+  "voice clone", "TTS", "read this text aloud", "convert text to audio".
 ---
 
 # quickmagic-tts — Text-to-Speech & Voice Cloning
@@ -19,7 +22,7 @@ text read aloud as audio, or wants a custom cloned voice for future TTS calls.
 
 | Command | Required flags | Key optional flags |
 |---|---|---|
-| `qm tts` | `--text <t>` or `--file <path>`, `--voice <v>` | `--model <m>` (default `qimi_3`), `--language <l>`, `--speed <n>` (0.5-2.0, qimi_5/qimi_5.5 only), `--style <s>`, `--title <t>`, `--crid <id>`, `--wait`, `--out <dir>` |
+| `qm tts` | `--text <t>` or `--file <path>`, `--voice <v>` | `--model <m>` (default `qimi_3`), `--language <l>`, `--speed <n>` (0.5-2.0, qimi_5/qimi_5.5 only), `--style <s>` (voice label for qimi_1.5/2.5/3; preset or `custom:<mô tả>` for qimi_3.5 — see "Reading styles"), `--title <t>`, `--crid <id>`, `--wait`, `--out <dir>` |
 | `qm voices list` | `--model <m>` | `--language <l>`, `--search <s>`, `--limit <n>` (default 50, max 100 — qimi_1.5 has 535 voices and qimi_5 310+: use `--language`/`--search` to narrow instead of paging) |
 | `qm voices clone` | `--audio <file\|url>`, `--name <n>` | `--crid <id>` (auto-generated if omitted), `--wait` |
 | `qm voices delete <id>` | `<id>` (`voc_12` or bare `12`) | — |
@@ -31,15 +34,18 @@ text read aloud as audio, or wants a custom cloned voice for future TTS calls.
 | `qimi_1.5` | flat credits/call | 50,000 | fixed catalog |
 | `qimi_2.5` | flat credits/call | 30,000 | fixed catalog |
 | `qimi_3` (default) | flat credits/call | 30,000 | fixed catalog |
+| `qimi_3.5` | flat credits/call | 30,000 | the `qimi_3` catalog (multilingual) + reading styles — no clones |
 | `qimi_5` | credits/character, with a minimum charge | 10,000 | 310 system voices (16 languages) + your own clones |
 | `qimi_5.5` | credits/character (higher quality), with a minimum charge | 10,000 | 310 system voices (16 languages) + your own clones |
 
-Reference only, as of 260817 — **never quote these from memory**. Always run
+Reference only, as of 260927 — **never quote these from memory**. Always run
 `qm voices list --model <m>` and read the `pricing` object from its response:
-roughly `qimi_1.5`/`qimi_2.5` ≈ 2cr/call, `qimi_3` ≈ 4cr/call, `qimi_5` ≈
-0.09cr/char, `qimi_5.5` ≈ 0.15cr/char (min ~5cr) — rates can change. Voice
-cloning is a separate, much larger flat charge (~2,230cr) — see "Cloning a
-custom voice" below.
+roughly `qimi_1.5`/`qimi_2.5` ≈ 2cr/call, `qimi_3` ≈ 4cr/call, `qimi_3.5` ≈
+10cr/call (any length up to 30,000 chars), `qimi_5` ≈ 0.09cr/char,
+`qimi_5.5` ≈ 0.15cr/char (min ~5cr) — rates can change. Per-character models
+count the text **after** your saved pronunciation replacements. Voice cloning
+is a separate, much larger flat charge (~2,230cr) — see "Cloning a custom
+voice" below.
 
 ## Pick a voice
 
@@ -55,6 +61,9 @@ qm voices list --model qimi_5 --search Minh --limit 20
 - `qimi_1.5`/`qimi_2.5`/`qimi_3` list a fixed catalog with a `STYLES` column
   (labels like "Vui vẻ"/"Formal") — pass the exact label as `--style`.
   `qimi_5`/`qimi_5.5` voices don't take `--style`.
+- `qimi_3.5` lists the same voices as `qimi_3` and
+  prints a `Kiểu đọc (style)` line — its `--style` is a reading style, not a
+  voice label (see "Reading styles" below).
 - `qimi_5`/`qimi_5.5` output splits into **"Giọng của bạn"** (voices you
   cloned) and **"Giọng hệ thống"** (310 system voices, 16 languages) —
   cloning is optional, try a system voice first. Each system voice reads
@@ -74,8 +83,28 @@ qm tts --file ./script.txt --voice <voice_id> --model qimi_5 --language "Tiếng
 - The CLI prints the character count before submitting; sanity-check it
   against the model's char limit above to avoid a `char_limit_exceeded`.
 - Without `--wait`, note the printed job id (`tts_<n>`) and run
-  `qm jobs wait tts_<n> --out ./out` separately — it auto-downloads the mp3
-  (single `result_url`).
+  `qm jobs wait tts_<n> --out ./out` separately — it auto-downloads the audio
+  file (mp3, or wav for qimi_3/qimi_3.5; single `result_url`).
+
+## Reading styles (qimi_3.5 only)
+
+```bash
+qm voices list --model qimi_3.5          # prints the price line + the live "Kiểu đọc (style)" hint
+qm tts --file ./truyen.txt --voice <voice_id> --model qimi_3.5 --style "slow+storytelling" --wait --out ./out
+qm tts --text "Ngày xửa ngày xưa..." --voice <voice_id> --model qimi_3.5 --style "custom:giọng trầm ấm, chậm rãi như kể chuyện đêm khuya" --wait --out ./out
+```
+
+- Preset: at most **one speed** (`fast` | `default` | `slow`) and **one
+  emotion** (`cheerful` | `sad` | `storytelling` | `emotional`), joined
+  with `+` — e.g. `slow`, `cheerful`, `slow+storytelling`. The server's
+  current list is the `Kiểu đọc (style)` line of `qm voices list --model qimi_3.5`.
+- Custom: `custom:<Vietnamese description>`, ≤200 characters after the
+  server removes quotes/brackets and turns line breaks into spaces. It only
+  changes tone, pace and emotion — the text is still read word for word.
+- Omit `--style` for a natural read. `--speed` does not apply to qimi_3.5 —
+  put the speed in `--style` instead.
+- An unknown key, two speeds, two emotions, or a custom text over 200
+  characters fails with `invalid_style` **before** any credit is held.
 
 ## Cloning a custom voice (optional, for qimi_5/qimi_5.5)
 
@@ -137,10 +166,10 @@ CLI prints `Lỗi [code]: message`. Common codes:
 
 | Code | Meaning | What to do |
 |---|---|---|
-| `invalid_model` | `--model` not one of the 5 keys (e.g. `v3`) | use `qimi_1.5|qimi_2.5|qimi_3|qimi_5|qimi_5.5` |
+| `invalid_model` | `--model` not one of the 6 keys (e.g. `v3`) | use `qimi_1.5|qimi_2.5|qimi_3|qimi_3.5|qimi_5|qimi_5.5` |
 | `voice_not_found` | bad/unknown `--voice` | re-pick from `qm voices list`; if the name repeats across languages, add `--language` |
-| `invalid_style` | `--style` isn't in that voice's `styles` | use the exact label from the `STYLES` column |
-| `invalid_speed` | outside 0.5-2.0, or `--speed` used with qimi_1.5/2.5/3 | clamp to range; only pass `--speed` for qimi_5/qimi_5.5 |
+| `invalid_style` | qimi_1.5/2.5/3: `--style` isn't in that voice's `styles`; qimi_3.5: unknown preset key, two speeds/emotions, or `custom:` text over 200 chars | use the exact `STYLES` label; for qimi_3.5 follow "Reading styles" |
+| `invalid_speed` | `--speed` outside 0.5-2.0 on qimi_5/qimi_5.5 (other models ignore `--speed`) | clamp to range; for qimi_3.5 use a speed preset in `--style` |
 | `char_limit_exceeded` | text longer than the model's char limit | split the text into smaller chunks |
 | `insufficient_credit` / `negative_balance` | not enough balance | state the exact shortfall and https://quickmagic.vn/pricing |
 | `rate_limited` / `concurrent_limit` / `busy` | too many requests/jobs right now | wait, then retry |
@@ -159,6 +188,9 @@ qm auth status
 qm voices list --model qimi_1.5 --language "Tiếng Việt"   # qimi_3 has no per-language labels (all "Đa ngôn ngữ (70+)") — omit --language for it
 qm tts --text "Chào mừng đến với Quick Magic." --voice <voice_id> --model qimi_3 --wait --out ./out
 
+qm voices list --model qimi_3.5
+qm tts --file ./truyen.txt --voice <voice_id> --model qimi_3.5 --style "slow+storytelling" --wait --out ./out
+
 qm voices list --model qimi_5
 qm voices clone --audio ./mysample.wav --name "Giọng riêng" --wait
 qm tts --text "Đọc bằng giọng của tôi." --voice "Giọng riêng" --model qimi_5 --wait --out ./out

package/skills/quickmagic-upscale/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: quickmagic-upscale
+description: >-
+  Upscale (sharpen + enlarge) one or more existing images to 2K/4K/8K, or
+  denoise/sharpen existing videos, via `qm upscale`. Use when the user wants a
+  sharper/higher-resolution version of an existing photo or video — not for
+  generating new media, and not for restore/beauty/muscle/color_boost (use
+  `quickmagic-edit-image` for those). Triggers: "upscale ảnh lên 4k/8k",
+  "phóng to ảnh nét hơn", "nâng độ phân giải ảnh", "upscale image to 4k",
+  "sharpen this photo", "upscale video", "làm nét video", "video mờ quá làm
+  nét lại", "tăng fps video".
+---
+
+# quickmagic-upscale — Image (2K/4K/8K) + Video Upscale
+
+Wraps `qm upscale <image...>`. Takes **one or more existing images or
+videos** and returns a sharper, higher-resolution (or higher-frame-rate)
+version of each — one credit hold and one job per file. Not for restoring
+damage, beauty retouch, muscle enhancement, or color grading
+(`quickmagic-edit-image` handles those tools), and not for generating new
+media from a text prompt (`quickmagic-generate`).
+
+## Command
+
+```
+qm upscale <file...> [--model <m>] [--resolution <r>] [--video] [--crid <id>]
+```
+
+| Flag | Notes |
+|---|---|
+| `<file...>` **required** (positional, 1+) | URL(s) or local file path(s) — repeatable, one job submitted per file |
+| `--model <m>` | Image: `crisp`\|`standard`\|`seedvr2`\|`ultra`. Video: `standard`\|`pro`\|`seedvr2`\|`fps`. Default `standard` (valid for both) |
+| `--resolution <r>` | Image: `2k`\|`4k`\|`8k`, default `4k`. Video: `720p`\|`1080p`\|`2k`\|`4k`, **no CLI default** — omit it and the server picks `1080p` (do NOT pass `4k` "to be safe", it is the most expensive video tier). **Ignored by image `--model crisp`** and **video `--model fps`** (no resolution option); video `--model pro` does not accept `720p` |
+| `--video` | Force every file in this command to be treated as **video** — only needed when a URL hides its extension (e.g. a signed URL); local paths and URLs ending in `.mp4`/`.mov`/`.webm` are auto-detected, no flag needed |
+| `--crid <id>` | idempotency key; the CLI appends `-0`, `-1`, ... per file so retrying the exact same multi-file command is safe |
+
+Image model choice (ask the user if unclear, or default to `standard`):
+
+| Model | Best for | Notes |
+|---|---|---|
+| `crisp` | quick sharpen, fixed output size | cheapest; does **not** accept `--resolution` |
+| `standard` | general 2K/4K/8K upscale | default |
+| `seedvr2` | best detail retention on faces/text | pricier than `standard` |
+| `ultra` | highest quality, large enlargements | most expensive — confirm cost before running |
+
+Video model choice (ask the user if unclear, or default to `standard`):
+
+| Model | Resolutions | Best for | Notes |
+|---|---|---|---|
+| `standard` | 720p/1080p/2k/4k | general video upscale | default; wait ≈10× the clip length |
+| `pro` | 1080p/2k/4k (no 720p) | highest-fidelity tier | **slowest**, wait ≈25-30× the clip length |
+| `seedvr2` | 720p/1080p/2k/4k | best detail retention | wait ≈6-27× the clip length (higher resolutions are slower) |
+| `fps` | none (ignores `--resolution`) | double the frame rate | **fastest**, wait ≈2-3× the clip length |
+
+Video caps: **300MB / 10 minutes** input. Billing is per second of input,
+rounded up to the next whole second; if that is still below the model
+minimum (`standard`/`seedvr2`: 3s, `pro`/`fps`: 1s) it bills at the minimum
+instead — e.g. a 2s clip on `standard` bills as 3s (30 credits, not 20).
+
+## Before running
+
+1. `qm auth status` → not logged in → `qm auth login`.
+2. `qm models list --type image` does **not** list upscale pricing (it's a
+   separate catalog) — quote credit cost from the table below instead.
+
+## Quote, then confirm
+
+**Image** — state the per-image credit cost **× number of images** and get
+confirmation before running — submitting holds credit immediately, one hold
+per image:
+
+| Model | Credits/image |
+|---|---|
+| `crisp` | 10 |
+| `standard` | 20 |
+| `seedvr2` | 20 |
+| `ultra` | 116 |
+
+**Video** — credits are **per second of input** (not per file); estimate
+from the clip's duration (`ffprobe`, or ask the user): round the seconds up
+to the next whole second, floor that at the model's minimum (`standard`/
+`seedvr2`: 3s, `pro`/`fps`: 1s), then × the rate below — confirm the result
+before running (do not quote a lower number for clips under the minimum):
+
+| Model | 720p | 1080p | 2k | 4k |
+|---|---|---|---|---|
+| `standard` | 10 | 10 | 20 | 39 |
+| `pro` | — (unsupported) | 14 | 28 | 56 |
+| `seedvr2` | 39 | 77 | 96 | 116 |
+| `fps` | 16 (flat, no resolution) | | | |
+
+## Run + track
+
+No `--wait` flag. The CLI prints one job hint per file
+(`→ Theo dõi: quickmagic jobs get ups_5` for images, `vup_5` for videos);
+collect every id from the output, then `qm jobs wait <id> --out ./out` for
+each — single `result_url` per job, `--out` auto-downloads. Video processing
+is slow (see per-model wait multipliers above) — a `processing` status
+(including while the finished file is still being saved) is normal, keep
+waiting, do not resubmit. Report every final URL + total `credits_charged`.
+Result files follow the account plan retention (free plan: 5 days —
+download promptly; paid plans: long-term).
+
+## Errors
+
+`Không đủ credit: ...` → state shortfall + https://quickmagic.vn/pricing.
+Any other failure prints `Lỗi: <message>` and stops the whole command (a
+prior file's job may already be submitted/charged — check with
+`qm jobs get ups_<n>` / `qm jobs get vup_<n>` before retrying that one
+file). Full reference: `quickmagic-account` skill.
+
+## Example
+
+```bash
+qm upscale ./old-photo.jpg --model standard --resolution 4k
+qm upscale ./a.jpg ./b.jpg ./c.jpg --model seedvr2 --resolution 8k
+qm jobs wait ups_5 --out ./out
+
+qm upscale ./clip.mp4 --model standard --resolution 1080p
+qm upscale https://files.quickmagic.cloud/media-tools/clip.mp4 --model fps
+qm jobs wait vup_12 --out ./out
+```

package/src/commands/apps.js

@@ -0,0 +1,76 @@
+// commands/apps.js — Ứng dụng React SSR trên <slug>.quickmagic.app (Apps đợt B): create / list / status / deploy / publish / remove.
+// KHÔNG có `apps db` / `apps secrets` (bề mặt nhạy cảm — chỉ agent qua MCP). repo-access in clone_url ra stdout theo yêu cầu tường minh.
+const api = require('../api');
+
+const SLEEP = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function printApp(a) {
+  console.log(`${a.title || '(chưa tên)'}  [${a.id}]`);
+  console.log(`  URL:      ${a.url || '—'}`);
+  console.log(`  Deploy:   ${a.deploy_status || '—'}${a.last_build ? ` (build #${a.last_build.id} ${a.last_build.status}${a.last_build.error_code ? ' ' + a.last_build.error_code : ''})` : ''}`);
+  console.log(`  Duyệt:    ${a.review_status || '—'} · công khai: ${a.is_public ? 'có' : 'không'} · cover: ${a.thumb_url ? 'có' : 'chưa'} · DB: ${a.has_db ? 'có' : 'không'}`);
+  if (a.has_unbuilt_commits) console.log('  ⚠️ Có commit chưa deploy — chạy: qm apps deploy <app_id>');
+  if (a.last_build && a.last_build.error_text) console.log(`  Lỗi build: ${String(a.last_build.error_text).slice(0, 300)}`);
+}
+
+async function create(options) {
+  const body = { title: options.title, subdomain: options.subdomain, category: options.category, description: options.description };
+  if (options.from) body.from_app_id = options.from;
+  const data = await api.call('POST', '/apps', { body });
+  console.log(`Đã tạo app ${data.id}${data.remixed_from ? ` (remix từ "${data.remixed_from.title}")` : ''}`);
+  printApp(data);
+  console.log('Tiếp: qm apps repo-access <app_id> → git clone → sửa → push → qm apps deploy <app_id>');
+}
+async function list() {
+  const data = await api.call('GET', '/apps');
+  const apps = data.apps || [];
+  if (!apps.length) { console.log('Chưa có app nào. Tạo: qm apps create --title "Tên app"'); return; }
+  const id_w = 36, slug_w = Math.max(4, ...apps.map((a) => String(a.slug || '').length));
+  console.log(`${'APP_ID'.padEnd(id_w)}  ${'SLUG'.padEnd(slug_w)}  DEPLOY     DUYỆT     PUBLIC  TITLE`);
+  for (const a of apps) console.log(`${a.id.padEnd(id_w)}  ${String(a.slug || '').padEnd(slug_w)}  ${String(a.deploy_status || '').padEnd(9)}  ${String(a.review_status || '').padEnd(8)}  ${a.is_public ? 'có ' : 'không'}   ${a.title || ''}`);
+}
+async function status(app_id, options) {
+  const data = await api.call('GET', `/apps/${encodeURIComponent(app_id)}`);
+  if (options && options.json) { console.log(JSON.stringify(data, null, 2)); return; }
+  printApp(data);
+}
+async function repoAccess(app_id) {
+  const data = await api.call('POST', `/apps/${encodeURIComponent(app_id)}/repo-access`, { body: {} });
+  // In clone_url có token TTL 15' — người dùng CLI chủ động xin, KHÔNG log ở nơi khác.
+  console.log(`Quyền push repo (hết hạn ${data.expires_at}):`);
+  console.log(data.clone_url);
+  console.log(`git clone ${data.clone_url} app && cd app`);
+}
+async function deploy(app_id, options) {
+  const data = await api.call('POST', `/apps/${encodeURIComponent(app_id)}/deploy`, { body: {} });
+  console.log(`Đã xếp hàng build #${data.build_id} → ${data.url}`);
+  if (!options || !options.wait) { console.log('Theo dõi: qm apps status <app_id>'); return; }
+  for (let i = 0; i < 60; i++) {
+    await SLEEP(5000);
+    const s = await api.call('GET', `/apps/${encodeURIComponent(app_id)}`);
+    const b = s.last_build;
+    if (b && String(b.id) === String(data.build_id) && ['succeeded', 'failed'].includes(b.status)) {
+      if (b.status === 'succeeded') { console.log(`✅ Deploy xong (${Math.round((b.duration_ms || 0) / 1000)}s): ${s.url}`); return; }
+      console.error(`❌ Build thất bại (${b.error_code || 'lỗi'}): ${String(b.error_text || '').slice(0, 400)}`); process.exit(1);
+    }
+    process.stdout.write(`  … ${b ? b.step || b.status : 'queued'}\r`);
+  }
+  console.error('Hết 5 phút chưa xong — kiểm: qm apps status <app_id>'); process.exit(1);
+}
+async function publish(app_id, options) {
+  try {
+    const data = await api.call('POST', `/apps/${encodeURIComponent(app_id)}/publish`, { body: { is_public: !(options && options.unlist) } });
+    console.log(data.is_public ? `✅ Đã công khai lên feed Ứng dụng: ${data.url}` : 'Đã gỡ khỏi feed (link trực tiếp vẫn hoạt động).');
+  } catch (e) {
+    const m = String(e.message || '');
+    if (/APP_REVIEW_PENDING|chờ duyệt/.test(m)) { console.log('⏳ App đang chờ duyệt nội dung (app đầu tiên của tài khoản được duyệt tay). Link trực tiếp vẫn dùng được.'); return; }
+    throw e;
+  }
+}
+async function remove(app_id, options) {
+  if (!options || !options.yes) { console.error('Xoá VĨNH VIỄN app (Worker + DB + repo, subdomain khoá mãi). Xác nhận bằng --yes.'); process.exit(1); }
+  const data = await api.call('DELETE', `/apps/${encodeURIComponent(app_id)}`);
+  console.log(`Đã xoá app ${data.slug || app_id}.`);
+}
+
+module.exports = { create, list, status, repoAccess, deploy, publish, remove };

package/src/commands/jobs.js

@@ -8,6 +8,38 @@ const POLL_INTERVAL_MS = 2500;
 const TERMINAL_STATUSES = new Set(['completed', 'error', 'failed', 'success', 'stalled', 'timeout']);
 const SUCCESS_STATUSES = new Set(['completed', 'success']);
 
+// [P3 portrait, plans/260818-1521 bước 9] Ảnh người thật Seedance 2.x đi qua kho ảo pass-through —
+// job có thể đứng "đang xử lý" tới ~10' ở lần đầu dùng 1 ảnh. R12: jobs-view có thể còn đánh dấu
+// job xếp hàng >15' là 'stalled' (fix ở BE phase sau) → agent/script CHẠY --wait tuyệt đối KHÔNG
+// được suy ra "job kẹt, tạo job mới thử lại" (tạo job đôi, trừ tiền 2 lần). portrait_state đọc trực
+// tiếp từ response — override cách hiểu bất kể server còn gắn status gì.
+const PORTRAIT_PREPARING_STATES = new Set(['awaiting_asset', 'asset_ready']);
+
+// Gợi ý theo error_code B′ (đối chiếu backend-quick-magic/services/portrait/portrait-errors.js — 17 mã).
+const PORTRAIT_HINTS = {
+  PORTRAIT_PUBLIC_FIGURE: 'dùng ảnh người thường, không phải người nổi tiếng',
+  PORTRAIT_MINOR: 'dùng ảnh người lớn, không phải trẻ em',
+  PORTRAIT_NSFW: 'dùng ảnh khác, tránh nội dung nhạy cảm',
+  PORTRAIT_GEMINI_UNAVAILABLE: 'thử lại sau vài phút',
+  PORTRAIT_ASSET_FAILED: 'thử ảnh khác, rõ mặt, chỉ 1 người',
+  PORTRAIT_ASSET_REJECTED: 'ảnh bị bộ lọc nội dung từ chối (người nổi tiếng/trẻ em/nhạy cảm/bản quyền) — dùng ảnh khác',
+  PORTRAIT_TIMEOUT: 'thử lại sau vài phút',
+  PORTRAIT_QUOTA_FULL: 'thử lại sau vài phút',
+  PORTRAIT_IMAGE_HOST: 'tải ảnh lên QM trước (dùng --image <file>)',
+  PORTRAIT_IMAGE_FETCH_FAILED: 'thử lại sau vài phút',
+  PORTRAIT_PROVIDER_ERROR: 'thử lại sau vài phút',
+  PORTRAIT_PROVIDER_FAILED: 'ảnh bị từ chối theo chính sách nội dung (người nổi tiếng/trẻ em/nhạy cảm/bản quyền) — dùng ảnh khác',
+  PORTRAIT_COPYRIGHT: 'ảnh bị từ chối vì bản quyền/quyền hình ảnh (người nổi tiếng, nhân vật/tác phẩm được bảo hộ) — dùng ảnh khác',
+  PORTRAIT_DISABLED: 'đổi --model gemini-omni (nhận ảnh người thật)',
+  PORTRAIT_TOO_MANY_IMAGES: 'bớt số ảnh có người thật trong yêu cầu',
+  PORTRAIT_VIDEO_REF_UNSUPPORTED: 'dùng --image thay --video-ref, hoặc đổi model',
+  REAL_PERSON_BLOCKED: 'đổi --model gemini-omni (nhận ảnh người thật)',
+};
+function hintFor(code) {
+  const h = PORTRAIT_HINTS[code];
+  return h ? ` — gợi ý: ${h}` : '';
+}
+
 function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
@@ -36,11 +68,23 @@ async function waitOne(id, out_dir) {
   for (;;) {
     const data = await api.call('GET', `/jobs/${id}`);
     const status = data.status;
+
+    // [P3 portrait, R12] job đang chuẩn bị ảnh có người thật — KHÔNG coi là stalled/lỗi, KHÔNG gợi ý
+    // chạy lại lệnh dù đợi lâu. In thẳng rồi tiếp tục poll, bỏ qua nhánh TERMINAL_STATUSES lượt này
+    // (server có deadline riêng ~10' sẽ tự chuyển job sang failed thật nếu quá hạn — vòng lặp không treo mãi).
+    if (PORTRAIT_PREPARING_STATES.has(data.portrait_state)) {
+      console.log(`[${id}] đang chuẩn bị ảnh có người thật (tối đa ~10 phút) — đừng tạo job mới…`);
+      await sleep(POLL_INTERVAL_MS);
+      continue;
+    }
+
     const progress = data.progress != null ? ` (${data.progress}%)` : '';
     console.log(`[${id}] ${status}${progress}`);
     if (TERMINAL_STATUSES.has(status)) {
       if (SUCCESS_STATUSES.has(status)) {
         if (data.result_url && out_dir) await download(data.result_url, out_dir);
+      } else if (data.error_code) {
+        console.error(`[${id}] Lỗi [${data.error_code}]: ${data.error || status}${hintFor(data.error_code)}`);
       } else {
         console.error(`[${id}] job lỗi: ${data.error || status}`);
       }

package/src/commands/models.js

@@ -1,4 +1,6 @@
-// commands/models.js — liệt kê model ảnh/video dạng bảng key | label | credit (+IMAGES cho video).
+// commands/models.js — liệt kê model ảnh/video/nhạc dạng bảng key | label | credit (+IMAGES cho
+// video). `qm models list --type music` dùng chung hàm này; bảng ĐẦY ĐỦ hơn (giá/ETA/hàng chờ) nằm
+// ở `qm music models` (commands/music.js) — dành cho ai đã quen `qm models list` chung 1 lệnh.
 const api = require('../api');
 
 // Cột IMAGES (video): "ref 9* · frames 2" — theo image_max_by_mode; * = mode cấm ảnh người thật.
@@ -44,6 +46,11 @@ async function list(options) {
     console.log('  rồi dùng ảnh đó (provider chấp nhận ảnh thuần Seedream 5.0 Pro — đã probe thật 260808).');
     console.log('  Hoặc dùng model không dấu *: gemini-omni / wan-3-0 / wan-2-7 / seedance 1.x nhận ảnh người trực tiếp.');
   }
+  // [Portrait 260819] server bật pass-through → model từng cấm người thật giờ trả real_person_note (không còn dấu *)
+  if (is_video && models.some((m) => m.real_person_note)) {
+    console.log('\nℹ Ảnh người thật: Seedance 2.x nhận bình thường — hệ thống chuẩn bị ảnh thêm ~1-3 phút ở lần đầu dùng 1 ảnh');
+    console.log('  (qm jobs wait tự chờ). Nếu bộ lọc nội dung của model từ chối (bản quyền/chính sách), job failed kèm lý do rõ, credit hoàn.');
+  }
 }
 
 module.exports = { list };

package/src/commands/music.js

@@ -0,0 +1,109 @@
+// commands/music.js — qm music create/lyrics/models/get (Xưởng Nhạc Melo: REST /music, /music/lyrics,
+// /models?type=music, /jobs/mus_<n>). Tách khỏi tools.js vì cần đọc file lời + gộp --wait + in bảng.
+const fs = require('fs');
+const path = require('path');
+const { call } = require('../api');
+const jobs = require('./jobs');
+
+const out = (data) => console.log(JSON.stringify(data, null, 2));
+// [mirror voice.js] api.js đã gắn err.code từ REST {code,message} → in kèm code để rẽ nhánh (retryable
+// 5xx/429 vs không 4xx).
+const run = (fn) => (...a) => fn(...a).catch((e) => {
+  console.error(e.code ? `Lỗi [${e.code}]: ${e.message}` : `Lỗi: ${e.message}`);
+  process.exit(1);
+});
+
+// Bảng text căn cột đơn giản — repo không có thư viện bảng, KHÔNG thêm dependency mới (mirror voice.js).
+function printTable(headers, rows) {
+  const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => String(r[i] == null ? '' : r[i]).length)));
+  const line = (cells) => cells.map((c, i) => String(c == null ? '' : c).padEnd(widths[i])).join('  ');
+  console.log(line(headers));
+  console.log(widths.map((w) => '-'.repeat(w)).join('  '));
+  for (const r of rows) console.log(line(r));
+}
+
+function priceLabel(m) {
+  return m.free_launch ? 'Miễn phí (giai đoạn ra mắt)' : `${m.credit} credit/bài`;
+}
+
+// ── music models ──
+const models = run(async () => {
+  const data = await call('GET', '/models?type=music');
+  const rows = data.models || [];
+  if (!rows.length) {
+    console.log('Không có model nào.');
+    return;
+  }
+  printTable(
+    ['KEY', 'LABEL', 'GIÁ', 'ETA (s)', 'HÀNG CHỜ'],
+    rows.map((m) => [m.key, m.label, priceLabel(m), m.eta_seconds, m.queue_capacity]),
+  );
+  if (rows.some((m) => m.free_launch)) {
+    console.log('\nGiá đang MIỄN PHÍ giai đoạn ra mắt — có thể đổi bất kỳ lúc nào, luôn kiểm tra lại trước khi tạo bài.');
+  }
+});
+
+// ── music lyrics — AI viết lời (0đ) ──
+const lyrics = run(async (o) => {
+  if (!o.desc) throw new Error('Cần --desc');
+  const data = await call('POST', '/music/lyrics', {
+    body: { description: o.desc, title: o.title, language: o.language, instrumental: !!o.instrumental },
+  });
+  console.log(`Tiêu đề: ${data.title}`);
+  console.log(`Phong cách: ${data.style_tags}`);
+  console.log('');
+  console.log(data.lyrics || '(bản không lời — chỉ có tiêu đề + phong cách)');
+});
+
+// ── music create ──
+const create = run(async (o) => {
+  // [P06b-L5 fix 260818] Server (validateMinimal, music-submit-service.js) CHẤP instrumental chỉ cần
+  // styles HOẶC description, không cần cả 2 — guard cục bộ cũ hẹp hơn hợp đồng, chặn oan
+  // `--instrumental --styles "lofi"` không --desc. Nới điều kiện cho khớp.
+  if (!o.desc && !o.lyrics && !o.lyricsFile && !(o.instrumental && o.styles)) {
+    throw new Error('Cần --desc (mode simple/instrumental) hoặc --lyrics/--lyrics-file (mode custom) hoặc --instrumental kèm --styles');
+  }
+  // [P06b-L5 fix 260818] --out mà thiếu --wait trước đây bị LỜ ÂM THẦM (waitAll chỉ chạy khi o.wait) —
+  // tự bật --wait để --out thực sự có tác dụng, kèm cảnh báo cho user biết.
+  if (o.out && !o.wait) {
+    console.log('Lưu ý: có --out nhưng thiếu --wait — tự động bật --wait để tải file khi bài xong.');
+    o.wait = true;
+  }
+
+  // [KI #11] Đọc giá + free_launch NGAY TRƯỚC submit — gửi kèm expected_free chống lệch giá giữa lúc
+  // quote và lúc submit thật (server fail-closed trả price_changed nếu lệch, KHÔNG âm thầm thu tiền).
+  const catalog = await call('GET', '/models?type=music');
+  const model_key = o.model || 'melo-3';
+  const m = (catalog.models || []).find((x) => x.key === model_key);
+  if (!m) {
+    console.log(`Cảnh báo: không tìm thấy model "${model_key}" trong catalog hiện tại — vẫn thử gửi, server sẽ báo lỗi nếu sai.`);
+  } else {
+    console.log(priceLabel(m));
+  }
+
+  const lyrics_text = o.lyricsFile ? fs.readFileSync(path.resolve(o.lyricsFile), 'utf8') : o.lyrics;
+  const data = await call('POST', '/music', {
+    body: {
+      mode: o.mode || 'simple', description: o.desc, lyrics: lyrics_text, title: o.title, model: model_key,
+      styles: o.styles ? o.styles.split(',').map((s) => s.trim()).filter(Boolean) : undefined,
+      instrumental: !!o.instrumental, vocal_gender: o.gender,
+      expected_free: m ? m.free_launch : undefined, client_request_id: o.crid,
+    },
+  });
+  out(data);
+  console.log(`\n→ Theo dõi: qm music get ${data.job_id}`);
+  if (o.wait) {
+    // [KI #16] --out là THƯ MỤC (jobs.waitAll → fs.mkdirSync(out_dir) rồi ghi basename từ URL) —
+    // truyền --out song.mp3 sẽ tạo THƯ MỤC tên song.mp3, không phải file. Dùng --out ./out.
+    await jobs.waitAll([data.job_id], o.out);
+    out(await call('GET', `/jobs/${data.job_id}`));
+  }
+});
+
+// ── music get — chấp cả mus_<n> lẫn số trần ──
+const get = run(async (id) => {
+  const job_id = String(id).startsWith('mus_') ? id : `mus_${id}`;
+  out(await call('GET', `/jobs/${job_id}`));
+});
+
+module.exports = { create, lyrics, models, get };

package/src/commands/tools.js

@@ -12,7 +12,9 @@ const jobHint = (data) => {
   const id = data.job_id || (Array.isArray(data.job_ids) && data.job_ids[0]);
   if (id) console.log(`\n→ Theo dõi: quickmagic jobs get ${id}`);
 };
-const run = (fn) => (...a) => fn(...a).catch((e) => { console.error('Lỗi:', e.message); process.exit(1); });
+// [code-review-p03.md L8] api.js#call gán e.code = json.code (REST giữ nguyên code cho mục đích này) —
+// bản cũ chỉ in message, script/agent đọc stderr KHÔNG phân biệt được 'feature_disabled' với lỗi khác.
+const run = (fn) => (...a) => fn(...a).catch((e) => { console.error('Lỗi:', e.code ? `[${e.code}] ${e.message}` : e.message); process.exit(1); });
 
 // ── Nhập liệu (không tốn credit) ──
 const scrape = run(async (url) => out(await call('POST', '/scrape', { body: { url } })));
@@ -29,7 +31,39 @@ const product = run(async (o) => jobHint(await call('POST', '/product/images', {
 const fashion = run(async (o) => jobHint(await call('POST', '/fashion/images', { body: { mode: o.mode, outfit_ids: (o.outfit || []).map(Number), kol_kind: o.kolKind, kol_id: o.kolId ? Number(o.kolId) : undefined, model: o.model, client_request_id: o.crid } })));
 
 // ── Ảnh ──
-const edit = run(async (image, o) => jobHint(await call('POST', '/edit', { body: { image: await rmi(image), tool: o.tool, model: o.model, upscale_target: o.upscaleTarget, style: o.style, client_request_id: o.crid } })));
+const edit = run(async (image, o) => jobHint(await call('POST', '/edit', { body: { image: await rmi(image), tool: o.tool, model: o.model, style: o.style, client_request_id: o.crid } })));
+// [260825, plans/260825-1344-upscale-studio-hf-clone P04] 1 lệnh CLI = N file = N job (mỗi file 1
+// job/hold riêng, REST /upscale(-video) chỉ nhận 1 file/call). --crid dùng CHUNG y nguyên cho cả vòng
+// lặp sẽ khiến BE coi file 2+ TRÙNG file 1 (idempotency theo client_request_id) → chỉ file đầu có job
+// thật, các file sau lặng lẽ trả về CÙNG job đó (thiếu file, không lỗi rõ ràng) — hậu tố `-${i}` cho
+// mỗi file 1 khoá riêng, vẫn giữ được idempotency khi retry NGUYÊN LỆNH (cùng --crid, cùng thứ tự file).
+//
+// [260826, plans/260826-1200-upscale-video-hf-clone-byteplus-vcube P03] mở rộng ẢNH → VIDEO cùng lệnh:
+// --video ép mọi file coi là video; không truyền thì tự nhận theo đuôi .mp4/.mov/.webm (KHÔNG .m4v —
+// media.js/get_upload_url không có mime cho đuôi này). data:video/ hoặc data:image/ (file ≤64KB đã
+// inline) tự nhận theo mime, KHÔNG cần đuôi.
+const VIDEO_EXT_RE = /\.(mp4|mov|webm)(\?.*)?$/i;
+function looksLikeVideo(ref) {
+  if (/^data:video\//i.test(ref)) return true;
+  if (/^data:image\//i.test(ref)) return false;
+  if (/^https?:\/\//i.test(ref)) {
+    try { return VIDEO_EXT_RE.test(new URL(ref).pathname); } catch { return false; }
+  }
+  return VIDEO_EXT_RE.test(ref);
+}
+const upscale = run(async (files, o) => {
+  for (const [i, f] of files.entries()) {              // LẶP — không phải files[0]
+    const crid = o.crid ? `${o.crid}-${i}` : undefined;
+    const is_video = !!o.video || looksLikeVideo(f);
+    // [code-review-p03.md H3] --resolution KHÔNG còn default ở commander (index.js). Ảnh: giữ default
+    // '4k' CŨ (P04, chỉ áp khi user không truyền). Video: KHÔNG tự thêm default — để trống thì server
+    // (createMediaJobs) tự chọn default_resolution 1080p, tránh CLI âm thầm gửi bậc giá đắt nhất.
+    const res = is_video
+      ? await call('POST', '/upscale-video', { body: { video: await rmi(f), model: o.model, resolution: o.resolution, client_request_id: crid } })
+      : await call('POST', '/upscale', { body: { image: await rmi(f), model: o.model, resolution: o.resolution || '4k', client_request_id: crid } });
+    jobHint(res);                                       // in job_id từng file
+  }
+});
 const tryon = run(async (o) => jobHint(await call('POST', '/tryon', { body: { type: o.type, model: o.model, model_image: await rmi(o.model_image), garment_image: await rmi(o.garment), upper_image: await rmi(o.upper), lower_image: await rmi(o.lower), background_image: await rmi(o.background), prompt: o.prompt, client_request_id: o.crid } })));
 
 // ── Video nặng / audio ──
@@ -43,4 +77,4 @@ const cutout = run(async (o) => jobHint(await call('POST', '/cutout', { body: {
 const hookPresets = run(async () => out(await call('GET', '/hook/presets')));
 const hookVideo = run(async (o) => jobHint(await call('POST', '/hook/videos', { body: { preset_id: o.preset, character_url: await rmi(o.character), product_url: await rmi(o.product), aspect: o.aspect, speech_lang: o.speechLang, custom_cta: o.cta, location_url: o.location, accessory_url: o.accessory, style: o.style, format: o.format, resolution: o.resolution, client_request_id: o.crid } })));
 
-module.exports = { scrape, importSocial, assets, analyze, marketingModes, marketingVideo, product, fashion, edit, tryon, stt, subtitle, split, motion, cutout, hookPresets, hookVideo };
+module.exports = { scrape, importSocial, assets, analyze, marketingModes, marketingVideo, product, fashion, edit, upscale, tryon, stt, subtitle, split, motion, cutout, hookPresets, hookVideo };

package/src/commands/voice.js

@@ -66,6 +66,8 @@ const voicesList = run(async (o) => {
   const data = await call('GET', `/voices${buildQuery({ model: o.model, language: o.language, search: o.search, limit: o.limit })}`);
   const pricing = data.pricing || {}; // [review C4] BE lỗi/shape cũ → không crash, in được phần còn lại
   printPricing(pricing);
+  // qimi_3.5: server builds this hint from its own preset list — print it verbatim instead of hard-coding keys here.
+  if (data.style_hint) console.log(data.style_hint);
   if (pricing.billing === 'per_char') {
     if (data.clone_price != null) console.log(`Giá clone giọng riêng: ${data.clone_price} credit`);
     // [review C2] false có 2 nghĩa: (a) đã dùng suất, (b) chưa có gói trả phí active (BE trả first_free_upsell=true).
@@ -93,7 +95,12 @@ const voicesList = run(async (o) => {
     }
     if (systems.length) {
       console.log('Giọng hệ thống:');
-      printTable(['VOICE', 'NAME', 'NAME_EN', 'GENDER', 'LANGUAGE'], systems.map((v) => [v.voice, v.name, v.name_en, v.gender, v.language]));
+      // qimi_3.5 system voices (the qimi_3 catalog) have no English name — drop the empty column.
+      const has_en = systems.some((v) => v.name_en);
+      printTable(
+        has_en ? ['VOICE', 'NAME', 'NAME_EN', 'GENDER', 'LANGUAGE'] : ['VOICE', 'NAME', 'GENDER', 'LANGUAGE'],
+        systems.map((v) => (has_en ? [v.voice, v.name, v.name_en, v.gender, v.language] : [v.voice, v.name, v.gender, v.language])),
+      );
     }
   }
   console.log(`\nNgôn ngữ: ${(data.languages || []).join(' · ')}`);

package/src/index.js

@@ -10,6 +10,8 @@ const models = require('./commands/models');
 const credits = require('./commands/credits');
 const tools = require('./commands/tools');
 const voice = require('./commands/voice');
+const music = require('./commands/music');
+const apps = require('./commands/apps');
 
 const collect = (v, acc) => { acc.push(v); return acc; };
 
@@ -51,7 +53,7 @@ gen_cmd
   .option('--resolution <r>', 'Độ phân giải (vd 720p, 1080p)')
   .option('--aspect-ratio <r>', 'Tỉ lệ khung')
   .option('--image <i...>', 'Ảnh đầu vào (URL hoặc file local, lặp nhiều lần — max theo model+mode, xem qm models)')
-  .option('--mode <m>', 'Chế độ ảnh: reference (nhiều ảnh tham chiếu) | frames (khung đầu/cuối, max 2). Seedance 2.x KHÔNG nhận ảnh người thật ở MỌI chế độ (xem qm models --type video)')
+  .option('--mode <m>', 'Chế độ ảnh: reference (nhiều ảnh tham chiếu) | frames (khung đầu/cuối, max 2). Seedance 2.x nhận ảnh người thật ở mọi chế độ (hệ thống chuẩn bị ảnh thêm ~1-3 phút lần đầu; nếu bộ lọc nội dung của model từ chối — bản quyền/chính sách — CLI in rõ lý do, credit hoàn; xem README mục "Ảnh người thật")')
   .option('--video-ref <v>', 'Video tham chiếu (URL hoặc file local, max 15s/100MB) — CHỈ model supports_video_ref (seedance-2-0/-fast). Giá = rate with-video × (giây output + giây video); không dùng chung với --image')
   .option('--seed <n>', 'Seed cố định — cùng seed + cùng prompt cho kết quả LẶP LẠI được (giữ nhất quán khi render nhiều cảnh)', parseInt)
   .option('--negative <p>', 'Mô tả thứ KHÔNG muốn xuất hiện (watermark, chữ, tay thừa…) — model nào không hỗ trợ thì bỏ qua')
@@ -93,7 +95,7 @@ const models_cmd = program.command('models').description('Model AI');
 models_cmd
   .command('list')
   .description('Liệt kê model')
-  .option('--type <t>', 'Loại: image | video', 'image')
+  .option('--type <t>', 'Loại: image | video | music', 'image')
   .action(models.list);
 
 // ── credits ──────────────────────────────────────────────────────────────────
@@ -129,9 +131,22 @@ program.command('fashion').description('Tạo ảnh thời trang AI')
   .action(tools.fashion);
 
 // ── Ảnh ────────────────────────────────────────────────────────────────────────
-program.command('edit <image>').description('Sửa ảnh: restore/upscale/beauty/muscle/color_boost')
+program.command('edit <image>').description('Sửa ảnh: restore/beauty/muscle/color_boost (upscale → dùng lệnh `qm upscale`)')
   .requiredOption('--tool <t>').option('--model <m>', 'qimi_2.5|qimi_3', 'qimi_3')
-  .option('--upscale-target <t>', '2k|4k').option('--style <s...>').option('--crid <id>').action(tools.edit);
+  .option('--style <s...>').option('--crid <id>').action(tools.edit);
+// [260826, plans/260826-1200-upscale-video-hf-clone-byteplus-vcube P03] mở rộng ẢNH → VIDEO cùng lệnh
+// (giữ nguyên tên arg <image...> — đã pin cứng trong test BE mcp-upscale-wiring.test.js). Video tự
+// nhận theo đuôi .mp4/.mov/.webm (KHÔNG .m4v — media.js/get_upload_url không có mime cho đuôi này),
+// hoặc ép bằng --video khi URL không lộ đuôi (vd link ký chữ ký).
+program.command('upscale <image...>').description('Upscale ảnh (crisp|standard|seedvr2|ultra) hoặc video (standard|pro|seedvr2|fps) — 1 lệnh nhiều file = mỗi file 1 job. File video: .mp4/.mov/.webm, tự nhận theo đuôi hoặc ép bằng --video')
+  .option('--model <m>', 'Ảnh: crisp|standard|seedvr2|ultra — Video: standard|pro|seedvr2|fps', 'standard')
+  // [code-review-p03.md H3] KHÔNG đặt default ở đây — default '4k' hợp lý cho ẢNH (giữ nguyên hành vi
+  // cũ P04) nhưng SAI cho VIDEO (server default là 1080p, rẻ hơn 4k standard 3.9×). Default lệch theo
+  // media_type xử lý TRONG tools.upscale (ảnh mới rơi về '4k' khi không truyền; video để trống, server tự chọn).
+  .option('--resolution <r>', 'Ảnh: 2k|4k|8k, mặc định 4k (bỏ qua crisp) — Video: 720p|1080p|2k|4k, mặc định 1080p do server chọn khi không truyền (bỏ qua fps, pro không nhận 720p)')
+  .option('--video', 'Ép MỌI file trong lệnh này là VIDEO (mặc định tự nhận theo đuôi .mp4/.mov/.webm)')
+  .option('--crid <id>', 'client_request_id (tự thêm hậu tố theo từng file)')
+  .action(tools.upscale);
 program.command('tryon').description('Thử đồ ảo (virtual try-on)')
   .requiredOption('--model-image <img>', 'Ảnh người mẫu (URL/base64)')
   .option('--type <t>', 'full|upper', 'full').option('--model <m>', 'qimi_1.5|qimi_2.5|qimi_3', 'qimi_3')
@@ -149,28 +164,46 @@ program.command('motion <video_url>').description('Áp chuyển động video v
   .requiredOption('--image <url...>', 'Ảnh áp motion (1-20)')
   .option('--model <m>').option('--mode <m>', 'standard|professional').option('--prompt <p>').option('--crid <id>').action(tools.motion);
 
+// ── Media-tools mở rộng [260902] — cùng kho model Spaces "Bàn Sáng Tạo" ─────
+program.command('sfx <prompt>').description('Tạo hiệu ứng âm thanh từ mô tả (whoosh/nổ/mưa/bước chân…)')
+  .option('--model <m>', 'sfx-lite (mặc định) | sfx-pro').option('--duration <s>', 'Giây: lite 3/5/10/15/30, pro 3/5/10/15 (mặc định 5)').option('--crid <id>').action(tools.sfx);
+program.command('remove-bg <image>').description('Tách nền ảnh → PNG trong suốt')
+  .option('--crid <id>').action(tools.removeBg);
+const t3d = program.command('3d').description('Model 3D (.glb): tạo từ ảnh/mô tả + hoạt hình');
+t3d.command('create').description('Tạo model 3D từ ảnh hoặc mô tả')
+  .option('--image <i>', 'Ảnh tham chiếu (file/URL)').option('--prompt <p>', 'Mô tả model')
+  .option('--model <m>', 'tripo-v3 (mặc định) | tripo-v2-5').option('--texture <t>', 'standard | textureless').option('--crid <id>').action(tools.gen3d);
+t3d.command('animate <model_url>').description('Hoạt hình model 3D đã tạo (rig + preset chuyển động)')
+  .option('--preset <p>', 'Tên preset (vd dance_01, wave_goodbye_01)').option('--crid <id>').action(tools.animate3d);
+program.command('talking-photo').description('Ảnh chân dung + audio → video nói chuyện (khớp môi)')
+  .requiredOption('--image <i>', 'Ảnh chân dung (file/URL)').requiredOption('--audio <url>', 'Audio giọng nói (vd kết quả qm tts)')
+  .option('--model <m>', 'talk-fast (mặc định) | talk-standard').option('--resolution <r>', '480p | 720p (talk-standard)').option('--prompt <p>', 'Gợi ý biểu cảm').option('--crid <id>').action(tools.talkingPhoto);
+program.command('extend-video <video_url>').description('Kéo dài video — sinh tiếp N giây sau khung cuối')
+  .requiredOption('--duration <s>', 'Giây đoạn mới: wan 3-10, seedance 4-15')
+  .option('--model <m>', 'vext-wan-2-5 (mặc định) | vext-seedance-2-0').option('--resolution <r>', '480p/720p/1080p (+4k seedance)').option('--prompt <p>', 'Điều xảy ra tiếp theo').option('--crid <id>').action(tools.extendVideo);
+
 // ── TTS / Voices ─────────────────────────────────────────────────────────────
 program
   .command('tts')
-  .description('Chuyển văn bản → giọng nói (5 engine qimi_1.5/2.5/3/5/5.5)')
+  .description('Chuyển văn bản → giọng nói (6 engine qimi_1.5/2.5/3/3.5/5/5.5)')
   .option('--text <t>', 'Văn bản cần đọc')
   .option('--file <path>', 'Đọc văn bản từ file local (thay --text)')
-  .option('--model <m>', 'qimi_1.5|qimi_2.5|qimi_3|qimi_5|qimi_5.5', 'qimi_3')
+  .option('--model <m>', 'qimi_1.5|qimi_2.5|qimi_3|qimi_3.5|qimi_5|qimi_5.5 (qimi_3.5: giọng qimi_3, giá cố định mỗi lần — xem giá ở qm voices list --model qimi_3.5, tối đa 30.000 ký tự)', 'qimi_3')
   .requiredOption('--voice <v>', 'Tên giọng — xem cột VOICE của qm voices list')
   .option('--language <l>', 'Ngôn ngữ — phân biệt giọng trùng tên (xem qm voices list)')
-  .option('--speed <n>', 'Tốc độ đọc 0.5-2.0 (mặc định 1) — CHỈ qimi_5/qimi_5.5')
-  .option('--style <s>', 'Phong cách đọc — nhãn từ cột STYLES của qm voices list')
+  .option('--speed <n>', 'Tốc độ đọc 0.5-2.0 (mặc định 1) — CHỈ qimi_5/qimi_5.5 (qimi_3.5: chỉnh tốc độ bằng --style)')
+  .option('--style <s>', 'Kiểu đọc. qimi_1.5/2.5/3: nhãn cột STYLES của qm voices list. qimi_3.5: tối đa 1 tốc độ (fast|default|slow) + 1 cảm xúc (cheerful|sad|storytelling|emotional) nối bằng "+", vd "slow+storytelling"; hoặc tự mô tả tiếng Việt "custom:<mô tả ≤200 ký tự>" — danh sách mới nhất: qm voices list --model qimi_3.5')
   .option('--title <t>', 'Tiêu đề job')
   .option('--crid <id>', 'client_request_id')
   .option('--wait', 'Chờ tới khi job hoàn tất')
-  .option('--out <dir>', 'Thư mục lưu file mp3 (dùng kèm --wait)')
+  .option('--out <dir>', 'Thư mục lưu file audio mp3/wav (dùng kèm --wait)')
   .action(voice.tts);
 
 const voices_cmd = program.command('voices').description('Giọng đọc: catalog + giọng clone của bạn');
 voices_cmd
   .command('list')
-  .description('Liệt kê giọng theo model')
-  .requiredOption('--model <m>', 'qimi_1.5|qimi_2.5|qimi_3|qimi_5|qimi_5.5')
+  .description('Liệt kê giọng theo model (+ giá, và gợi ý kiểu đọc với qimi_3.5)')
+  .requiredOption('--model <m>', 'qimi_1.5|qimi_2.5|qimi_3|qimi_3.5|qimi_5|qimi_5.5')
   .option('--language <l>', 'Lọc theo ngôn ngữ')
   .option('--search <s>', 'Lọc theo tên (không phân biệt hoa/thường)')
   .option('--limit <n>', 'Số lượng tối đa (mặc định 50, trần 100)')
@@ -188,6 +221,41 @@ voices_cmd
   .description('Xoá giọng đã clone')
   .action(voice.voicesDelete);
 
+// ── Xưởng Nhạc Melo ──────────────────────────────────────────────────────────
+const music_cmd = program.command('music').description('Xưởng Nhạc Melo — tạo nhạc AI (mô tả/lời → mp3)');
+music_cmd
+  .command('create')
+  .description('Tạo bài hát AI (mode simple: AI viết lời từ mô tả; mode custom: tự nhập lời)')
+  .option('--mode <m>', 'simple (mặc định, AI viết lời) | custom (tự nhập lời)', 'simple')
+  .option('--desc <d>', 'Mô tả bài hát — bắt buộc mode simple, hoặc bản không lời')
+  .option('--lyrics <l>', 'Lời bài hát (mode custom)')
+  .option('--lyrics-file <path>', 'Đọc lời từ file local UTF-8 (thay --lyrics)')
+  .option('--styles <s>', 'Phong cách nhạc, phân cách dấu phẩy (vd "V-pop, Ballad")')
+  .option('--title <t>', 'Tiêu đề bài hát')
+  .option('--model <m>', 'melo-3 (mặc định, mới nhất) | melo-2 (thế hệ trước)', 'melo-3')
+  .option('--instrumental', 'Bản không lời')
+  .option('--gender <g>', 'auto (mặc định) | male | female — chỉ áp dụng khi có lời')
+  .option('--crid <id>', 'client_request_id')
+  .option('--wait', 'Chờ tới khi job hoàn tất')
+  .option('--out <dir>', 'Thư mục lưu file mp3 (tự bật --wait nếu chưa có)')
+  .action(music.create);
+music_cmd
+  .command('lyrics')
+  .description('AI viết lời bài hát (0đ) — xem trước/chỉnh trước khi dùng mode custom')
+  .requiredOption('--desc <d>', 'Mô tả bài hát')
+  .option('--title <t>', 'Tiêu đề gợi ý')
+  .option('--language <l>', 'Ngôn ngữ (mặc định auto)')
+  .option('--instrumental', 'Chỉ cần tiêu đề + phong cách, không cần lời')
+  .action(music.lyrics);
+music_cmd
+  .command('models')
+  .description('Liệt kê model nhạc + giá + ETA + hàng chờ')
+  .action(music.models);
+music_cmd
+  .command('get <id>')
+  .description('Xem chi tiết job nhạc (mus_<n> hoặc số trần)')
+  .action(music.get);
+
 // ── Cutout Studio ────────────────────────────────────────────────────────────
 program.command('cutout').description('Tách nền / tạo ảnh cutout trong suốt (PNG)')
   .option('--operation <o>', 'generate|from_ref|remix_describe', 'from_ref')
@@ -220,6 +288,20 @@ hook_cmd
   .option('--crid <id>', 'client_request_id')
   .action(tools.hookVideo);
 
+// ── apps (Ứng dụng React SSR trên <slug>.quickmagic.app — Apps đợt B) ─────────
+const apps_cmd = program.command('apps').description('Ứng dụng web đầy đủ (React SSR, subdomain riêng, Sign in with Quick Magic)');
+apps_cmd.command('create').description('Tạo app mới (repo từ template) — cần duyệt nếu gọi từ agent')
+  .requiredOption('--title <t>', 'Tên app').option('--subdomain <s>', 'Subdomain mong muốn (tự thêm hậu tố 4 ký tự)')
+  .option('--category <c>', 'Danh mục').option('--description <d>', 'Mô tả 1 câu')
+  .option('--from <app_id>', 'Remix: chép mã nguồn app công khai đã duyệt (không chép secrets/DB/cover)')
+  .action(apps.create);
+apps_cmd.command('list').description('Liệt kê app của tôi').action(apps.list);
+apps_cmd.command('status <app_id>').description('Trạng thái deploy/duyệt/build gần nhất').option('--json', 'In JSON').action(apps.status);
+apps_cmd.command('repo-access <app_id>').description('Lấy URL git clone có token 15 phút (in ra stdout)').action(apps.repoAccess);
+apps_cmd.command('deploy <app_id>').description('Build + deploy nhánh main').option('--wait', 'Chờ tới khi xong (≤5 phút)').action(apps.deploy);
+apps_cmd.command('publish <app_id>').description('Đưa lên feed Ứng dụng (cần deployed + cover; tự kiểm duyệt nội dung)').option('--unlist', 'Gỡ khỏi feed').action(apps.publish);
+apps_cmd.command('remove <app_id>').description('Xoá vĩnh viễn app').option('--yes', 'Xác nhận').action(apps.remove);
+
 program.parseAsync(process.argv).catch((e) => {
   console.error('Lỗi:', e.message);
   process.exit(1);