quickmagic-cli 1.2.0 → 1.4.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 9 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,10 @@ 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 | — |
 
 ### Nhập liệu (miễn phí)
 
@@ -223,6 +227,11 @@ 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
+
 # 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 +267,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 9 **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 +278,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
 ```
 
 Cách 2 — copy thủ công vào thư mục skills của Claude Code:
@@ -283,8 +292,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`... 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.2.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.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.",
   "bin": {
     "quickmagic": "src/index.js",
     "qm": "src/index.js"

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
+9 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
 ```
 
 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 8 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,28 @@ 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 |
 
-## Shared conventions (all 8 skills)
+## Shared conventions (all 9 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); 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

@@ -101,10 +101,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-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/elements.js

@@ -0,0 +1,42 @@
+// commands/elements.js — thư viện element tái dùng: xem `@tag` để trỏ trong prompt video, và tạo mới.
+// BE dịch `@tag` trong prompt thành "Image N (mô tả)" lúc gửi provider → giữ nhân vật/sản phẩm
+// nhất quán qua nhiều cảnh. Nhớ đưa ảnh element vào `--image` kèm `--mode reference`.
+const api = require('../api');
+const { resolveMediaInput } = require('../media');
+
+async function list(options) {
+  const limit = (options && options.limit) || 50;
+  const data = await api.call('GET', `/elements?limit=${encodeURIComponent(limit)}`);
+  const items = (data && data.elements) || [];
+  if (!items.length) {
+    console.log('Chưa có element nào. Tạo bằng: qm elements create --name "Áo dài đỏ" --image ./ao.jpg --desc "..."');
+    return;
+  }
+
+  const tag_w = Math.max(3, ...items.map((e) => `@${e.tag}`.length));
+  const name_w = Math.max(4, ...items.map((e) => (e.name || '').length));
+  console.log(`${'TAG'.padEnd(tag_w)}  ${'TÊN'.padEnd(name_w)}  MÔ TẢ`);
+  console.log('─'.repeat(tag_w + name_w + 30));
+  for (const e of items) {
+    const desc = (e.description || '').replace(/\s+/g, ' ');
+    const short = desc.length > 60 ? `${desc.slice(0, 57)}...` : desc;
+    console.log(`${`@${e.tag}`.padEnd(tag_w)}  ${(e.name || '').padEnd(name_w)}  ${short}`);
+  }
+  console.log(`\nDùng: qm generate video --prompt "cô gái mặc @${items[0].tag} đi dạo" --image <url-element> --mode reference --model seedance-2-0`);
+}
+
+async function create(options) {
+  // File local → tự upload presigned lên host Quick Magic (server chỉ nhận URL của mình).
+  const media_url = await resolveMediaInput(options.image);
+  const body = { name: options.name, media_url };
+  if (options.desc) body.description = options.desc;
+  if (options.category) body.category = options.category;
+  if (options.type) body.media_type = options.type;
+
+  const data = await api.call('POST', '/elements', { body });
+  console.log(`Đã tạo element: @${data.tag} (${data.name})`);
+  if (data.description) console.log(`Mô tả gửi kèm model: ${data.description}`);
+  console.log(`Dùng trong prompt: "@${data.tag}"`);
+}
+
+module.exports = { list, create };

package/src/commands/generate.js

@@ -32,8 +32,15 @@ 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).
+  if (Number.isInteger(options.seed)) body.seed = options.seed;
+  if (options.negative) body.negative_prompt = options.negative;
+  if (options.cameraFixed) body.camera_fixed = true;
+  if (options.audio === false) body.audio = false;
 
   const data = await api.call('POST', '/videos', { body });
   const job_id = data.job_id;

package/src/commands/models.js

@@ -39,7 +39,10 @@ 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.');
   }
 }
 

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

@@ -4,10 +4,12 @@ const { program } = require('commander');
 
 const auth = require('./commands/auth');
 const generate = require('./commands/generate');
+const elements = require('./commands/elements');
 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 collect = (v, acc) => { acc.push(v); return acc; };
 
@@ -51,10 +53,32 @@ gen_cmd
   .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('--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')
+  .option('--camera-fixed', 'Khoá máy quay đứng yên (không pan/zoom) — hợp cảnh xoay sản phẩm')
+  .option('--no-audio', 'Tắt tiếng (không đổi giá)')
   .option('--wait', 'Chờ tới khi job hoàn tất')
   .option('--out <dir>', 'Thư mục lưu kết quả (dùng kèm --wait)')
   .action(generate.video);
 
+// ── elements ─────────────────────────────────────────────────────────────────
+// [260726] Thư viện element tái dùng: `@tag` trong prompt → BE dịch thành "Image N (mô tả)".
+const elements_cmd = program.command('elements').description('Thư viện element tái dùng (@tag trong prompt)');
+elements_cmd
+  .command('list')
+  .description('Liệt kê element + tag để trỏ trong prompt')
+  .option('--limit <n>', 'Số lượng tối đa (mặc định 50)')
+  .action(elements.list);
+elements_cmd
+  .command('create')
+  .description('Lưu 1 ảnh thành element tái dùng')
+  .requiredOption('--name <n>', 'Tên element, vd "Áo dài đỏ" (tag tự sinh từ tên)')
+  .requiredOption('--image <i>', 'Ảnh (URL hoặc file local — tự upload)')
+  .option('--desc <d>', 'Mô tả chi tiết — CHÍNH là thứ được chèn kèm ảnh vào prompt, viết càng rõ càng giữ được nhân vật')
+  .option('--category <c>', 'character | location | prop | product | style | other')
+  .option('--type <t>', 'image (mặc định) | video')
+  .action(elements.create);
+
 // ── jobs ─────────────────────────────────────────────────────────────────────
 const jobs_cmd = program.command('jobs').description('Theo dõi job');
 jobs_cmd.command('get <id>').description('Xem chi tiết job (JSON)').action(jobs.get);
@@ -125,6 +149,45 @@ 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);
+
 // ── 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')