quickmagic-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quick Magic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,337 @@
+# quickmagic-cli
+
+[![npm version](https://img.shields.io/npm/v/quickmagic-cli.svg)](https://www.npmjs.com/package/quickmagic-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Node.js >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+
+**English** — Command-line client for [Quick Magic](https://quickmagic.vn): generate AI
+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
+coding agents. Everything below this line is in Vietnamese (tiếng Việt) — quickstart only:
+
+```bash
+npm install -g quickmagic-cli    # once published to npm — see "Cài đặt" below for today
+qm auth login                    # opens your browser to sign in
+qm generate image --prompt "a red apple on a table" --model qimi_3 --wait --out ./out
+```
+
+Full command reference, MCP setup, Agent Skills, troubleshooting: keep reading, or run
+`qm <command> --help`.
+
+---
+
+## Giới thiệu
+
+CLI tạo ảnh/video AI qua REST API Quick Magic, đăng nhập bằng **OAuth PKCE** (mở trình
+duyệt, không cần dán API key).
+
+- Node **>= 18** (dùng `fetch`/`crypto`/`http` built-in — không cần axios).
+- Bin: `quickmagic` và alias `qm`.
+- REST base: `https://api.quickmagic.vn/public/v1`. Discovery OAuth ở root
+  `https://api.quickmagic.vn/.well-known/oauth-authorization-server`.
+
+## Cài đặt
+
+**Cách 1 — npm (sau khi publish):**
+
+```bash
+npm install -g quickmagic-cli
+```
+
+**Cách 2 — cài từ source (dùng ngay bây giờ):**
+
+```bash
+git clone https://github.com/Tungbillee/cli-quickmagic.git
+cd cli-quickmagic
+npm install
+npm install -g .
+```
+
+**Cách 3 — dev local (symlink, sửa code chạy luôn):**
+
+```bash
+cd cli-quickmagic
+npm install
+npm link                # tạo lệnh global `quickmagic` / `qm` trỏ về source
+```
+
+Gỡ cài đặt: `npm rm -g quickmagic-cli` (Cách 1/2) hoặc `npm unlink -g quickmagic-cli` (Cách 3).
+
+## Bắt đầu nhanh (3 lệnh)
+
+```bash
+npm install -g quickmagic-cli
+qm auth login
+qm generate image --prompt "a red apple on a table" --model qimi_3 --wait --out ./out
+```
+
+`qm auth login` mở trình duyệt đăng nhập 1 lần; các lệnh sau tự dùng token đã lưu (tự
+refresh khi sắp hết hạn hoặc gặp HTTP 401 — không cần đăng nhập lại).
+
+## Xác thực
+
+```bash
+qm auth login                              # mở trình duyệt, đăng nhập, lưu token
+qm auth login --api-url https://api.quickmagic.vn   # chỉ định URL gốc khác
+qm auth status                             # in email / số dư
+qm auth logout                             # xoá credentials
+```
+
+Credentials lưu tại `~/.quickmagic/credentials.json` (quyền `600`, thư mục `700`).
+Access token tự refresh khi sắp hết hạn hoặc khi gặp HTTP 401 — không cần đăng nhập lại.
+
+## Bảng lệnh đầy đủ
+
+Ghi chú chung trước khi xem bảng:
+
+- Tham số nhận ảnh/video (`--ref`, `--image`, `--garment`, `--character`, `--product`...)
+  nhận **URL** (giữ nguyên) hoặc **file local** (tự đọc → `data:image/*;base64,...`). File
+  local lớn (> ~8MB) sẽ bị cảnh báo — nên dùng URL vì body giới hạn ~10MB.
+- `--crid <id>` (`client_request_id`) dùng cho **idempotency** — truyền cùng giá trị khi
+  retry để không bị tạo job / trừ tiền 2 lần.
+- Cột **Credit** đánh dấu lệnh có giữ/trừ credit hay không; xem giá chính xác bằng
+  `qm models list`, `qm hook presets`, `qm marketing modes` trước khi chạy thật.
+- Xem đầy đủ cờ (flags) của từng lệnh: `qm <lệnh> --help` (vd `qm hook video --help`).
+
+### Xác thực & tài khoản
+
+| Lệnh | Mô tả | Credit |
+|---|---|---|
+| `qm auth login` | Đăng nhập qua trình duyệt (OAuth PKCE) | — |
+| `qm auth logout` | Đăng xuất, xoá credentials | — |
+| `qm auth status` | Xem email / số dư | — |
+| `qm credits` | Số dư / tạm giữ / gói / Qimi free-window | — |
+| `qm models list --type image\|video` | Bảng model + giá credit | — |
+
+### Tạo ảnh / video + theo dõi job
+
+| Lệnh | Mô tả | Credit |
+|---|---|---|
+| `qm generate image` | Tạo ảnh AI (text-to-image, tối đa nhiều ảnh tham chiếu) | Có |
+| `qm generate video` | Tạo video AI (text-to-video / ảnh đầu vào) | Có |
+| `qm jobs get <id>` | Xem chi tiết 1 job (JSON) | — |
+| `qm jobs wait <id> [--out dir]` | Chờ job hoàn tất + tải kết quả | — |
+
+### Sản phẩm / Thời trang
+
+| Lệnh | Mô tả | Credit |
+|---|---|---|
+| `qm product --refs <r...>` | Ảnh sản phẩm AI (packshot/poster/infographic/composite) | Có |
+| `qm fashion --outfit <id...>` | Ảnh thời trang từ outfit đã lưu + KOL | Có |
+| `qm tryon --model-image <img>` | Thử đồ ảo (virtual try-on) trên ảnh người cụ thể | Có |
+
+### Ảnh nâng cao
+
+| Lệnh | Mô tả | Credit |
+|---|---|---|
+| `qm cutout` | Tách nền / PNG trong suốt / remix scene | Có |
+| `qm edit <image> --tool <t>` | restore / upscale (2k,4k) / beauty / muscle / color_boost | Có |
+
+### Video quảng cáo / Marketing
+
+| Lệnh | Mô tả | Credit |
+|---|---|---|
+| `qm hook presets` | Liệt kê preset Hook Studio + giá | — |
+| `qm hook video --preset <id>` | Video hài quảng cáo từ ảnh nhân vật + sản phẩm | Có |
+| `qm marketing modes` | Liệt kê mode + bảng giá theo duration | — |
+| `qm marketing video --mode <id>` | Video marketing (giá theo duration) | Có |
+| `qm analyze <video_url>` | Phân tích video quảng cáo đối thủ → kịch bản | Có (15cr) |
+
+### Audio / Video dài
+
+| Lệnh | Mô tả | Credit |
+|---|---|---|
+| `qm stt <audio_url>` | Chuyển giọng nói → văn bản (+ dịch) | Có |
+| `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ó |
+
+### Nhập liệu (miễn phí)
+
+| Lệnh | Mô tả | Credit |
+|---|---|---|
+| `qm scrape <url>` | Quét ảnh + tên sản phẩm từ link trang | — |
+| `qm import <url>` | Nhập ảnh/video từ link TikTok/Instagram | — |
+| `qm assets <kind>` | Liệt kê tài sản đã lưu: `products`\|`outfits`\|`kols` | — |
+
+## Tạo ảnh
+
+```bash
+qm generate image --prompt "a red apple on a table" --model qimi_3
+qm generate image --prompt "a cat" --model qimi_3 --n 4 --quality high --aspect-ratio 1:1
+qm generate image --prompt "same style" --ref https://x.com/a.png --ref ./local.jpg
+qm generate image --prompt "a dog" --model qimi_3 --wait --out ./out   # chờ + tải file
+```
+
+- `--ref` nhận **URL** (giữ nguyên) hoặc **file local** (đọc thành `data:image/*;base64,...`). Lặp nhiều lần để gửi nhiều ảnh.
+- Ảnh local lớn (> ~8MB) sẽ bị cảnh báo — nên dùng URL vì body giới hạn ~10MB.
+
+## Tạo video
+
+```bash
+qm generate video --prompt "a waving flag" --model grok-imagine
+qm generate video --prompt "zoom in" --model <m> --duration 8 --resolution 720p --image ./first.jpg
+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 `*`).
+
+## Job
+
+```bash
+qm jobs get img_12               # in JSON chi tiết job
+qm jobs wait vid_7 --out ./out   # poll mỗi 2.5s tới khi xong, tải kết quả về ./out
+```
+
+## Model & Credit
+
+```bash
+qm models list --type image      # bảng key | label | credit
+qm models list --type video
+qm credits                       # số dư / tạm giữ / gói
+```
+
+## Ví dụ nhanh — các tính năng khác
+
+```bash
+# Ảnh sản phẩm AI (product_id trong tủ đồ, hoặc URL/base64 — tối đa 3 ref)
+qm product --refs 42 --types product poster --count 2
+
+# Ảnh thời trang từ outfit đã lưu
+qm fashion --outfit 7 12 --mode kol_outfit --kol-id 3
+
+# Thử đồ ảo trên ảnh người cụ thể
+qm tryon --model-image ./me.jpg --garment ./ao.jpg --type full
+
+# Tách nền / tạo PNG trong suốt từ ảnh tham chiếu
+qm cutout --operation from_ref --ref ./product.jpg --model nano-banana-2
+
+# Video hài quảng cáo — xem preset + giá trước khi chạy
+qm hook presets
+qm hook video --preset <id> --character ./face.jpg --product ./product.jpg --speech-lang vi
+
+# Phụ đề tự động (+ dịch), cắt video dài thành clip ngắn
+qm subtitle https://cdn.example.com/video.mp4 --translate en
+qm split https://www.tiktok.com/@user/video/123 --mode auto
+
+# Giọng nói → văn bản, áp chuyển động video vào ảnh
+qm stt https://cdn.example.com/audio.mp3 --translate vi
+qm motion https://cdn.example.com/dance.mp4 --image ./photo.jpg
+
+# 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
+
+# Nhập liệu — không tốn credit
+qm scrape https://shop.example.com/product/123
+qm import https://www.tiktok.com/@user/video/123 --media image
+qm assets products --limit 20
+qm analyze https://cdn.example.com/ad.mp4 --product-id 42
+```
+
+## Biến môi trường
+
+| Biến | Ý nghĩa |
+|---|---|
+| `QUICKMAGIC_URL` | Ghi đè URL gốc API (mặc định `https://api.quickmagic.vn`). |
+| `QUICKMAGIC_TOKEN` | **CI headless** — access token. Có biến này thì bỏ qua bước mở trình duyệt. |
+| `QUICKMAGIC_REFRESH_TOKEN` | **CI headless** — refresh token (kèm access token). |
+
+Khi chạy bằng env token, CLI **chỉ đọc** token từ env, **không** ghi xuống `~/.quickmagic/credentials.json`.
+
+```bash
+# Ví dụ CI
+export QUICKMAGIC_TOKEN="<access_token>"
+export QUICKMAGIC_REFRESH_TOKEN="<refresh_token>"
+qm credits          # chạy không cần browser
+```
+
+## Mã thoát (exit code)
+
+- `0` — thành công.
+- `1` — lỗi (chưa đăng nhập, job thất bại, HTTP lỗi, ...). Thân thiện CI.
+
+## Agent Skills
+
+CLI này đi kèm 8 **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`.
+
+**Yêu cầu:** cài CLI trước (xem mục Cài đặt) + `qm auth login` một lần trên máy.
+
+Cách 1 — `npx skills` (nếu dùng công cụ [`skills`](https://www.npmjs.com/package/skills) để
+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
+```
+
+Cách 2 — copy thủ công vào thư mục skills của Claude Code:
+
+```bash
+cp -r skills/quickmagic-* .claude/skills/        # project (chỉ áp dụng cho project này)
+cp -r skills/quickmagic-* ~/.claude/skills/      # user (mọi project trên máy)
+```
+
+## MCP (Model Context Protocol)
+
+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.
+
+- MCP endpoint: `https://api.quickmagic.vn/mcp`
+
+**Claude Code:**
+
+```bash
+claude mcp add --transport http quickmagic https://api.quickmagic.vn/mcp
+```
+
+Lần đầu dùng sẽ mở trình duyệt → đăng nhập Quick Magic → **Cho phép**. Kiểm tra:
+`claude mcp list` hoặc gõ `/mcp` trong phiên Claude Code.
+
+**Cursor** — thêm vào `.cursor/mcp.json`:
+
+```json
+{ "mcpServers": { "quickmagic": { "url": "https://api.quickmagic.vn/mcp" } } }
+```
+
+**claude.ai (web connector):** Settings → Connectors → Add custom connector → dán URL
+`https://api.quickmagic.vn/mcp` → Connect → đăng nhập Quick Magic.
+
+CLI và MCP dùng chung tài khoản: đăng nhập 1 bên không tự đăng nhập bên kia (mỗi bên lưu
+token riêng), nhưng số dư credit/lịch sử job là chung.
+
+## Bảo mật
+
+- PKCE S256 (không lưu client secret trên máy). `state` chống CSRF ở callback.
+- Loopback chỉ nghe `127.0.0.1` (không `0.0.0.0`), `redirect_uri` gắn port cụ thể của phiên login.
+- `credentials.json` quyền `600`, ghi kiểu temp→rename (atomic, không hỏng JSON).
+- Refresh bọc lockfile `~/.quickmagic/refresh.lock` chống 2 tiến trình refresh đồng thời.
+- Không in access/refresh token ra stdout/log.
+
+## Khắc phục sự cố
+
+| Vấn đề | Xử lý |
+|---|---|
+| `Chưa đăng nhập. Chạy: quickmagic auth login` | Chạy `qm auth login`. |
+| Trình duyệt không tự mở khi login | Dán URL được in ra terminal vào trình duyệt bất kỳ. |
+| Đăng nhập quá 2 phút (timeout) | Chạy lại `qm auth login`. |
+| Lỗi HTTP 401 lặp lại dù đã đăng nhập | Token bị thu hồi/hết hạn refresh — `qm auth logout` rồi `qm auth login` lại. |
+| `Không đủ credit: ... thiếu Zcr` | Nạp thêm tại https://quickmagic.vn/pricing. |
+| Cảnh báo file > 8MB khi dùng `--ref`/`--image` | Body giới hạn ~10MB — ưu tiên dùng URL public thay vì file local. |
+| Muốn trỏ CLI vào domain/môi trường khác | Cờ `--api-url <url>` (khi login) hoặc biến môi trường `QUICKMAGIC_URL`. |
+| Máy CI/server không có trình duyệt | Đặt `QUICKMAGIC_TOKEN` (+ `QUICKMAGIC_REFRESH_TOKEN`) — xem mục Biến môi trường. |
+| Cài `-g` xong gõ `qm`/`quickmagic` báo "command not found" | Kiểm tra `npm config get prefix`, thêm `<prefix>/bin` vào `PATH`. |
+
+## Giấy phép
+
+[MIT](./LICENSE) © Quick Magic. Issue/góp ý:
+https://github.com/Tungbillee/cli-quickmagic/issues.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "quickmagic-cli",
+  "version": "1.0.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.",
+  "bin": {
+    "quickmagic": "src/index.js",
+    "qm": "src/index.js"
+  },
+  "main": "src/index.js",
+  "files": [
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "node --check src/index.js"
+  },
+  "keywords": [
+    "quickmagic",
+    "cli",
+    "ai",
+    "image-generation",
+    "video-generation",
+    "text-to-image",
+    "text-to-video",
+    "generative-ai",
+    "oauth",
+    "oauth-pkce",
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "agent-skills",
+    "product-photography",
+    "virtual-try-on"
+  ],
+  "homepage": "https://github.com/Tungbillee/cli-quickmagic#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Tungbillee/cli-quickmagic.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Tungbillee/cli-quickmagic/issues"
+  },
+  "author": "Quick Magic",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^12",
+    "open": "^8.4.2"
+  }
+}

package/skills/README.md

@@ -0,0 +1,67 @@
+# Quick Magic CLI — Agent Skills
+
+8 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.
+
+Each skill is a `skills/<name>/SKILL.md` (frontmatter `name` + `description` —
+the `description` doubles as the router/trigger contract an agent uses to decide
+when to load the skill).
+
+## Install
+
+**Requires the CLI itself first** — see `cli-quickmagic/README.md`
+(`npm install -g .` or `npm link` from the `cli-quickmagic/` folder), then
+`qm auth login` once per machine.
+
+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
+```
+
+Option 2 — copy directly into a project's or your user's Claude skills folder:
+
+```bash
+# project-level (this repo, active for anyone working in it)
+mkdir -p .claude/skills && cp -r cli-quickmagic/skills/quickmagic-* .claude/skills/
+
+# user-level (active in every project)
+mkdir -p ~/.claude/skills && cp -r cli-quickmagic/skills/quickmagic-* ~/.claude/skills/
+```
+
+## Skills
+
+| 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-generate` | `generate image`, `generate video` | text/reference-to-image or -video |
+| `quickmagic-product-photoshoot` | `product` | studio/marketing photos of a product (packshot/poster/infographic/composite) |
+| `quickmagic-fashion` | `fashion`, `tryon` | outfit lookbook shoots vs. virtual try-on on a specific person photo |
+| `quickmagic-cutout` | `cutout` | transparent PNG cutouts / scene remix |
+| `quickmagic-hook-video` | `hook presets`, `hook video` | ~10s comedy ad video from a character + product photo (18 presets) |
+| `quickmagic-edit-image` | `edit` | restore / upscale (2k/4k) / beauty / muscle / color_boost on an existing image |
+| `quickmagic-subtitle-split` | `subtitle`, `split` | auto subtitles/dubbing, long-video → short clips |
+
+## Shared conventions (all 8 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.
+- 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.
+- Always end with the final result URL(s) plus the credit amount already
+  charged/held.
+
+See each skill's `SKILL.md` for exact CLI flags and feature-specific
+error-handling.

package/skills/quickmagic-account/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: quickmagic-account
+description: >-
+  Foundation skill for the Quick Magic CLI: login/logout/status (`qm auth`),
+  credit balance + Qimi free-window benefit (`qm credits`), model catalog
+  (`qm models list`), and job status/waiting (`qm jobs`). Every other
+  quickmagic-* skill depends on this one for auth checks, pricing lookups,
+  job-id prefixes, and the common error-code table. Triggers: "đăng nhập
+  quickmagic", "kiểm tra số dư credit", "danh sách model AI", "theo dõi
+  trạng thái job", "quickmagic login", "check my credits".
+---
+
+# quickmagic-account — Auth, Credits, Models, Jobs (Foundation)
+
+Wraps `qm auth`, `qm credits`, `qm models list`, and `qm jobs`. Every `quickmagic-*`
+skill relies on this one — read it first if this is your first Quick Magic CLI task
+in a session. Bin name: `quickmagic` (alias `qm`).
+
+## Auth
+
+```bash
+qm auth login [--api-url <url>]   # opens a browser, OAuth PKCE, saves credentials
+qm auth status                    # prints email / balance / plan / api url
+qm auth logout                    # clears saved credentials
+```
+
+- `qm auth status` prints `Chưa đăng nhập. Chạy: quickmagic auth login` and exits
+  **1** when there is no saved (or env) token. Always check auth (run this, or
+  attempt the real command and read stderr) before any other quickmagic command in
+  a fresh session — if it fails, tell the user to run `qm auth login` and stop.
+- Credentials live in `~/.quickmagic/credentials.json`; access tokens auto-refresh
+  in the background, no manual re-login needed once logged in.
+- CI/headless: set `QUICKMAGIC_TOKEN` (+ optionally `QUICKMAGIC_REFRESH_TOKEN`) env
+  vars to skip the browser step entirely; nothing is written to disk in that mode.
+- `QUICKMAGIC_URL` overrides the API root (default `https://api.quickmagic.vn`).
+
+## Credits & the Qimi free-image window
+
+```bash
+qm credits
+```
+
+Prints `Số dư (balance)`, `Tạm giữ (held)`, `Gói (plan)`, and — only when active —
+`Qimi miễn phí: còn N ngày (chế độ: ...)`.
+
+- This benefit gives free `qimi_3`/`qimi_2.5` image generations for a limited
+  window (Business/Enterprise plans).
+- Mode **"Miễn phí — 1 ảnh/lần"**: one image per call is free; requesting more than
+  one in parallel (or `--n` > 1) costs credits.
+- Mode **"Nhanh — trả credit, chạy song song"**: the account chose speed over the
+  free tier — parallel generations always cost credits.
+- Any skill that generates `qimi_3`/`qimi_2.5` images should call `qm credits`
+  first and proactively surface this to the user before quoting a price.
+
+Note: `qm auth status` also prints a balance line, but only `qm credits` reports
+`held` and the Qimi benefit — use `qm credits` for anything pricing-related.
+
+## Browsing models
+
+```bash
+qm models list --type image   # columns: KEY | LABEL | CREDIT
+qm models list --type video    # columns: KEY | LABEL | CREDIT | IMAGES
+```
+
+- `IMAGES` (video only) shows the max reference images per input mode, e.g.
+  `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.
+- 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
+  default, or ask the user.
+- Always check this before quoting a price in any generate/edit/product/fashion/
+  cutout/hook skill — prices vary per model and change over time; never reuse a
+  remembered price from a previous session.
+
+## Job status & waiting
+
+```bash
+qm jobs get <id>              # prints the full job JSON
+qm jobs wait <id> [--out dir] # polls every 2.5s until a terminal status; downloads on success if --out is set
+```
+
+Never poll `jobs get` manually in a loop — always use `jobs wait` (or the
+generating command's own `--wait` flag, where available).
+
+**Job id prefixes** (dispatch table used by every `qm jobs` call):
+
+| Prefix | Feature | Result shape |
+|---|---|---|
+| `img_` | `generate image` | single `result_url` |
+| `vid_` | `generate video` | single `result_url` + `thumbnail_url` |
+| `pai_` | `product` | **array** `images[]` `{status, image_url, image_type}` |
+| `fsh_` | `fashion` | **array** `results[]` `{status, url, pose_index}` |
+| `vto_` | `tryon` | single `result_url` |
+| `edt_` | `edit` | single `result_url` |
+| `cut_` | `cutout` | **array** `images[]` `{status, result_url, operation}` |
+| `hok_` | `hook video` | single `result_url` + `thumbnail_url` |
+| `sub_` | `subtitle` | single `result_url` |
+| `spl_` | `split` | **array** `clips[]` `{title, url, thumbnail_url, start_time, end_time, status}` |
+| `mkt_` | `marketing video` | single result (no dedicated skill) |
+| `mot_` | `motion` | single result (no dedicated skill) |
+| `stt_` | `stt` | text result (no dedicated skill) |
+
+**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
+but downloads nothing — after status is `completed`, call `qm jobs get <id>` and
+read the array field yourself, then report each URL to the user.
+
+Statuses: `queued` → `in_progress` → `completed` (success) or `failed` (relay the
+job's `error` field). A `queued` status stuck past ~15 minutes is reported as
+`stalled` with a hint that the queue may be backed up — suggest retrying later
+rather than resubmitting immediately.
+
+## Common errors (any command)
+
+| CLI message (stderr, exit 1) | Meaning | What to do |
+|---|---|---|
+| `Chưa đăng nhập. Chạy: quickmagic auth login` | no local/env token | tell the user to run `qm auth login` |
+| `Không đủ credit: cần Xcr, hiện có Ycr, thiếu Zcr. Vui lòng nạp thêm để tiếp tục.` | `insufficient_credit` (HTTP 402) | state the exact shortfall (Z) and suggest topping up at https://quickmagic.vn/pricing |
+| `Tài khoản đang âm N credit. Vui lòng nạp thêm để tiếp tục sử dụng.` | `negative_balance` (HTTP 402) | same — must top up before any new paid job |
+| `Bạn đã có N job đang xử lý (giới hạn M job đồng thời cho gói ...)` | `concurrent_limit` (HTTP 429) | wait for an in-flight job to finish (`jobs wait`) before submitting more |
+| `Bạn thao tác quá nhanh. Chờ Ns.` | `rate_limited` (HTTP 429) | wait N seconds, then retry |
+| any other `Lỗi: <message>` | validation error (bad model/ref/prompt/URL — HTTP 400/413/502) | read the message, fix the offending flag, retry — don't blindly resubmit unchanged |
+
+Exit code is always `1` on any failure, `0` on success — safe to script around.
+
+## Example
+
+```bash
+qm auth status || qm auth login
+qm credits
+qm models list --type image
+qm jobs get img_12
+qm jobs wait vid_7 --out ./out
+```