quickmagic-cli 1.4.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 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
@@ -151,6 +151,10 @@ Ghi chú chung trước khi xem bảng:
 | `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í)
 
@@ -182,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
 
@@ -232,6 +267,11 @@ 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
@@ -267,7 +307,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 +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,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 +333,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.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
 
-9 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,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
 ```
 
 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 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 |
@@ -44,8 +44,9 @@ mkdir -p ~/.claude/skills && cp -r cli-quickmagic/skills/quickmagic-* ~/.claude/
 | `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 9 skills)
+## Shared conventions (all 10 skills)
 
 - Check `qm auth status` first; if not logged in, tell the user to run
   `qm auth login`.
@@ -60,7 +61,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/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

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

@@ -10,6 +10,7 @@ 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; };
 
@@ -51,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')
@@ -93,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 ──────────────────────────────────────────────────────────────────
@@ -188,6 +189,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')