quickmagic-cli 1.0.0

package/src/api.js

@@ -0,0 +1,77 @@
+// api.js — fetch wrapper Bearer + auto-refresh (sớm 60s / retry 1 lần khi 401).
+// H5: lockfile ~/.quickmagic/refresh.lock chống 2 process refresh đồng thời (revoke family).
+const fs = require('fs');
+const config = require('./config');
+const { refresh } = require('./oauth');
+
+const EARLY_REFRESH_MS = 60000; // refresh sớm khi access token còn < 60s
+const LOCK_MAX_TRIES = 50; // chờ tối đa ~5s để lấy lock
+const LOCK_WAIT_MS = 100;
+
+// H5 — lockfile best-effort (kết hợp grace-window server P1). Tự giải phóng sau khi xong.
+async function withRefreshLock(fn) {
+  for (let i = 0; i < LOCK_MAX_TRIES; i += 1) {
+    let fd;
+    try {
+      fd = fs.openSync(config.LOCK_FILE, 'wx'); // 'wx' — lỗi nếu lock đã tồn tại
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      await new Promise((r) => setTimeout(r, LOCK_WAIT_MS)); // đang có process khác refresh → chờ
+      continue;
+    }
+    try {
+      return await fn();
+    } finally {
+      fs.closeSync(fd);
+      try {
+        fs.unlinkSync(config.LOCK_FILE);
+      } catch {
+        // lock đã bị xoá — bỏ qua
+      }
+    }
+  }
+  return fn(); // hết thời gian chờ → cứ refresh (grace-window server đỡ)
+}
+
+function doRefresh() {
+  return withRefreshLock(refresh);
+}
+
+// Gọi REST /public/v1<rest_path>. Trả về trường `data`. Ném lỗi khi HTTP lỗi hoặc success=false.
+async function call(method, rest_path, { body } = {}) {
+  let creds = config.load();
+  if (!creds || (!creds.access_token && !creds.refresh_token)) {
+    throw new Error('Chưa đăng nhập. Chạy: quickmagic auth login');
+  }
+
+  // Refresh sớm khi access token sắp hết hạn (bỏ qua nếu không có expires_at/refresh_token — env CI).
+  if (creds.expires_at && creds.refresh_token && creds.expires_at - Date.now() < EARLY_REFRESH_MS) {
+    await doRefresh();
+    creds = config.load();
+  }
+
+  const doFetch = () =>
+    fetch(`${config.restBase(creds.api_url)}${rest_path}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${creds.access_token}`,
+        'content-type': 'application/json',
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+
+  let res = await doFetch();
+  if (res.status === 401 && creds.refresh_token) {
+    await doRefresh(); // 401 → refresh 1 lần rồi retry
+    creds = config.load();
+    res = await doFetch();
+  }
+
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok || json.success === false) {
+    throw new Error(json.message || `HTTP ${res.status}`);
+  }
+  return json.data;
+}
+
+module.exports = { call };

package/src/commands/auth.js

@@ -0,0 +1,32 @@
+// commands/auth.js — login / logout / status.
+const oauth = require('../oauth');
+const config = require('../config');
+const api = require('../api');
+
+// Đăng nhập qua browser (OAuth PKCE). Cờ --api-url ghi đè URL gốc.
+async function login(options) {
+  const api_url = config.apiUrl(options && options.apiUrl);
+  await oauth.login(api_url);
+}
+
+// Đăng xuất — xoá credentials.json.
+function logout() {
+  config.clear();
+  console.log('Đã đăng xuất.');
+}
+
+// Trạng thái — in email/số dư qua GET /public/v1/credits, hoặc báo chưa đăng nhập (exit 1).
+async function status() {
+  const creds = config.load();
+  if (!creds || (!creds.access_token && !creds.refresh_token)) {
+    console.log('Chưa đăng nhập. Chạy: quickmagic auth login');
+    process.exit(1);
+  }
+  const data = await api.call('GET', '/credits');
+  if (data && data.email) console.log(`Email:   ${data.email}`);
+  console.log(`Số dư:   ${(data && data.balance) ?? 0} credit`);
+  if (data && data.plan) console.log(`Gói:     ${data.plan}`);
+  console.log(`API URL: ${creds.api_url || config.DEFAULT_API_URL}`);
+}
+
+module.exports = { login, logout, status };

package/src/commands/credits.js

@@ -0,0 +1,19 @@
+// commands/credits.js — in số dư credit qua GET /public/v1/credits.
+const api = require('../api');
+
+async function show() {
+  const data = await api.call('GET', '/credits');
+  console.log(`Số dư (balance): ${data.balance ?? 0}`);
+  console.log(`Tạm giữ (held):  ${data.held ?? 0}`);
+  console.log(`Gói (plan):      ${data.plan ?? '—'}`);
+  // Benefit Qimi: cửa sổ 10 ngày miễn phí ảnh qimi_3/qimi_2.5 (gói Business/Enterprise).
+  if (data.qimi_benefit?.active) {
+    const days = data.qimi_benefit.window_ends_at
+      ? Math.max(0, Math.ceil((data.qimi_benefit.window_ends_at - Date.now()) / 86400000))
+      : 0;
+    const mode = data.qimi_benefit.speed_mode ? 'Nhanh — trả credit, chạy song song' : 'Miễn phí — 1 ảnh/lần';
+    console.log(`Qimi miễn phí:   còn ${days} ngày (chế độ: ${mode})`);
+  }
+}
+
+module.exports = { show };

package/src/commands/generate.js

@@ -0,0 +1,70 @@
+// commands/generate.js — tạo ảnh/video AI. --ref/--image: URL giữ nguyên, file local → base64 data URI.
+const fs = require('fs');
+const path = require('path');
+const api = require('../api');
+const jobs = require('./jobs');
+
+const MAX_LOCAL_BYTES = 8 * 1024 * 1024; // cảnh báo khi file > 8MB (body giới hạn ~10MB)
+const MIME_BY_EXT = {
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.png': 'image/png',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+};
+
+// URL/data URI → giữ nguyên; file local → data:<mime>;base64,...
+function resolveInputImage(ref) {
+  if (/^https?:\/\//i.test(ref) || /^data:/i.test(ref)) return ref;
+  const abs_path = path.resolve(ref);
+  const ext = path.extname(abs_path).toLowerCase();
+  const mime = MIME_BY_EXT[ext] || 'image/png';
+  const buf = fs.readFileSync(abs_path);
+  if (buf.length > MAX_LOCAL_BYTES) {
+    console.warn(`Cảnh báo: ${ref} > 8MB — body giới hạn ~10MB, nên dùng URL thay vì file local.`);
+  }
+  return `data:${mime};base64,${buf.toString('base64')}`;
+}
+
+function resolveInputImages(refs) {
+  if (!refs || !refs.length) return [];
+  return refs.map(resolveInputImage);
+}
+
+// generate image — POST /public/v1/images.
+async function image(options) {
+  const ref_image_urls = resolveInputImages(options.ref);
+  const num_images = parseInt(options.n, 10) || 1;
+  const body = { prompt: options.prompt, model: options.model, num_images };
+  if (options.quality) body.quality = options.quality;
+  if (options.aspectRatio) body.aspect_ratio = options.aspectRatio;
+  if (ref_image_urls.length) body.ref_image_urls = ref_image_urls;
+
+  const data = await api.call('POST', '/images', { body });
+  const job_ids = (data.jobs || []).map((j) => j.job_id);
+  console.log(`Đã tạo ${job_ids.length} job ảnh: ${job_ids.join(', ')}`);
+  console.log(`Credit tạm giữ: ${data.credits_held ?? '?'} · Số dư: ${data.balance ?? '?'}`);
+
+  if (options.wait) await jobs.waitAll(job_ids, options.out);
+}
+
+// generate video — POST /public/v1/videos.
+async function video(options) {
+  const image_urls = resolveInputImages(options.image);
+  const body = { prompt: options.prompt, model: options.model };
+  if (options.duration) body.duration = options.duration;
+  if (options.resolution) body.resolution = options.resolution;
+  if (options.aspectRatio) body.aspect_ratio = options.aspectRatio;
+  if (image_urls.length) body.image_urls = image_urls;
+  // --mode reference|frames (R2V 260706): server validate theo model; bỏ trống = default model.
+  if (options.mode) body.image_mode = options.mode;
+
+  const data = await api.call('POST', '/videos', { body });
+  const job_id = data.job_id;
+  console.log(`Đã tạo job video: ${job_id}`);
+  console.log(`Credit tạm giữ: ${data.credits_held ?? '?'} · Số dư: ${data.balance ?? '?'}`);
+
+  if (options.wait) await jobs.waitAll([job_id], options.out);
+}
+
+module.exports = { image, video };

package/src/commands/jobs.js

@@ -0,0 +1,69 @@
+// commands/jobs.js — theo dõi job: get / wait / waitAll + tải kết quả.
+const fs = require('fs');
+const path = require('path');
+const api = require('../api');
+
+const POLL_INTERVAL_MS = 2500;
+// Trạng thái kết thúc (M6 — union các status server có thể trả sau chuẩn hoá).
+const TERMINAL_STATUSES = new Set(['completed', 'error', 'failed', 'success', 'stalled', 'timeout']);
+const SUCCESS_STATUSES = new Set(['completed', 'success']);
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// jobs get <id> — in JSON chi tiết job.
+async function get(id) {
+  const data = await api.call('GET', `/jobs/${id}`);
+  console.log(JSON.stringify(data, null, 2));
+}
+
+// Tải result_url → ghi file, tên lấy từ URL (bỏ query).
+async function download(url, out_dir) {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`tải file thất bại: HTTP ${res.status}`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  const url_name = path.basename(new URL(url).pathname) || `download-${Date.now()}`;
+  fs.mkdirSync(out_dir, { recursive: true });
+  const dest = path.join(out_dir, url_name);
+  fs.writeFileSync(dest, buf);
+  console.log(`Đã tải: ${dest}`);
+  return dest;
+}
+
+// Poll 1 job mỗi 2.5s tới trạng thái kết thúc; tải kết quả nếu thành công + có --out.
+async function waitOne(id, out_dir) {
+  for (;;) {
+    const data = await api.call('GET', `/jobs/${id}`);
+    const status = data.status;
+    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 {
+        console.error(`[${id}] job lỗi: ${data.error || status}`);
+      }
+      return data;
+    }
+    await sleep(POLL_INTERVAL_MS);
+  }
+}
+
+// jobs wait <id> [--out dir] — chờ 1 job, exit 1 nếu thất bại.
+async function wait(id, options) {
+  const data = await waitOne(id, options && options.out);
+  if (!SUCCESS_STATUSES.has(data.status)) process.exit(1);
+}
+
+// Chờ nhiều job tuần tự (dùng cho generate --wait); exit 1 nếu có job thất bại.
+async function waitAll(ids, out_dir) {
+  let has_error = false;
+  for (const id of ids) {
+    const data = await waitOne(id, out_dir);
+    if (!SUCCESS_STATUSES.has(data.status)) has_error = true;
+  }
+  if (has_error) process.exit(1);
+}
+
+module.exports = { get, wait, waitAll, download };

package/src/commands/models.js

@@ -0,0 +1,46 @@
+// commands/models.js — liệt kê model ảnh/video dạng bảng key | label | credit (+IMAGES cho video).
+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.
+function imagesCell(m) {
+  const by_mode = m.image_max_by_mode || {};
+  const banned = m.no_real_person_modes || [];
+  const parts = Object.entries(by_mode).map(([mode, max]) => {
+    const short = mode === 'reference' ? 'ref' : mode;
+    return `${short} ${max}${banned.includes(mode) ? '*' : ''}`;
+  });
+  return parts.join(' · ') || String(m.image_max ?? '');
+}
+
+async function list(options) {
+  const type = (options && options.type) || 'image';
+  const data = await api.call('GET', `/models?type=${encodeURIComponent(type)}`);
+  const models = data.models || [];
+  if (!models.length) {
+    console.log('Không có model nào.');
+    return;
+  }
+
+  const is_video = type === 'video';
+  const rows = models.map((m) => ({
+    key: String(m.key || ''),
+    label: String(m.label || ''),
+    credit: String(m.credit ?? m.credit_cost ?? m.credit_per_image ?? ''),
+    images: is_video ? imagesCell(m) : '',
+  }));
+  const key_w = Math.max(3, ...rows.map((r) => r.key.length));
+  const label_w = Math.max(5, ...rows.map((r) => r.label.length));
+  const credit_w = Math.max(6, ...rows.map((r) => r.credit.length));
+
+  const header = `${'KEY'.padEnd(key_w)}  ${'LABEL'.padEnd(label_w)}  ${'CREDIT'.padEnd(credit_w)}${is_video ? '  IMAGES' : ''}`;
+  console.log(header);
+  console.log('-'.repeat(header.length + (is_video ? 14 : 0)));
+  for (const r of rows) {
+    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.');
+  }
+}
+
+module.exports = { list };

package/src/commands/tools.js

@@ -0,0 +1,41 @@
+// tools.js — lệnh CLI cho 17 tool mở rộng (gọi REST /public/v1 qua api.call). In kết quả JSON gọn.
+const { call } = require('../api');
+
+const out = (data) => console.log(JSON.stringify(data, null, 2));
+const jobHint = (data) => {
+  out(data);
+  const id = data.job_id || (Array.isArray(data.job_ids) && data.job_ids[0]);
+  if (id) console.log(`\n→ Theo dõi: quickmagic jobs get ${id}`);
+};
+const run = (fn) => (...a) => fn(...a).catch((e) => { console.error('Lỗi:', e.message); process.exit(1); });
+
+// ── Nhập liệu (không tốn credit) ──
+const scrape = run(async (url) => out(await call('POST', '/scrape', { body: { url } })));
+const importSocial = run(async (url, o) => out(await call('POST', '/import', { body: { url, media: o.media || 'image', max: o.max ? Number(o.max) : undefined } })));
+const assets = run(async (kind, o) => out(await call('GET', `/assets?kind=${encodeURIComponent(kind)}${o.limit ? `&limit=${Number(o.limit)}` : ''}`)));
+const analyze = run(async (video_url, o) => out(await call('POST', '/analyze', { body: { video_url, product_id: o.productId ? Number(o.productId) : undefined } })));
+
+// ── Marketing ──
+const marketingModes = run(async () => out(await call('GET', '/marketing/modes')));
+const marketingVideo = run(async (o) => jobHint(await call('POST', '/marketing/videos', { body: { mode_id: Number(o.mode), product_id: o.productId ? Number(o.productId) : undefined, avatar_id: o.avatarId ? Number(o.avatarId) : undefined, avatar_kind: o.avatarKind, duration: o.duration ? Number(o.duration) : undefined, aspect_ratio: o.aspectRatio, client_request_id: o.crid } })));
+
+// ── Product / Fashion ──
+const product = run(async (o) => jobHint(await call('POST', '/product/images', { body: { refs: (o.refs || []).map((r) => (/^\d+$/.test(r) ? Number(r) : r)), image_types: o.types || ['product'], count_per_type: o.count ? Number(o.count) : undefined, kol_id: o.kolId ? Number(o.kolId) : undefined, instruction: o.instruction, model: o.model, client_request_id: o.crid } })));
+const fashion = run(async (o) => jobHint(await call('POST', '/fashion/images', { body: { mode: o.mode, outfit_ids: (o.outfit || []).map(Number), kol_kind: o.kolKind, kol_id: o.kolId ? Number(o.kolId) : undefined, model: o.model, client_request_id: o.crid } })));
+
+// ── Ảnh ──
+const edit = run(async (image, o) => jobHint(await call('POST', '/edit', { body: { image, tool: o.tool, model: o.model, upscale_target: o.upscaleTarget, style: o.style, client_request_id: o.crid } })));
+const tryon = run(async (o) => jobHint(await call('POST', '/tryon', { body: { type: o.type, model: o.model, model_image: o.model_image, garment_image: o.garment, upper_image: o.upper, lower_image: o.lower, background_image: o.background, prompt: o.prompt, client_request_id: o.crid } })));
+
+// ── Video nặng / audio ──
+const stt = run(async (audio_url, o) => jobHint(await call('POST', '/stt', { body: { audio_url, language_translate: o.translate, client_request_id: o.crid } })));
+const subtitle = run(async (video_url, o) => jobHint(await call('POST', '/subtitle', { body: { video_url, enable_voice_dubbing: !!o.dub, target_lang: o.translate, client_request_id: o.crid } })));
+const split = run(async (video_url, o) => jobHint(await call('POST', '/split', { body: { video_url, clip_mode: o.mode, title_lang: o.titleLang, translate_lang: o.translate, client_request_id: o.crid } })));
+const motion = run(async (video_url, o) => jobHint(await call('POST', '/motion', { body: { video_url, image_urls: o.image || [], model: o.model, mode: o.mode, prompt: o.prompt, client_request_id: o.crid } })));
+
+// ── Cutout / Hook Studio ──
+const cutout = run(async (o) => jobHint(await call('POST', '/cutout', { body: { operation: o.operation, ref_image_urls: o.ref || [], prompt: o.prompt, model: o.model, aspect_ratio: o.aspectRatio, quality: o.quality, num_images: o.n ? Number(o.n) : undefined, transparent_bg: o.transparentBg, client_request_id: o.crid } })));
+const hookPresets = run(async () => out(await call('GET', '/hook/presets')));
+const hookVideo = run(async (o) => jobHint(await call('POST', '/hook/videos', { body: { preset_id: o.preset, character_url: o.character, product_url: o.product, aspect: o.aspect, speech_lang: o.speechLang, custom_cta: o.cta, location_url: o.location, accessory_url: o.accessory, style: o.style, format: o.format, resolution: o.resolution, client_request_id: o.crid } })));
+
+module.exports = { scrape, importSocial, assets, analyze, marketingModes, marketingVideo, product, fashion, edit, tryon, stt, subtitle, split, motion, cutout, hookPresets, hookVideo };

package/src/config.js

@@ -0,0 +1,77 @@
+// config.js — Quản lý credentials ~/.quickmagic/credentials.json (chmod 600, dir 700).
+// H5: ghi atomic temp→rename; env token thắng file (CI headless, chỉ đọc không ghi).
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+
+const QM_DIR = path.join(os.homedir(), '.quickmagic');
+const CRED_FILE = path.join(QM_DIR, 'credentials.json');
+const LOCK_FILE = path.join(QM_DIR, 'refresh.lock');
+// URL GỐC (root) — REST base = + '/public/v1'; discovery OAuth cũng ở root.
+const DEFAULT_API_URL = process.env.QUICKMAGIC_URL || 'https://api.quickmagic.vn';
+
+// H5 — CI headless: env token thắng file (bỏ qua browser login). Chỉ đọc, KHÔNG ghi xuống đĩa.
+function getEnvCreds() {
+  const access_token = process.env.QUICKMAGIC_TOKEN;
+  const refresh_token = process.env.QUICKMAGIC_REFRESH_TOKEN;
+  if (!access_token && !refresh_token) return null;
+  return {
+    api_url: DEFAULT_API_URL,
+    access_token: access_token || null,
+    refresh_token: refresh_token || null,
+    expires_at: 0,
+    _from_env: true,
+  };
+}
+
+// Đọc credentials: ưu tiên env (CI) → file JSON. Trả null nếu chưa có.
+function load() {
+  const env_creds = getEnvCreds();
+  if (env_creds) return env_creds;
+  try {
+    return JSON.parse(fs.readFileSync(CRED_FILE, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Ghi credentials an toàn: temp→rename atomic, quyền 600 (dir 700). Bỏ qua khi chạy bằng env.
+function save(creds) {
+  if (creds && creds._from_env) return; // không ghi đè xuống đĩa khi chạy bằng env token
+  fs.mkdirSync(QM_DIR, { recursive: true, mode: 0o700 });
+  const tmp_file = `${CRED_FILE}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp_file, JSON.stringify(creds, null, 2), { mode: 0o600 });
+  fs.renameSync(tmp_file, CRED_FILE); // H5 — atomic, tránh corrupt JSON khi crash giữa write
+  fs.chmodSync(CRED_FILE, 0o600);
+}
+
+// Xoá credentials (logout). Bỏ qua nếu file không tồn tại.
+function clear() {
+  try {
+    fs.unlinkSync(CRED_FILE);
+  } catch {
+    // đã xoá hoặc chưa tồn tại — bỏ qua
+  }
+}
+
+// Xác định api_url: cờ CLI → file → mặc định.
+function apiUrl(flag) {
+  return flag || load()?.api_url || DEFAULT_API_URL;
+}
+
+// C1 — REST base = root + /public/v1 (KHÔNG /v1). Discovery OAuth vẫn ở root.
+function restBase(api_url) {
+  return `${api_url}/public/v1`;
+}
+
+module.exports = {
+  load,
+  save,
+  clear,
+  apiUrl,
+  restBase,
+  CRED_FILE,
+  LOCK_FILE,
+  QM_DIR,
+  DEFAULT_API_URL,
+};

package/src/index.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+// index.js — điểm vào CLI quickmagic (commander wiring). Node >=18, CommonJS.
+const { program } = require('commander');
+
+const auth = require('./commands/auth');
+const generate = require('./commands/generate');
+const jobs = require('./commands/jobs');
+const models = require('./commands/models');
+const credits = require('./commands/credits');
+const tools = require('./commands/tools');
+
+const collect = (v, acc) => { acc.push(v); return acc; };
+
+program
+  .name('quickmagic')
+  .description('Quick Magic CLI — tạo ảnh/video AI qua REST API (OAuth PKCE)')
+  .version('1.0.0');
+
+// ── auth ─────────────────────────────────────────────────────────────────────
+const auth_cmd = program.command('auth').description('Đăng nhập / đăng xuất / trạng thái');
+auth_cmd
+  .command('login')
+  .description('Đăng nhập qua trình duyệt (OAuth PKCE)')
+  .option('--api-url <url>', 'URL gốc API (mặc định https://api.quickmagic.vn)')
+  .action(auth.login);
+auth_cmd.command('logout').description('Đăng xuất, xoá credentials').action(auth.logout);
+auth_cmd.command('status').description('Xem email / số dư').action(auth.status);
+
+// ── generate ─────────────────────────────────────────────────────────────────
+const gen_cmd = program.command('generate').description('Tạo ảnh / video AI');
+gen_cmd
+  .command('image')
+  .description('Tạo ảnh AI')
+  .requiredOption('--prompt <p>', 'Mô tả ảnh')
+  .option('--model <m>', 'Model', 'qimi_3')
+  .option('--quality <q>', 'Chất lượng')
+  .option('--aspect-ratio <r>', 'Tỉ lệ khung (vd 1:1, 16:9)')
+  .option('--n <n>', 'Số ảnh', '1')
+  .option('--ref <r...>', 'Ảnh tham chiếu (URL hoặc file local, lặp nhiều lần)')
+  .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.image);
+gen_cmd
+  .command('video')
+  .description('Tạo video AI')
+  .requiredOption('--prompt <p>', 'Mô tả video')
+  .requiredOption('--model <m>', 'Model')
+  .option('--duration <d>', 'Thời lượng (giây)')
+  .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('--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);
+
+// ── 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);
+jobs_cmd
+  .command('wait <id>')
+  .description('Chờ job tới khi hoàn tất')
+  .option('--out <dir>', 'Thư mục lưu kết quả')
+  .action((id, options) => jobs.wait(id, options));
+
+// ── models ───────────────────────────────────────────────────────────────────
+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')
+  .action(models.list);
+
+// ── credits ──────────────────────────────────────────────────────────────────
+program.command('credits').description('Xem số dư credit').action(credits.show);
+
+// ── Nhập liệu (không tốn credit) ───────────────────────────────────────────────
+program.command('scrape <url>').description('Quét ảnh + tên sản phẩm từ link trang').action(tools.scrape);
+program.command('import <url>').description('Nhập ảnh/video từ POST TikTok/Instagram')
+  .option('--media <m>', 'image | video', 'image').option('--max <n>', 'Số ảnh tối đa').action(tools.importSocial);
+program.command('assets <kind>').description('Liệt kê tài sản: products | outfits | kols')
+  .option('--limit <n>', 'Giới hạn').action(tools.assets);
+program.command('analyze <video_url>').description('Phân tích video quảng cáo → kịch bản (15cr)')
+  .option('--product-id <id>', 'Sản phẩm trong tủ').action(tools.analyze);
+
+// ── Marketing ──────────────────────────────────────────────────────────────────
+const mkt = program.command('marketing').description('Marketing video');
+mkt.command('modes').description('Liệt kê mode + bảng giá theo duration').action(tools.marketingModes);
+mkt.command('video').description('Tạo video marketing (tốn credit theo duration)')
+  .requiredOption('--mode <id>', 'mode_id (xem marketing modes)')
+  .option('--product-id <id>').option('--avatar-id <id>').option('--avatar-kind <k>')
+  .option('--duration <d>', '8/10/12/15').option('--aspect-ratio <r>').option('--crid <id>', 'client_request_id')
+  .action(tools.marketingVideo);
+
+// ── Product / Fashion ──────────────────────────────────────────────────────────
+program.command('product').description('Tạo ảnh sản phẩm AI')
+  .requiredOption('--refs <r...>', 'product_id hoặc URL/base64 (1-3)')
+  .option('--types <t...>', 'product|poster|infographic|composite', ['product'])
+  .option('--count <n>').option('--kol-id <id>').option('--instruction <s>').option('--model <m>').option('--crid <id>')
+  .action(tools.product);
+program.command('fashion').description('Tạo ảnh thời trang AI')
+  .requiredOption('--outfit <id...>', 'outfit_ids (xem assets outfits)')
+  .option('--mode <m>', 'kol_outfit/outfit_only/...').option('--kol-kind <k>').option('--kol-id <id>').option('--model <m>').option('--crid <id>')
+  .action(tools.fashion);
+
+// ── Ảnh ────────────────────────────────────────────────────────────────────────
+program.command('edit <image>').description('Sửa ảnh: restore/upscale/beauty/muscle/color_boost')
+  .requiredOption('--tool <t>').option('--model <m>', 'qimi_2.5|qimi_3', 'qimi_3')
+  .option('--upscale-target <t>', '2k|4k').option('--style <s...>').option('--crid <id>').action(tools.edit);
+program.command('tryon').description('Thử đồ ảo (virtual try-on)')
+  .requiredOption('--model-image <img>', 'Ảnh người mẫu (URL/base64)')
+  .option('--type <t>', 'full|upper', 'full').option('--model <m>', 'qimi_1.5|qimi_2.5|qimi_3', 'qimi_3')
+  .option('--garment <img>').option('--upper <img>').option('--lower <img>').option('--background <img>').option('--prompt <p>').option('--crid <id>')
+  .action((o) => tools.tryon({ ...o, model_image: o.modelImage }));
+
+// ── Video nặng / audio ─────────────────────────────────────────────────────────
+program.command('stt <audio_url>').description('Chuyển giọng nói → văn bản')
+  .option('--translate <lang>', 'Dịch sang ngôn ngữ').option('--crid <id>').action(tools.stt);
+program.command('subtitle <video_url>').description('Thêm phụ đề (tùy chọn lồng tiếng)')
+  .option('--dub', 'Bật lồng tiếng').option('--translate <lang>').option('--crid <id>').action(tools.subtitle);
+program.command('split <video_url>').description('Cắt video dài → clip ngắn')
+  .option('--mode <m>', 'auto|specific', 'auto').option('--title-lang <l>').option('--translate <lang>').option('--crid <id>').action(tools.split);
+program.command('motion <video_url>').description('Áp chuyển động video vào ảnh (Kling)')
+  .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);
+
+// ── 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')
+  .option('--ref <r...>', 'Ảnh tham chiếu (URL hoặc data:base64, tối đa 5, lặp nhiều lần)')
+  .option('--prompt <p>', 'Mô tả ảnh (bắt buộc khi --operation generate)')
+  .option('--model <m>', 'Model (xem qm models --type image)', 'nano-banana-2')
+  .option('--aspect-ratio <r>').option('--quality <q>')
+  .option('--n <n>', 'Số ảnh', '1')
+  .option('--no-transparent-bg', 'Giữ nguyên nền gốc (chỉ operation=remix_describe)')
+  .option('--crid <id>', 'client_request_id')
+  .action(tools.cutout);
+
+// ── Hook Studio ──────────────────────────────────────────────────────────────
+const hook_cmd = program.command('hook').description('Hook Studio — video quảng cáo hài từ ảnh nhân vật + sản phẩm');
+hook_cmd.command('presets').description('Liệt kê preset + option hợp lệ + giá').action(tools.hookPresets);
+hook_cmd
+  .command('video')
+  .description('Tạo video hook (tốn credit theo preset)')
+  .requiredOption('--preset <id>', 'preset_id (xem hook presets)')
+  .requiredOption('--character <img>', 'Ảnh nhân vật (URL hoặc data:base64)')
+  .requiredOption('--product <img>', 'Ảnh sản phẩm (URL hoặc data:base64)')
+  .option('--aspect <r>', '9:16|16:9', '9:16')
+  .option('--speech-lang <l>', 'Ngôn ngữ thoại (xem hook presets speech_lang_options)', 'vi')
+  .option('--cta <s>', 'Call-to-action tuỳ chỉnh')
+  .option('--location <img>', 'Ảnh bối cảnh (tuỳ chọn)')
+  .option('--accessory <img>', 'Ảnh phụ kiện (tuỳ chọn)')
+  .option('--style <s>', 'Phong cách hài (xem hook presets style_options)')
+  .option('--format <f>', 'Định dạng (xem hook presets format_options)')
+  .option('--resolution <r>', '720p|1080p')
+  .option('--crid <id>', 'client_request_id')
+  .action(tools.hookVideo);
+
+program.parseAsync(process.argv).catch((e) => {
+  console.error('Lỗi:', e.message);
+  process.exit(1);
+});