quickmagic-cli 1.0.0

package/skills/quickmagic-cutout/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: quickmagic-cutout
+description: >-
+  Create a transparent-background PNG cutout of a product/subject, or
+  reinterpret a product photo into a new scene, via `qm cutout` (operations:
+  generate, from_ref, remix_describe). Triggers: "remove background", "tách
+  nền ảnh", "xoá phông sản phẩm", "ảnh PNG trong suốt", "product cutout", "đổi
+  bối cảnh ảnh sản phẩm".
+---
+
+# quickmagic-cutout — Transparent Cutout / Scene Remix
+
+Wraps `qm cutout`. Three operations — pick the right one:
+
+| Operation | What it does | Needs |
+|---|---|---|
+| `from_ref` (default) | Keep the subject from 1-5 reference images, isolate it on a **transparent background** | `--ref` (1-5) |
+| `generate` | Pure text-to-image, no reference | `--prompt` (required) |
+| `remix_describe` | Freely reinterpret **only the first** reference image per your prompt (+3 credit vision fee); background stays only if `--no-transparent-bg` | `--ref` (uses only `--ref[0]`), `--prompt` optional |
+
+## Command
+
+```
+qm cutout [--operation generate|from_ref|remix_describe] [--ref <r...>] [--prompt <p>] [--model <m>] [--aspect-ratio <r>] [--quality <q>] [--n <n>] [--no-transparent-bg] [--crid <id>]
+```
+
+| Flag | Notes |
+|---|---|
+| `--operation` | default `from_ref` |
+| `--ref <r...>` | URL or local file, repeatable, max 5; required for `from_ref`/`remix_describe` |
+| `--prompt <p>` | required when `--operation generate`; optional extra instruction otherwise (max 4000 chars) |
+| `--model <m>` | default `nano-banana-2` — recommended for accurate transparent backgrounds; check `qm models list --type image` for alternatives/price |
+| `--n <n>` | number of images, 1-6, default 1 |
+| `--no-transparent-bg` | only meaningful with `remix_describe` — keeps the original scene instead of cutting it out |
+
+## Before running
+
+1. `qm auth status` → not logged in → `qm auth login`.
+2. If the user hasn't supplied an image yet: `qm scrape <url>` or `qm import
+   <url>` can fetch one (free), or `qm assets products` for an existing library
+   item's image URL.
+3. `qm models list --type image` for the `--model`'s credit price.
+
+## Quote, then confirm
+
+Estimated cost = model credit price × `--n`. State it and get confirmation
+before running (this holds credit immediately), e.g. "nano-banana-2, 3cr/ảnh ×
+2 ảnh = 6cr, số dư Ycr — xác nhận?".
+
+## Run + track
+
+No `--wait` flag. The command prints raw JSON plus a hint:
+`→ Theo dõi: quickmagic jobs get cut_<batch>`. This job type returns an
+**array of images**, so `qm jobs wait cut_... --out ./out` will poll status
+correctly but **won't auto-download**. Once `completed`, run
+`qm jobs get cut_...` and read `images[]` (`{status, result_url, operation}`) —
+report each `result_url`.
+
+## Errors
+
+`Không đủ credit: ...` → state the shortfall + https://quickmagic.vn/pricing.
+Missing `--prompt` on `generate`, or missing `--ref` on `from_ref`/
+`remix_describe`, surfaces as a plain `Lỗi: <message>` — fix the flag and
+retry. Full reference: `quickmagic-account` skill.
+
+## Example
+
+```bash
+qm cutout --operation from_ref --ref ./product-photo.jpg --model nano-banana-2 --n 2
+qm jobs wait cut_1737000000abc --out ./out
+qm jobs get cut_1737000000abc
+```

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

@@ -0,0 +1,69 @@
+---
+name: quickmagic-edit-image
+description: >-
+  Restore, upscale (2k/4k), beauty-retouch, muscle-enhance, or color-boost a
+  single existing image via `qm edit`. Use for enhancing an existing photo,
+  not generating a new one. Triggers: "upscale ảnh lên 4k", "phục hồi ảnh cũ",
+  "làm đẹp da trong ảnh", "chỉnh màu ảnh", "restore old photo", "upscale
+  image resolution".
+---
+
+# quickmagic-edit-image — Photo Restore / Upscale / Retouch
+
+Wraps `qm edit <image>`. Edits **one existing image** in place — restoring
+damage, upscaling resolution, beauty retouch, muscle enhancement, or color
+grading. Not for generating a new image from a text prompt (use
+`quickmagic-generate` for that).
+
+## Command
+
+```
+qm edit <image> --tool <t> [--model qimi_2.5|qimi_3] [--upscale-target 2k|4k] [--style <s...>] [--crid <id>]
+```
+
+| Flag | Notes |
+|---|---|
+| `<image>` **required** (positional) | URL or local file path |
+| `--tool <t>` **required** | one of `restore` \| `upscale` \| `beauty` \| `muscle` \| `color_boost` |
+| `--model` | `qimi_2.5` or `qimi_3` (default `qimi_3`) |
+| `--upscale-target` | **required when `--tool upscale`** — `2k` or `4k` |
+| `--style <s...>` | **required when `--tool beauty`** — up to 3 style keywords, repeatable flag |
+| `--crid <id>` | idempotency key |
+
+Map the user's request to a tool: "ảnh cũ/rách/mờ" → `restore`; "phóng to/nét
+hơn/4K" → `upscale` (ask 2k or 4k if not specified); "làm đẹp da/mặt" → `beauty`
+(ask for up to 3 style keywords); "cơ bắp săn chắc hơn" → `muscle`; "màu sắc rực
+rỡ hơn" → `color_boost`.
+
+## Before running
+
+1. `qm auth status` → not logged in → `qm auth login`.
+2. `qm models list --type image` for `qimi_2.5`/`qimi_3` credit price.
+
+## Quote, then confirm
+
+State the model's per-image credit cost and get confirmation before running —
+submitting holds credit immediately.
+
+## Run + track
+
+No `--wait` flag. Copy the job id from the hint
+(`→ Theo dõi: quickmagic jobs get edt_3`), then `qm jobs wait edt_3 --out ./out`
+— single `result_url`, `--out` auto-downloads. Report the final URL +
+`credits_charged`.
+
+## Errors
+
+`Không đủ credit: ...` → state shortfall + https://quickmagic.vn/pricing.
+Missing `--upscale-target` on `upscale`, or missing `--style` on `beauty` →
+plain `Lỗi: <message>`; add the missing flag and retry. Full reference:
+`quickmagic-account` skill.
+
+## Example
+
+```bash
+qm edit ./old-photo.jpg --tool restore --model qimi_3
+qm edit ./portrait.jpg --tool upscale --upscale-target 4k
+qm edit ./selfie.jpg --tool beauty --style smooth-skin soft-light
+qm jobs wait edt_3 --out ./out
+```

package/skills/quickmagic-fashion/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: quickmagic-fashion
+description: >-
+  Generate fashion photos via `qm fashion` (outfit lookbook/pose shoots on a
+  KOL avatar or outfit-only) and `qm tryon` (virtual try-on of a garment onto
+  a specific model/person photo). Picks the right command based on whether
+  the user supplies a person photo to dress. Triggers: "virtual try-on", "thử
+  đồ ảo", "mặc thử quần áo", "lookbook thời trang", "ảnh KOL mặc outfit", "try
+  on this dress".
+---
+
+# quickmagic-fashion — Fashion & Virtual Try-On
+
+Two related but distinct commands — pick the right one first:
+
+| User wants... | Command |
+|---|---|
+| Put a garment on a **specific person photo** they provide (try-on / OOTD / fit-check) | `qm tryon` |
+| A styled **lookbook/pose shoot** of outfit(s) from the wardrobe library, optionally on a KOL/avatar | `qm fashion` |
+
+## Before running
+
+1. `qm auth status` → not logged in → tell the user to `qm auth login`.
+2. `qm assets outfits` (free) → `{id, name, preview_url}`, gives `outfit_ids` for
+   `qm fashion`.
+3. `qm assets kols` (free) → gives a `kol_id` for either command (the KOL/avatar
+   to wear the outfit).
+4. `qm models list --type image` for the credit price of the chosen model.
+
+## `qm tryon` — virtual try-on onto a person photo
+
+```
+qm tryon --model-image <img> [--type full|upper] [--model qimi_1.5|qimi_2.5|qimi_3] [--garment <img>] [--upper <img>] [--lower <img>] [--background <img>] [--prompt <p>] [--crid <id>]
+```
+
+- `--model-image` **required** — the person/model photo (URL or local file).
+- `--type full` (default) needs `--garment`; `--type upper` needs both `--upper`
+  and `--lower`.
+- `--background` and `--prompt` only apply with `qimi_2.5`/`qimi_3`.
+- Default model: `qimi_3`.
+- Output job hint: `vto_<n>`.
+
+## `qm fashion` — outfit lookbook
+
+```
+qm fashion --outfit <id...> [--mode <m>] [--kol-kind user_kol|system_kol] [--kol-id <id>] [--model <m>] [--crid <id>]
+```
+
+- `--outfit <id...>` **required** — one or more `outfit_ids` from
+  `qm assets outfits`.
+- `--mode` (server-validated; examples): `kol_outfit` (outfit worn by a KOL —
+  needs `--kol-id`), `outfit_only` (styled flat-lay/ghost-mannequin, no person),
+  `kol_couple` (two KOLs). If unsure which modes are valid, omit `--mode` and let
+  the server default apply, or ask the user to confirm the look they want.
+- `--kol-kind` distinguishes the user's own saved KOL (`user_kol`) vs a
+  system/preset avatar (`system_kol`).
+- Output job hint: `fsh_<n>`.
+
+## Quote, then confirm
+
+Both commands charge **per resulting image** — `qm fashion` in particular can
+produce multiple poses/results (`total_results` in the response), so the exact
+count may only be pinned down after submission. Tell the user the model's
+per-image credit rate from `qm models list` up front, and confirm intent to
+proceed before running either command — submitting holds credit immediately.
+
+## Run + track
+
+Neither command has `--wait`. Copy the job id from the printed hint
+(`→ Theo dõi: quickmagic jobs get vto_5` / `fsh_9`), then:
+
+- `qm tryon` → `qm jobs wait vto_5 --out ./out` (single `result_url` —
+  auto-downloads fine).
+- `qm fashion` → `qm jobs wait fsh_9 --out ./out` polls status but **won't
+  auto-download** (the job returns an array, not one `result_url`). Once
+  `completed`, run `qm jobs get fsh_9` and read `results[]`
+  (`{status, url, pose_index}`) — report each `url`.
+
+## Errors
+
+`Không đủ credit: ...` → state the shortfall + suggest
+https://quickmagic.vn/pricing. Otherwise relay the CLI's `Lỗi: <message>`
+verbatim. Full reference: `quickmagic-account` skill.
+
+## Examples
+
+```bash
+qm assets outfits
+qm assets kols
+qm fashion --outfit 12 15 --mode kol_outfit --kol-id 3 --model qimi_3
+qm jobs wait fsh_9 --out ./out
+
+qm tryon --model-image ./person.jpg --garment ./dress.jpg --model qimi_3
+qm jobs wait vto_5 --out ./out
+```

package/skills/quickmagic-generate/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: quickmagic-generate
+description: >-
+  Generate AI images or videos from a text prompt and/or reference photos via
+  the Quick Magic CLI (`qm generate image` / `qm generate video`). Lists
+  models with pricing, quotes the credit cost, confirms with the user before
+  spending, and surfaces the Qimi free-image window. Triggers: "generate an
+  image", "create a video", "tạo ảnh AI", "tạo video quảng cáo", "vẽ ảnh bằng
+  AI", "render video từ ảnh".
+---
+
+# quickmagic-generate — AI Image & Video Generation
+
+Wraps `qm generate image` and `qm generate video`. Use whenever the user wants to
+**create** new image(s) or a video from a prompt and/or reference images/photos.
+For editing an *existing* image see `quickmagic-edit-image`; for product-specific
+studio photos see `quickmagic-product-photoshoot`.
+
+## Before anything: auth + balance
+
+1. `qm auth status` — if it prints `Chưa đăng nhập...` (exit 1), tell the user to
+   run `qm auth login` first and stop.
+2. `qm credits` — read `Số dư`, `Tạm giữ`, `Gói`. If the output includes
+   `Qimi miễn phí: còn N ngày (chế độ: ...)`, the account has an active **Qimi
+   free-image window** (`qimi_3`/`qimi_2.5` models):
+   - Mode **"Miễn phí — 1 ảnh/lần"** → generating with `qimi_3`/`qimi_2.5` and
+     `--n 1` is free; proactively tell the user: "Qimi 3/2.5 đang MIỄN PHÍ (còn N
+     ngày, 1 ảnh/lần) — muốn tạo nhiều ảnh song song (`--n` > 1) hoặc dùng model
+     khác sẽ tốn credit."
+   - Mode **"Nhanh — trả credit, chạy song song"** → the benefit is active but this
+     account pays credits for parallel speed; say so plainly.
+
+## Pick the right model
+
+`qm models list --type image` or `qm models list --type video` → table
+`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`).
+
+- This table doesn't print quality tiers — image quality levels are commonly
+  `1K`/`2K`/`4K`, priced differently per level. If `--quality` matters, mention the
+  level naming and let the server validate, or omit the flag for the model default.
+- Match model to intent: photorealistic vs stylized, image-to-image (needs `--ref`)
+  vs text-only, required aspect ratio, required video duration/resolution.
+
+## Quote, then confirm (mandatory before spending credits)
+
+Compute an estimate: `credit (from models list) × --n` for images, or the video
+model's listed `credit` (base duration/resolution — actual price can vary by
+`--duration`/`--resolution`, shown precisely only after submission via
+`credits_held`). Present it to the user, e.g.:
+
+> "Model qimi_3: 10cr/ảnh × 4 ảnh = 40cr. Số dư hiện tại: 120cr. Xác nhận tạo?"
+
+Do not run `generate image`/`generate video` until the user confirms — submitting
+holds credit immediately.
+
+## Commands
+
+| Command | Required flags | Key optional flags |
+|---|---|---|
+| `qm generate image` | `--prompt <p>` | `--model <m>` (default `qimi_3`), `--quality <q>`, `--aspect-ratio <r>`, `--n <n>` (default 1), `--ref <r...>` (repeatable — URL or local file path), `--wait`, `--out <dir>` |
+| `qm generate video` | `--prompt <p>`, `--model <m>` | `--duration <d>`, `--resolution <r>`, `--aspect-ratio <r>`, `--image <i...>` (repeatable), `--mode reference\|frames`, `--wait`, `--out <dir>` |
+
+- `--ref` / `--image` accept a URL (kept as-is) or a local file path (read + base64
+  encoded automatically). Files over ~8MB print a warning — prefer URLs (`qm scrape
+  <url>` or `qm import <url>` can produce a hosted URL from a product page or a
+  TikTok/Instagram post).
+- `--mode frames` caps at 2 images (first/last frame); `--mode reference` allows
+  more (see the `IMAGES` column). A wrong count is rejected server-side.
+
+## Run + wait for results
+
+- Add `--wait --out <dir>` to the generate command itself to poll and
+  auto-download in one step (polls every 2.5s internally).
+- Or run without `--wait`, note the printed job id(s)
+  (`Đã tạo N job ảnh: img_12, img_13` / `Đã tạo job video: vid_7`), then separately:
+  `qm jobs wait img_12 --out ./out`.
+- Batch requests (`--n` > 1, or several video jobs): the platform runs several jobs
+  in parallel automatically per the account's plan tier; anything beyond that
+  queues server-side — no manual throttling needed, just submit and `jobs wait`.
+
+## Report the result
+
+Always end with: the final URL(s) (downloaded file path if `--out` was used,
+otherwise the `result_url` field from `qm jobs get <id>`) **and** the credit info
+already printed after submission (`Credit tạm giữ: X · Số dư: Y`).
+
+## Errors
+
+- `Lỗi: Không đủ credit: cần Xcr, hiện có Ycr, thiếu Zcr. Vui lòng nạp thêm để
+  tiếp tục.` → tell the user exactly how many credits (Z) are missing and suggest
+  topping up at https://quickmagic.vn/pricing (or via the Quick Magic app).
+- `Lỗi: Tài khoản đang âm N credit...` → balance is negative, must top up before
+  any new job.
+- `[id] job lỗi: failed` (or `stalled`) after `jobs wait` → relay the job's
+  `error` field from `qm jobs get <id>`; a `stalled` status past ~15 minutes
+  queued means the queue is backed up — suggest retrying later.
+- Full error-code reference and job-status semantics: `quickmagic-account` skill.
+
+## Examples
+
+```bash
+qm auth status
+qm credits
+qm models list --type image
+qm generate image --prompt "a red sneaker on white background" --model qimi_3 --n 4 --aspect-ratio 1:1 --wait --out ./out
+
+qm models list --type video
+qm generate video --prompt "product slowly rotating" --model grok-imagine --duration 8 --resolution 720p --image ./product.jpg --wait --out ./out
+
+qm jobs get img_12
+```

package/skills/quickmagic-hook-video/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: quickmagic-hook-video
+description: >-
+  Generate a ~10 second comedy ad video from a character photo + a product
+  photo using one of 18 Hook Studio presets, via `qm hook presets` (browse +
+  price) and `qm hook video` (generate). Triggers: "hook video", "video
+  quảng cáo hài hước", "video viral cho sản phẩm", "tạo hook ads", "comedy ad
+  video".
+---
+
+# quickmagic-hook-video — Hook Studio Comedy Ads
+
+Wraps `qm hook presets` (browse) and `qm hook video` (generate). Produces a short
+(~10s) comedy-style ad video: a character reacts/performs around a product,
+following one of 18 written presets (each with its own script beats — the actual
+prompt text is not exposed, only title/description/beats/preview).
+
+## Step 1 — always browse presets first
+
+```bash
+qm hook presets
+```
+
+Returns JSON:
+- `presets[]` — `{id, title, title_en, tagline, description, beats[], poster_url,
+  video_url, sample_character_url, sample_product_url, aspect_default}` for all 18
+  presets: `stream`, `breaking-news`, `bear-chase`, `pitch-invasion`,
+  `product-run`, `cho-mang-review`, `unbox-bat-ngo`, `san-sale-sap-san`,
+  `time-freeze`, `street-interview`, `podcast-clip`, `elevator-pitch`,
+  `red-carpet`, `me-chong-review`, `hang-xom-hong`, `tra-da-via-he`,
+  `boc-phot-plot-twist`, `di-cho-flex`.
+- `credit_cost` — the flat credit price for one hook video at the default
+  resolution.
+- `aspects` — `["9:16", "16:9"]`.
+- `speech_lang_options[]` — `{value, label}` (e.g. `vi`/`Tiếng Việt`,
+  `en`/`English`, plus Thai/Indonesian/Chinese/Japanese/Korean/Spanish/
+  Portuguese/French/Hindi).
+- `resolution_options` — typically `["720p", "1080p"]`.
+- `style_options[]` — `{value, label}`, 9 comedic styles (`slapstick`, `chase`,
+  `chaos`, `absurd`, `epic_fail`, `heroic`, `surreal`, `panic`, `parody`).
+- `format_options[]` — `{value, label}`, 4 formats (`shorts`, `reels`, `ugc`,
+  `ad`).
+
+## Step 2 — recommend a preset for the user's product
+
+Read each preset's `title`/`tagline`/`description`/`beats` and match to the
+product's category and the vibe the user wants (chaotic/action →
+`bear-chase`/`pitch-invasion`/`time-freeze`; sales/livestream energy →
+`cho-mang-review`/`san-sale-sap-san`; reveal/twist → `unbox-bat-ngo`; news parody
+→ `breaking-news`). Show the user 1-3 candidate presets with their `tagline` +
+`poster_url`/`video_url` before picking one.
+
+## Step 3 — quote + confirm
+
+State `credit_cost` from `hook presets` and get explicit confirmation before
+running `hook video` (it holds credit immediately).
+
+## Step 4 — generate
+
+```
+qm hook video --preset <id> --character <img> --product <img> [--aspect 9:16|16:9] [--speech-lang <l>] [--cta <s>] [--location <img>] [--accessory <img>] [--style <s>] [--format <f>] [--resolution 720p|1080p] [--crid <id>]
+```
+
+| Flag | Notes |
+|---|---|
+| `--preset <id>` **required** | a valid `id` from `hook presets` |
+| `--character <img>` **required** | URL or local file — the person featured |
+| `--product <img>` **required** | URL or local file — the product |
+| `--aspect` | default `9:16` |
+| `--speech-lang` | default `vi`; any value from `speech_lang_options`, or free text for another language |
+| `--cta` | custom call-to-action line (overrides the preset's default line) |
+| `--location` / `--accessory` | optional extra reference photos |
+| `--style` / `--format` | single value from `style_options` / `format_options` |
+| `--resolution` | `720p` or `1080p` |
+
+If the user doesn't have character/product photos ready, `qm scrape <url>` /
+`qm import <url>` / `qm assets products` / `qm assets kols` can source them (all
+free).
+
+## Run + track
+
+No `--wait` flag. Copy the job id from the hint
+(`→ Theo dõi: quickmagic jobs get hok_7`), then `qm jobs wait hok_7 --out ./out`
+— this job type has a single `result_url` (+ `thumbnail_url`), so `--out`
+**does** auto-download. Report the final video URL + `credits_charged`.
+
+## Errors
+
+`Không đủ credit: ...` → state shortfall + https://quickmagic.vn/pricing.
+Invalid `--preset`, or a missing character/product image, surfaces as a plain
+`Lỗi: <message>` — re-check against `hook presets` output. Full reference:
+`quickmagic-account` skill.
+
+## Example
+
+```bash
+qm hook presets
+qm hook video --preset cho-mang-review --character ./host.jpg --product ./drink-can.jpg --speech-lang vi --aspect 9:16
+qm jobs wait hok_7 --out ./out
+```

package/skills/quickmagic-product-photoshoot/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: quickmagic-product-photoshoot
+description: >-
+  Generate studio/marketing product photos (packshots, lifestyle posters,
+  infographics, composites) from 1-3 reference images via `qm product`. Use
+  for product catalog/ad photography, not for putting a garment on a person.
+  Triggers: "product photoshoot", "ảnh sản phẩm studio", "chụp ảnh sản phẩm
+  AI", "tạo poster sản phẩm", "packshot", "catalog photo".
+---
+
+# quickmagic-product-photoshoot — Product AI
+
+Wraps `qm product` (Product AI batch generation). Use for **studio/marketing
+photos of a product** — packshots, lifestyle/poster images, infographics, or
+composites — NOT for putting a product/outfit ON a person (that's
+`quickmagic-fashion`'s `tryon`).
+
+## Before running
+
+1. `qm auth status` → if not logged in, tell the user to `qm auth login` first.
+2. Get a reference image if the user doesn't have one ready:
+   - Already saved in the product library → `qm assets products` (free, no
+     credit) lists `{id, name, preview_url}`; use the numeric `id` directly as a
+     `--refs` value.
+   - From a product page URL → `qm scrape <url>` (free) returns a Quick
+     Magic-hosted image URL.
+   - From a TikTok/Instagram product post → `qm import <url> --media image`
+     (free).
+   - Otherwise a plain image URL or a local file path both work as `--refs`
+     values.
+3. `qm models list --type image` for the credit price of the chosen `--model`
+   (default `qimi_2.5`).
+
+## Command
+
+```
+qm product --refs <r...> [--types <t...>] [--count <n>] [--kol-id <id>] [--instruction <s>] [--model <m>] [--crid <id>]
+```
+
+| Flag | Meaning |
+|---|---|
+| `--refs <r...>` **required** | 1-3 values: numeric `product_id` (from `qm assets products`) OR an image URL/local file |
+| `--types <t...>` | one or more of `product` \| `poster` \| `infographic` \| `composite` (default `product`) |
+| `--count <n>` | images generated **per type** (1-20, default 4) |
+| `--kol-id <id>` | optional avatar/KOL id (from `qm assets kols`) to feature alongside the product |
+| `--instruction <s>` | extra free-text art direction (max 2000 chars) |
+| `--model <m>` | image model key (default `qimi_2.5`) |
+| `--crid <id>` | idempotency key — reuse on retry to avoid double charge |
+
+Map user intent to `--types`: catalog/e-commerce shot → `product`; social/ad
+banner → `poster`; spec sheet / feature callouts → `infographic`; multiple items
+together → `composite`. Multiple types can be combined in one call.
+
+## Quote, then confirm
+
+Total images = `--count` × number of `--types` values. Estimated cost = that
+total × the model's `credit` from `qm models list --type image`. State it, e.g.
+"qimi_2.5, 4 ảnh × 2 loại (product+poster) = 8 ảnh × 8cr = 64cr, số dư hiện tại
+Ycr — xác nhận tạo?" before running.
+
+## Run + track
+
+`qm product` has **no `--wait` flag** — it prints raw JSON plus a hint line:
+
+```
+→ Theo dõi: quickmagic jobs get pai_1737000000_ab12
+```
+
+Copy that job id and run `qm jobs wait pai_... --out ./out` — **but note**: this
+job type returns an **array of images**, not one `result_url`; `jobs wait --out`
+will poll status correctly but will **not auto-download** (the CLI only
+auto-downloads when the job view has a single `result_url`). Once status is
+`completed`, run `qm jobs get pai_...` and read `images[]` — each entry is
+`{status, image_url, image_type}`. Report every `image_url` to the user.
+
+## Errors
+
+- `Không đủ credit: cần Xcr, hiện có Ycr, thiếu Zcr...` → state the shortfall,
+  suggest topping up (https://quickmagic.vn/pricing).
+- Invalid/missing ref → CLI prints `Lỗi: <message>`; check the `--refs` value is
+  a valid id, URL, or existing local file.
+- Full error/status reference: `quickmagic-account` skill.
+
+## Example
+
+```bash
+qm assets products
+qm product --refs 42 --types product poster --count 4 --model qimi_2.5
+qm jobs wait pai_1737000000_ab12 --out ./out
+qm jobs get pai_1737000000_ab12
+```

package/skills/quickmagic-subtitle-split/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: quickmagic-subtitle-split
+description: >-
+  Add auto-subtitles (with optional translation/dubbing) via `qm subtitle`,
+  or cut a long video into short highlight clips via `qm split`. Both take a
+  direct video URL or a TikTok/Instagram post link (not YouTube). Triggers:
+  "thêm phụ đề tự động", "lồng tiếng video", "dịch phụ đề", "cắt video dài
+  thành clip ngắn", "auto subtitle", "split video into shorts".
+---
+
+# quickmagic-subtitle-split — Auto-Subtitle & Video Splitting
+
+Wraps two related video post-processing commands:
+
+| Command | What it does |
+|---|---|
+| `qm subtitle <video_url>` | Adds subtitles to a video, with optional translation and/or voice dubbing |
+| `qm split <video_url>` | Cuts one long video into several short highlight clips with auto-generated titles |
+
+Both need a **direct video file URL, or a TikTok/Instagram POST link** — **not a
+YouTube link, not a profile page**. If the user only has a YouTube link, tell
+them it's not supported by this command.
+
+## Commands
+
+```
+qm subtitle <video_url> [--dub] [--translate <lang>] [--crid <id>]
+qm split <video_url> [--mode auto|specific] [--title-lang <l>] [--translate <lang>] [--crid <id>]
+```
+
+| Flag | Notes |
+|---|---|
+| `--dub` (subtitle only) | enable voice dubbing, not just text subtitles |
+| `--translate <lang>` | translate subtitles / clip titles to this language |
+| `--mode` (split only) | `auto` (default, auto-detected highlights) or `specific` |
+| `--title-lang` (split only) | language for generated clip titles |
+
+## Before running
+
+1. `qm auth status` → not logged in → `qm auth login`.
+2. If the user only gave a TikTok/Instagram link and the raw file is needed for
+   another step first, `qm import <url> --media video` (free) re-hosts it on
+   Quick Magic.
+
+## Pricing — no upfront quote is possible
+
+Unlike other features, there is **no command to preview the credit price**
+before submitting — both are billed **by the video's duration**, which the
+server only knows after it downloads/probes the video. Do not invent a number.
+Instead:
+
+1. Tell the user plainly: "Phí tính theo thời lượng video, chỉ biết chính xác
+   sau khi server tải video về — vẫn muốn tiếp tục?"
+2. Get a go-ahead to proceed (not a numeric confirmation).
+3. Run the command; read `credits_held` and `duration_sec` from the JSON
+   response and report those as the actual charge.
+
+## Run + track
+
+Neither command has `--wait`. Copy the job id from the printed hint:
+
+- `qm subtitle` → `→ Theo dõi: quickmagic jobs get sub_4` →
+  `qm jobs wait sub_4 --out ./out` (single `result_url`, auto-downloads).
+- `qm split` → `→ Theo dõi: quickmagic jobs get spl_8` →
+  `qm jobs wait spl_8 --out ./out` polls status but **won't auto-download**
+  (result is a `clips[]` array, not one `result_url`). Once `completed`, run
+  `qm jobs get spl_8` and read `clips[]`
+  (`{title, url, thumbnail_url, start_time, end_time, status, social_content}`)
+  — report every clip's `url` + `title`.
+
+## Errors
+
+`Không đủ credit: ...` → state shortfall + https://quickmagic.vn/pricing. A
+YouTube link or an unreachable URL surfaces as a plain `Lỗi: <message>` — ask
+the user for a direct file URL or a TikTok/Instagram post link instead. Full
+reference: `quickmagic-account` skill.
+
+## Example
+
+```bash
+qm subtitle https://cdn.example.com/video.mp4 --translate en
+qm jobs wait sub_4 --out ./out
+
+qm split https://www.tiktok.com/@user/video/123456 --mode auto --title-lang Vietnamese
+qm jobs wait spl_8
+qm jobs get spl_8
+```