quickmagic-cli 1.3.0 → 1.5.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 8 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
@@ -147,6 +147,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 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í)
 
@@ -178,8 +186,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
 
@@ -223,6 +262,16 @@ qm split https://www.tiktok.com/@user/video/123 --mode auto
 qm stt https://cdn.example.com/audio.mp3 --translate vi
 qm motion https://cdn.example.com/dance.mp4 --image ./photo.jpg
 
+# Đọc văn bản thành giọng nói — xem giá + chọn giọng trước khi chạy
+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
+
+# 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
@@ -258,7 +307,7 @@ qm credits          # chạy không cần browser
 
 ## Agent Skills
 
-CLI này đi kèm 8 **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`.
@@ -269,7 +318,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
+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:
@@ -283,8 +332,9 @@ 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`... 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.
+`wait_for_job`, `list_models`, `get_credit_balance`, `list_voices`, `text_to_speech`,
+`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.3.0",
-  "description": "Quick Magic CLI — generate AI images/videos, product photoshoots, virtual try-on, hook ad videos, subtitles and more via the Quick Magic REST API, with browser-based OAuth PKCE login (no API keys to manage). Ships with 8 Claude Agent Skills and an MCP server integration.",
+  "version": "1.5.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 and more via the Quick Magic REST API, with browser-based OAuth PKCE login (no API keys to manage). Ships with 10 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
 
-8 Agent Skills that wrap the `quickmagic` / `qm` CLI so a coding agent (Claude
+10 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
+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
 ```
 
 Option 2 — copy directly into a project's or your user's Claude skills folder:
@@ -35,7 +35,7 @@ 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 7 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 |
@@ -43,23 +43,29 @@ mkdir -p ~/.claude/skills && cp -r cli-quickmagic/skills/quickmagic-* ~/.claude/
 | `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-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-music` | `music create/lyrics/models/get` | AI song generation (vocals or instrumental) from a description or your own lyrics |
 
-## Shared conventions (all 8 skills)
+## Shared conventions (all 10 skills)
 
 - Check `qm auth status` first; if not logged in, tell the user to run
   `qm auth login`.
-- Quote the credit cost (from `qm models list` / a preset's `credit_cost`) and
-  get explicit user confirmation **before** running any command that spends
-  credit — submission holds credit immediately. `subtitle`/`split` are the one
-  exception: price is duration-based and only known after submission, so the
-  skill asks for a go-ahead instead of a number.
+- Quote the credit cost (from `qm models list` / a preset's `credit_cost` —
+  `tts`/`voices clone` instead read `pricing`/`clone_price` from
+  `qm voices list --model <m>`) and get explicit user confirmation **before**
+  running any command that spends credit — submission holds credit
+  immediately. `subtitle`/`split` are the one exception: price is
+  duration-based and only known after submission, so the skill asks for a
+  go-ahead instead of a number.
 - Surface `insufficient_credit` (`Không đủ credit: ... thiếu Zcr`) with the exact
   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); product/fashion/cutout/split return
-  arrays and must be read back with `qm jobs get <id>` after completion.
-  See `quickmagic-account` for the full job-id-prefix table.
+  (image/video/tryon/edit/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
+  full job-id-prefix table.
 - Always end with the final result URL(s) plus the credit amount already
   charged/held.
 

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
@@ -101,10 +106,13 @@ generating command's own `--wait` flag, where available).
 | `mkt_` | `marketing video` | single result (no dedicated skill) |
 | `mot_` | `motion` | single result (no dedicated skill) |
 | `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` |
 
 **Important caveat**: `jobs wait --out <dir>` only **auto-downloads** for the
-single-`result_url` types (`img_`/`vid_`/`vto_`/`edt_`/`hok_`/`sub_`). For the
-array types (`pai_`/`fsh_`/`cut_`/`spl_`), `--out` still polls status correctly
+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.
 

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

@@ -0,0 +1,167 @@
+---
+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".
+---
+
+# quickmagic-tts — Text-to-Speech & Voice Cloning
+
+Wraps `qm tts` and `qm voices list/clone/delete`. Use whenever the user wants
+text read aloud as audio, or wants a custom cloned voice for future TTS calls.
+
+## Commands
+
+| 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 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`) | — |
+
+## Models — always read the price at runtime
+
+| Model | Billing | Char limit | Voices |
+|---|---|---|---|
+| `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_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
+`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.
+
+## Pick a voice
+
+```bash
+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 voices list --model qimi_5 --search Minh --limit 20
+```
+
+- Use the **`VOICE`** column value as `--voice` on `qm tts` — not `NAME`.
+- Pass `--language` whenever a voice name repeats across languages (e.g. an
+  `Aarav` voice exists in both English and Hindi) so the server picks the
+  right one.
+- `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_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
+  most naturally in its own source language (it can still read all ~40
+  supported languages) — for Vietnamese text, prefer a `Tiếng Việt`-tagged
+  voice or a voice you cloned yourself.
+
+## Reading text aloud
+
+```bash
+qm tts --text "Xin chào, đây là bản demo." --voice <voice_id> --model qimi_3 --wait --out ./out
+qm tts --file ./script.txt --voice <voice_id> --model qimi_5 --language "Tiếng Việt" --speed 1.1 --wait --out ./out
+```
+
+- `--file` reads local UTF-8 text — use it instead of `--text` for long
+  scripts.
+- 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`).
+
+## Cloning a custom voice (optional, for qimi_5/qimi_5.5)
+
+```bash
+qm voices clone --audio ./sample.wav --name "Giọng của tôi" --wait
+qm voices clone --audio https://files.quickmagic.cloud/... --name "Alt voice" --crid my-retry-key
+```
+
+- `--audio` accepts a **local audio file** (auto-uploaded to Quick Magic
+  first) or an **existing Quick Magic file URL** — an arbitrary external URL
+  is rejected (`invalid_source`).
+- Sample length **10 seconds – 5 minutes**, size **≤ 20MB**.
+- `--crid` is optional here: if omitted the CLI derives one from the file
+  bytes + name, so an accidental retry of the exact same file+name never
+  double-clones or double-charges.
+- Before running, read `clone_price` and `first_free_available` from
+  `qm voices list --model qimi_5` — the **first clone may be free**, but only
+  for an account with an **active paid plan** (never on the free tier).
+- Job id is `voc_<n>` and has **no `result_url`**: `qm jobs wait voc_<n>` only
+  polls status; once `completed`, run `qm jobs get voc_<n>` and read
+  `voice` / `sample_url` (or pass `--wait` to `qm voices clone`, which prints them). Use that same name as `--voice` on `qm tts` with
+  `--model qimi_5` (or `qimi_5.5`).
+- Uploaded sample files live in temporary Quick Magic storage (auto-deleted
+  after ~5 days) — that's fine, they're only needed once, during cloning.
+
+## Deleting a cloned voice
+
+```bash
+qm voices delete voc_12
+```
+
+No refund. Fails with `VOICE_BUSY` if the voice is still being processed, or
+if a `qm tts` job is currently reading with it — wait for that job to finish,
+then retry the delete.
+
+## Pricing — quote, then confirm
+
+1. `qm voices list --model <m> [...]` → read `pricing` (plus `clone_price` /
+   `first_free_available` for `qimi_5`/`qimi_5.5`).
+2. State the estimated cost to the user (character count × per-char rate, or
+   the flat per-call price) and get explicit confirmation.
+3. Only then run `qm tts` / `qm voices clone` — submission holds credit
+   immediately.
+
+**Retries (same rule for both `qm tts --crid` and `qm voices clone`):**
+retrying the *same* crid **after a failed** attempt (e.g.
+`insufficient_credit`) starts a **new** job — a failed attempt does not keep
+the crid reserved, so it's always safe to resubmit unchanged. Replaying the
+crid of a job that's still **in progress** instead returns
+`idempotent_replay: true` with the real `credits_held`/`status` — no new job,
+no double charge. `qm voices clone` auto-generates its own crid from the
+file bytes + name when `--crid` is omitted (see "Cloning a custom voice"
+above) — the same failed-vs-in-progress behavior applies to that
+auto-generated crid too.
+
+## Errors
+
+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` |
+| `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 |
+| `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 |
+| `feature_disabled` | TTS or cloning temporarily off | tell the user, don't retry |
+| `VOICE_BUSY` | voice is still cloning, or in use by an in-progress `qm tts` job | wait for that job to finish before deleting/reusing it |
+| `duplicate_name` | clone `--name` already used | pick a different name |
+| `invalid_source` | `--audio` isn't a local file or a Quick Magic URL | re-upload, or pass a valid Quick Magic file URL |
+| `pending_limit` | too many jobs already queued | wait for some to finish |
+
+Full auth/job/error-code reference: `quickmagic-account` skill.
+
+## Examples
+
+```bash
+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_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
+
+qm voices delete voc_12
+```

package/src/api.js

@@ -69,7 +69,9 @@ async function call(method, rest_path, { body } = {}) {
 
   const json = await res.json().catch(() => ({}));
   if (!res.ok || json.success === false) {
-    throw new Error(json.message || `HTTP ${res.status}`);
+    const err = new Error(json.message || `HTTP ${res.status}`);
+    err.code = json.code; // [plans/260817-2339 P4] giữ code REST để lệnh gọi phía trên in "Lỗi [code]: message"
+    throw err;
   }
   return json.data;
 }

package/src/commands/generate.js

@@ -32,7 +32,8 @@ async function video(options) {
   // --mode reference|frames (R2V 260706): server validate theo model; bỏ trống = default model.
   if (options.mode) body.image_mode = options.mode;
   // --video-ref (v2v 260723): file local tự upload presigned → URL host QM; server probe duration
-  // + validate (chỉ seedance-2-0/-fast, max 15s, không mix ảnh, giá hạng with-video).
+  // + validate theo cờ supports_video_ref per-model trong registry (260808: seedance-2-0/-fast/-2-5;
+  // danh sách ĐỘNG phía server — CLI không giữ list cứng), không mix ảnh, giá hạng with-video.
   if (options.videoRef) body.video_ref_url = await resolveMediaInput(options.videoRef);
   // [260726] 4 tham số nâng cao — server đã nhận sẵn, CLI chỉ chưa mở.
   // --no-audio: commander set options.audio = false; mặc định undefined (giữ default của model).

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.
@@ -39,7 +41,15 @@ async function list(options) {
     console.log(`${r.key.padEnd(key_w)}  ${r.label.padEnd(label_w)}  ${r.credit.padEnd(credit_w)}${is_video ? `  ${r.images}` : ''}`);
   }
   if (is_video && rows.some((r) => r.images.includes('*'))) {
-    console.log('\n* KHÔNG nhận ảnh chứa người thật (gửi vào sẽ lỗi) — dùng gemini-omni / seedance 1.x / wan-2-7 cho ảnh người.');
+    console.log('\n* KHÔNG nhận ảnh người upload/từ ngoài (gửi vào sẽ lỗi, không mất credit).');
+    console.log('  Muốn có nhân vật với model *: tạo ảnh bằng "qm generate image -m seedream-5.0-pro" ngay trong Quick Magic');
+    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.');
   }
 }
 

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/voice.js

@@ -0,0 +1,141 @@
+// commands/voice.js — qm tts + qm voices list/clone/delete (4 endpoint REST P2: GET /voices,
+// POST /tts, POST /voice-clones, DELETE /voice-clones/:voice_id). Tách khỏi tools.js vì 4 lệnh
+// này cần đọc file text, đếm ký tự, in bảng, gộp --wait — nhét vào phá quy ước 1-dòng/lệnh.
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { call } = require('../api');
+const { resolveMediaInput } = require('../media');
+const jobs = require('./jobs');
+
+const out = (data) => console.log(JSON.stringify(data, null, 2));
+// [red-team #15] api.js đã gắn err.code từ REST {code,message} → in kèm code để agent rẽ nhánh
+// (retryable 5xx/429 vs không 4xx như SKILL dặn); lỗi cục bộ (vd thiếu --text) không có code.
+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);
+});
+
+// Query string cho GET /voices — bỏ param rỗng/undefined (chỉ model bắt buộc).
+function buildQuery(params) {
+  const parts = Object.entries(params)
+    .filter(([, v]) => v !== undefined && v !== null && v !== '')
+    .map(([k, v]) => `${k}=${encodeURIComponent(v)}`);
+  return parts.length ? `?${parts.join('&')}` : '';
+}
+
+// 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.
+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 printPricing(p) {
+  if (p.billing === 'flat') console.log(`Giá: ${p.credits} credit/lần`);
+  else console.log(`Giá: ${p.credits_per_char} credit/ký tự, tối thiểu ${p.min_charge}`);
+  console.log(`Trần ký tự: ${p.char_limit}`);
+}
+
+// ── tts ──
+const tts = run(async (o) => {
+  if (!o.text && !o.file) throw new Error('Cần --text hoặc --file');
+  const text = o.text || fs.readFileSync(path.resolve(o.file), 'utf8');
+  console.log(`Số ký tự: ${text.length}`);
+  const data = await call('POST', '/tts', {
+    body: {
+      model: o.model, voice: o.voice, language: o.language, text,
+      speed: o.speed ? Number(o.speed) : undefined, style: o.style, title: o.title,
+      client_request_id: o.crid,
+    },
+  });
+  out(data);
+  console.log(`\n→ Theo dõi: qm jobs get ${data.job_id}`);
+  if (o.wait) {
+    // waitAll KHÔNG trả data (chỉ poll + tự tải khi có result_url đơn) — gọi lại /jobs để in result_url.
+    await jobs.waitAll([data.job_id], o.out);
+    const final = await call('GET', `/jobs/${data.job_id}`);
+    console.log(`result_url: ${final.result_url || '(chưa có)'}`);
+  }
+});
+
+// ── voices list ──
+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);
+  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).
+    if (data.first_free_available != null) {
+      const free_msg = data.first_free_available ? 'còn (giọng #1 = 0 credit)'
+        : data.first_free_upsell ? 'chỉ dành cho tài khoản có gói trả phí đang hoạt động (https://quickmagic.vn/pricing)'
+          : 'đã dùng';
+      console.log(`Suất clone miễn phí lần đầu: ${free_msg}`);
+    }
+    if (data.hint) console.log(data.hint);
+  }
+  console.log('');
+  if (pricing.billing === 'flat') {
+    printTable(
+      ['VOICE', 'NAME', 'GENDER', 'LANGUAGE', 'STYLES'],
+      data.voices.map((v) => [v.voice, v.name, v.gender, v.language, (v.styles || []).join(', ').slice(0, 40)]),
+    );
+  } else {
+    const clones = data.voices.filter((v) => v.kind === 'clone');
+    const systems = data.voices.filter((v) => v.kind === 'system');
+    if (clones.length) {
+      console.log('Giọng của bạn:');
+      printTable(['VOICE', 'STATUS', 'SAMPLE'], clones.map((v) => [v.voice, v.status, v.sample_url]));
+      console.log('');
+    }
+    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]));
+    }
+  }
+  console.log(`\nNgôn ngữ: ${(data.languages || []).join(' · ')}`);
+  console.log(`Tổng: ${data.total} — Hiển thị: ${data.returned}`);
+});
+
+// [red-team #14] auto-crid = hash(bytes file cục bộ | chuỗi URL) + hash(name) — retry vô tình
+// (mất mạng, gõ lại lệnh) không tạo 2 voice/2 hold 2.230cr khi user không tự truyền --crid.
+function autoCrid(audio_ref, name) {
+  const is_url = /^https?:\/\//i.test(audio_ref);
+  let source = audio_ref;
+  if (!is_url) {
+    const abs_path = path.resolve(audio_ref);
+    if (!fs.existsSync(abs_path)) throw new Error(`Không thấy file: ${audio_ref}`);
+    source = fs.readFileSync(abs_path);
+  }
+  const h1 = crypto.createHash('sha256').update(source).digest('hex').slice(0, 32);
+  const h2 = crypto.createHash('sha256').update(name).digest('hex').slice(0, 8);
+  return `cli-${h1}-${h2}`;
+}
+
+// ── voices clone ──
+const voicesClone = run(async (o) => {
+  const crid = o.crid || autoCrid(o.audio, o.name);
+  const audio_url = await resolveMediaInput(o.audio);
+  const data = await call('POST', '/voice-clones', { body: { audio_url, name: o.name, client_request_id: crid } });
+  out(data);
+  console.log(`\nclient_request_id: ${crid}`);
+  console.log(`→ Dùng --voice "${o.name}" ở qm tts (model qimi_5/qimi_5.5) sau khi status completed`);
+  if (o.wait) {
+    // Job clone (voc_) không có result_url ⇒ --wait chỉ poll trạng thái; in voice/sample_url sau khi xong.
+    await jobs.waitAll([data.voice_id]);
+    const final = await call('GET', `/jobs/${data.voice_id}`);
+    console.log(`voice: ${final.voice || ''}`);
+    console.log(`sample_url: ${final.sample_url || '(chưa có)'}`);
+    console.log(`status: ${final.status}`);
+  }
+});
+
+// ── voices delete ──
+const voicesDelete = run(async (id) => {
+  out(await call('DELETE', `/voice-clones/${encodeURIComponent(String(id).replace(/^voc_/, ''))}`));
+});
+
+module.exports = { tts, voicesList, voicesClone, voicesDelete };

package/src/index.js

@@ -9,6 +9,8 @@ const jobs = require('./commands/jobs');
 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 collect = (v, acc) => { acc.push(v); return acc; };
 
@@ -50,7 +52,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')
@@ -92,7 +94,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 ──────────────────────────────────────────────────────────────────
@@ -148,6 +150,80 @@ 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);
 
+// ── 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)')
+  .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')
+  .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('--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)')
+  .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')
+  .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)')
+  .action(voice.voicesList);
+voices_cmd
+  .command('clone')
+  .description('Nhân bản giọng nói từ file ghi âm mẫu (dùng cho qimi_5/qimi_5.5)')
+  .requiredOption('--audio <file|url>', 'File local mp3/wav/m4a 10s-5 phút ≤20MB (tự upload) hoặc URL do Quick Magic cấp (files.quickmagic.cloud)')
+  .requiredOption('--name <n>', 'Tên giọng — dùng lại ở --voice của qm tts')
+  .option('--crid <id>', 'client_request_id (mặc định tự sinh từ hash file+tên)')
+  .option('--wait', 'Chờ tới khi giọng xử lý xong')
+  .action(voice.voicesClone);
+voices_cmd
+  .command('delete <id>')
+  .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')