museav-cli 2.0.0 → 2.1.0

package/README.md

@@ -162,6 +162,16 @@ museav gen --prompt '...' --quality high
 # 图生图（自动上传垫图，保持人物面容）
 museav gen --prompt '保持面容，换成西装' --ref face.png
 
+# 透明背景 PNG（抠掉背景，出带 alpha 通道的图；可与 --ref 叠加）
+museav gen --prompt '一只橘猫，产品级抠图' --transparent
+museav gen --prompt '把这只鞋抠成透明底' --ref shoe.jpg --transparent
+# 注意三件事：
+#   · 只在提示词里写 "transparent background" 没用——那是构图描述，不是抠图开关，
+#     真正生效的是 --transparent（它对应上游的 background 参数）
+#   · 仅部分上游支持。没有可用上游时中台直接报错，不会悄悄给你一张白底图
+#     （白底图看起来完全正常，静默降级只会让你以为提示词没写对，反复重试）
+#   · 会强制 PNG 输出：JPEG / 有损 WebP 没有 alpha 通道，装不下透明
+
 # 文生视频（模型如 seedance-2-fast / artsdance-2-0-pro-260801，自动轮询直到完成）
 museav gen --video --prompt '一只橘猫在窗台上伸懒腰，阳光洒进来，电影感' --model seedance-2-fast --ratio 9:16
 

package/dist/client.d.ts

@@ -19,7 +19,18 @@ export interface GenerateOptions {
     ratio?: string;
     model?: string;
     reference_image?: string;
+    /** 多张参考图，顺序即提示词里的「图片1、图片2…」；中台按序喂给模型 */
+    reference_images?: string[];
     quality?: 'low' | 'medium' | 'high';
+    /**
+     * 出图背景。transparent = 抠掉背景出带 alpha 通道的 PNG；opaque = 明确要不透明背景；
+     * 不传 = 沿用上游默认（白底）。
+     *
+     * 跟上游 gpt-image 的参数同名同值，中台不做翻译。两个约束由中台强制、CLI 不重复实现：
+     *   · 透明背景强制 PNG 输出（JPEG/有损 WebP 没有 alpha 通道）
+     *   · 只派给声明了该能力的上游；一家都没有时返回 400 说明原因，**不会静默出白底图**
+     */
+    background?: 'transparent' | 'opaque';
 }
 /** 图片/文字模板清单项（GET /api/templates，template_type=image|article） */
 export interface TemplateOption {
@@ -347,6 +358,10 @@ export declare class StudioClient {
      * 分类型限大小——图片 8MB / 音频 20MB / 视频 50MB。认不出类型直接 400。
      * 同一归属每小时 120 个的防滥用刹车在服务端，超了返回 429。
      */
+    /**
+     * 上传素材。图片会先压到视觉模型够用的尺寸再传（见 compress.ts）——
+     * 参考图是给模型看的，不是留档，原图直传只会拖慢上传和解析。
+     */
     uploadRef(filePath: string): Promise<{
         url: string;
         media_type?: string;

package/dist/client.js

@@ -10,6 +10,7 @@
  */
 import { readFileSync } from 'node:fs';
 import { basename } from 'node:path';
+import { compressForVision } from './compress.js';
 /**
  * 客户端自报身份 —— 中台靠它把 gen_jobs.channel 记成 'cli'，报错告警也靠它定位调用方。
  *
@@ -141,8 +142,13 @@ export class StudioClient {
             body.model = opts.model;
         if (opts.reference_image)
             body.reference_image = opts.reference_image;
+        // 单双字段一起发：中台优先取复数、为空才回落单数，两个都带着更稳
+        if (opts.reference_images?.length)
+            body.reference_images = opts.reference_images;
         if (opts.quality)
             body.quality = opts.quality;
+        if (opts.background)
+            body.background = opts.background;
         const r = await this.request('generate', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
@@ -240,7 +246,7 @@ export class StudioClient {
      */
     async reverse(input) {
         if (input.file) {
-            return this.request('reverse', { method: 'POST', body: fileForm(input.file) });
+            return this.request('reverse', { method: 'POST', body: await fileForm(input.file) });
         }
         return this.request('reverse', {
             method: 'POST',
@@ -255,8 +261,12 @@ export class StudioClient {
      * 分类型限大小——图片 8MB / 音频 20MB / 视频 50MB。认不出类型直接 400。
      * 同一归属每小时 120 个的防滥用刹车在服务端，超了返回 429。
      */
+    /**
+     * 上传素材。图片会先压到视觉模型够用的尺寸再传（见 compress.ts）——
+     * 参考图是给模型看的，不是留档，原图直传只会拖慢上传和解析。
+     */
     async uploadRef(filePath) {
-        const r = await this.request('upload-ref', { method: 'POST', body: fileForm(filePath) });
+        const r = await this.request('upload-ref', { method: 'POST', body: await fileForm(filePath) });
         return { url: r.url, media_type: r.media_type, mime: r.mime };
     }
     /**
@@ -274,7 +284,7 @@ export class StudioClient {
         if (file) {
             // multipart 分支：中台 formOptions() 对这几个键做 JSON.parse（variables 还支持逗号分隔），
             // 所以对象/数组要自己序列化成字符串，不能直接塞进 FormData。
-            const fd = fileForm(file);
+            const fd = await fileForm(file);
             if (variables?.length)
                 fd.append('variables', JSON.stringify(variables));
             if (variableLabels)
@@ -358,9 +368,19 @@ function sleep(ms) {
  * 带上原文件名：中台判类型靠字节魔数不靠这个，但文件名会进日志/对象存储的排查线索，
  * 匿名的 "blob" 出问题时谁也认不出是哪张图。故意不设 MIME——声明的 MIME 中台本来就不信。
  */
-function fileForm(filePath) {
+/**
+ * 所有 multipart 上传的唯一入口，内置参考图压缩（见 compress.ts）。
+ * 压缩放这里而不是各调用点：uploadRef / reverse / image-to-template 都走它，
+ * 加在调用点就会漏——2026-08-16 就漏过 image-to-template，4.1MB 原图直传把任务拖挂了。
+ */
+async function fileForm(filePath) {
+    const { buffer, filename, note } = await compressForVision(filePath);
+    if (note)
+        process.stderr.write(`  ${note}\n`);
     const fd = new FormData();
-    fd.append('file', new Blob([readFileSync(filePath)]), basename(filePath));
+    // Buffer → Uint8Array：Blob 的类型签名不收 Buffer（它可能背靠 SharedArrayBuffer）
+    const blob = buffer ? new Blob([new Uint8Array(buffer)]) : new Blob([new Uint8Array(readFileSync(filePath))]);
+    fd.append('file', blob, buffer ? filename : basename(filePath));
     return fd;
 }
 /**

package/dist/commands/gen.d.ts

@@ -9,7 +9,8 @@ export declare function gen(client: StudioClient, opts: {
     ratio?: string;
     model?: string;
     quality?: string;
-    ref?: string;
+    ref?: string[];
+    transparent?: boolean;
     video?: boolean;
     duration?: number;
     image?: string;

package/dist/commands/gen.js

@@ -1,3 +1,5 @@
+/** 与中台/各租户后台口径一致：一次最多 5 张参考图 */
+const MAX_REFS = 5;
 export async function gen(client, opts) {
     // prompt / skill / template 三选一。commander 不好表达互斥，在这里校验，报错要说清怎么改
     const picked = [opts.prompt, opts.skill, opts.template].filter(Boolean).length;
@@ -16,6 +18,10 @@ export async function gen(client, opts) {
     if (opts.video && opts.skill) {
         throw new Error('--video 暂不支持配合 --skill（视频模板走 --template 或直接 --prompt）');
     }
+    // 视频没有 alpha 通道这回事（mp4 不带透明），本地就拦掉，别让用户等一趟往返才知道
+    if (opts.video && opts.transparent) {
+        throw new Error('--transparent 仅图片出图支持：视频输出是 mp4，没有 alpha 通道');
+    }
     let templateFields;
     if (opts.fields) {
         try {
@@ -25,14 +31,26 @@ export async function gen(client, opts) {
             throw new Error(`--fields 必须是合法 JSON 对象，如 '{"artist":"王嘉尔","city":"南京"}'，收到: ${opts.fields}`);
         }
     }
-    // 可选：先上传垫图（图片出图 --ref / 视频图生视频 --image 都走这里）
+    // 可选：先上传垫图（图片出图 --ref 可给多张 / 视频图生视频 --image 单张）
+    //
+    // 顺序有语义：中台把数组按序喂给模型，提示词里写「参考图片1的排版、用图片2当背景」
+    // 时，图片N 对应的就是这里的第 N 个 --ref。所以上传要顺序执行、不能并发抢跑。
     let referenceImage;
-    const refPath = opts.ref || opts.image;
-    if (refPath) {
-        process.stderr.write(`上传垫图 ${refPath} ...\n`);
-        const up = await client.uploadRef(refPath);
-        referenceImage = up.url;
-        process.stderr.write(`垫图就绪: ${referenceImage}\n`);
+    let referenceImages;
+    const refPaths = [...(opts.ref || []), ...(opts.image ? [opts.image] : [])];
+    if (refPaths.length > MAX_REFS) {
+        throw new Error(`参考图最多 ${MAX_REFS} 张，收到 ${refPaths.length} 张`);
+    }
+    if (refPaths.length) {
+        const urls = [];
+        for (const [i, refPath] of refPaths.entries()) {
+            process.stderr.write(`上传垫图 [图片${i + 1}] ${refPath} ...\n`);
+            const up = await client.uploadRef(refPath);
+            urls.push(up.url);
+            process.stderr.write(`  图片${i + 1} 就绪: ${up.url}\n`);
+        }
+        referenceImage = urls[0]; // 兼容：中台单数字段仍收
+        referenceImages = urls.length > 1 ? urls : undefined;
     }
     // ── 视频模式：走 /api/videos 独立链路 ──
     if (opts.video) {
@@ -78,6 +96,10 @@ export async function gen(client, opts) {
         model: opts.model,
         quality: opts.quality,
         reference_image: referenceImage,
+        reference_images: referenceImages,
+        // 开关 → 枚举：CLI 这层用布尔开关最顺手，中台契约是 background: transparent|opaque
+        // （跟上游 gpt-image 的参数同名同值）。不传就不发，行为跟以前完全一样。
+        background: opts.transparent ? 'transparent' : undefined,
     }, (status) => {
         if (status === 'processing')
             process.stderr.write('生成中...\r');

package/dist/compress.d.ts

@@ -0,0 +1,13 @@
+export interface CompressResult {
+    /** 要上传的数据；未压缩时为 null，表示用原文件 */
+    buffer: Buffer | null;
+    /** 上传时用的文件名（转了格式要换扩展名） */
+    filename: string;
+    /** 给人看的一行说明，未压缩时为空 */
+    note: string;
+}
+/**
+ * @param filePath 本地图片路径
+ * @returns 压缩结果；非图片、体积已达标、或 sharp 不可用时 buffer 为 null
+ */
+export declare function compressForVision(filePath: string): Promise<CompressResult>;

package/dist/compress.js

@@ -0,0 +1,97 @@
+/**
+ * 参考图压缩 —— 上传前把图缩到视觉模型够用的尺寸。
+ *
+ * 参考图的用途是「让模型看懂画面」，不是留档，不需要原始分辨率。实测 4.1MB 的海报
+ * 直接传上去，中台那次图生模板任务卡在「解析图片」再没回来（后台任务被 Cloudflare
+ * 掐掉，任务永远 pending）。50MB 的图更不用说。
+ *
+ * sharp 是 optionalDependency：原生模块在个别平台会装不上，装不上也不能让整个 CLI
+ * 用不了。取不到就原样上传并提示——压缩是优化，不是前置条件。
+ */
+import { stat } from 'node:fs/promises';
+import { basename } from 'node:path';
+/** 长边上限：主流视觉模型的有效输入分辨率都在 1.5k 上下，再大只是浪费带宽和解析时间 */
+const MAX_EDGE = 1568;
+/** 小于这个体积且尺寸不超标就原样传，不折腾 */
+const SKIP_BELOW_BYTES = 900 * 1024;
+/** 压完仍超过它就再降一档质量 */
+const TARGET_BYTES = 1.5 * 1024 * 1024;
+async function loadSharp() {
+    try {
+        const m = await import('sharp');
+        return m.default ?? m;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * @param filePath 本地图片路径
+ * @returns 压缩结果；非图片、体积已达标、或 sharp 不可用时 buffer 为 null
+ */
+export async function compressForVision(filePath) {
+    const name = basename(filePath);
+    const orig = (await stat(filePath)).size;
+    const sharp = await loadSharp();
+    if (!sharp) {
+        return {
+            buffer: null,
+            filename: name,
+            note: orig > SKIP_BELOW_BYTES
+                ? `未安装 sharp，${(orig / 1024 / 1024).toFixed(1)}MB 原图直传（大图可能导致解析超时）`
+                : '',
+        };
+    }
+    let meta;
+    try {
+        meta = await sharp(filePath).metadata();
+    }
+    catch {
+        return { buffer: null, filename: name, note: '' }; // 不是 sharp 认识的图（视频/音频）→ 原样传
+    }
+    const longEdge = Math.max(meta.width || 0, meta.height || 0);
+    if (orig <= SKIP_BELOW_BYTES && longEdge <= MAX_EDGE) {
+        return { buffer: null, filename: name, note: '' };
+    }
+    // 有 alpha 的保持 PNG（贴图类素材的透明通道不能丢），其余一律转 JPEG——
+    // 同样画质下 JPEG 比 PNG 小一个数量级，而参考图不需要无损。
+    //
+    // 只看 meta.hasAlpha 不够：截图工具产出的 PNG 普遍带一条**全不透明**的 alpha 通道，
+    // 照着它走 PNG 分支等于白白多存几倍体积（实测 4.1MB 海报按 PNG 只压到 1.16MB，
+    // 按 JPEG 是 0.2MB）。用 stats().isOpaque 判断透明通道有没有被真正用到。
+    let hasAlpha = !!meta.hasAlpha;
+    if (hasAlpha) {
+        try {
+            const st = await sharp(filePath).stats();
+            if (st.isOpaque)
+                hasAlpha = false;
+        }
+        catch { /* 统计失败就按有 alpha 保守处理 */ }
+    }
+    const pipeline = sharp(filePath).rotate() // rotate() 不带参数=按 EXIF 摆正，否则手机竖拍图会躺着
+        .resize({ width: MAX_EDGE, height: MAX_EDGE, fit: 'inside', withoutEnlargement: true });
+    let out;
+    let ext;
+    if (hasAlpha) {
+        out = await pipeline.png({ compressionLevel: 9, palette: true }).toBuffer();
+        ext = 'png';
+    }
+    else {
+        out = await pipeline.jpeg({ quality: 82, mozjpeg: true }).toBuffer();
+        ext = 'jpg';
+        if (out.byteLength > TARGET_BYTES) {
+            out = await sharp(filePath).rotate()
+                .resize({ width: MAX_EDGE, height: MAX_EDGE, fit: 'inside', withoutEnlargement: true })
+                .jpeg({ quality: 68, mozjpeg: true }).toBuffer();
+        }
+    }
+    // 压完反而更大（本来就是小图/高压缩率的 WebP 之类）就别换了
+    if (out.byteLength >= orig)
+        return { buffer: null, filename: name, note: '' };
+    const pct = Math.round((1 - out.byteLength / orig) * 100);
+    return {
+        buffer: out,
+        filename: name.replace(/\.[^.]+$/, '') + '.' + ext,
+        note: `已压缩 ${(orig / 1024 / 1024).toFixed(1)}MB → ${(out.byteLength / 1024 / 1024).toFixed(2)}MB（-${pct}%，长边 ≤ ${MAX_EDGE}px）`,
+    };
+}

package/dist/index.js

@@ -127,7 +127,12 @@ program
     .option('-r, --ratio <ratio>', '宽高比: 3:4 / 9:16 / 1:1 / 4:3 / 16:9（不指定则用技能/模板自己的比例，纯 prompt 模式兜底 3:4）')
     .option('-m, --model <name>', '指定模型，如 gpt-image-2 / seedance-2-fast / artsdance-2-0-pro-260801')
     .option('-q, --quality <level>', '质量: low / medium / high（仅 gpt-image）')
-    .option('--ref <file>', '垫图文件路径（图片图生图，自动上传）')
+    // 可重复：--ref 正面.jpg --ref 背景.jpg。顺序即语义——提示词里写「参考图片1的排版、
+    // 用图片2作为背景」时，图片N 对应第 N 个 --ref。commander 的 collect 保证顺序。
+    .option('--ref <file>', '垫图文件路径，可重复传多张（最多 5 张，顺序对应提示词里的「图片1、图片2…」）', (v, acc) => [...acc, v], [])
+    // 透明背景是上游的 background 参数，不是提示词能表达的东西——提示词里写
+    // "transparent background" 只是在描述构图，模型照样铺一层白底。这个开关才是抠图开关。
+    .option('--transparent', '透明背景 PNG（抠掉背景，带 alpha 通道）。仅部分上游支持，不支持时中台明确报错、不会悄悄给白底图；服务端自动强制 PNG 输出（JPEG 没有 alpha 通道）')
     .option('--video', '生成视频（走 /api/videos 链路，模型如 seedance-2-fast / artsdance-2-0-pro）')
     .option('--duration <sec>', '视频时长（秒，仅 --video；由模型与上游支持范围决定）', (v) => Number(v))
     .option('--image <file>', '图生视频首帧图（仅 --video，自动上传）')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "museav-cli",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "MUSE AV 出图中台官方 CLI —— 命令行调中台 API 出图、出视频、读图逆向、图生模板",
   "type": "module",
   "bin": {
@@ -51,5 +51,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "optionalDependencies": {
+    "sharp": "^0.35.3"
   }
 }

package/src/client.ts

@@ -10,6 +10,7 @@
  */
 import { readFileSync } from 'node:fs'
 import { basename } from 'node:path'
+import { compressForVision } from './compress.js'
 
 /**
  * 客户端自报身份 —— 中台靠它把 gen_jobs.channel 记成 'cli'，报错告警也靠它定位调用方。
@@ -67,7 +68,18 @@ export interface GenerateOptions {
   ratio?: string
   model?: string
   reference_image?: string
+  /** 多张参考图，顺序即提示词里的「图片1、图片2…」；中台按序喂给模型 */
+  reference_images?: string[]
   quality?: 'low' | 'medium' | 'high'
+  /**
+   * 出图背景。transparent = 抠掉背景出带 alpha 通道的 PNG；opaque = 明确要不透明背景；
+   * 不传 = 沿用上游默认（白底）。
+   *
+   * 跟上游 gpt-image 的参数同名同值，中台不做翻译。两个约束由中台强制、CLI 不重复实现：
+   *   · 透明背景强制 PNG 输出（JPEG/有损 WebP 没有 alpha 通道）
+   *   · 只派给声明了该能力的上游；一家都没有时返回 400 说明原因，**不会静默出白底图**
+   */
+  background?: 'transparent' | 'opaque'
 }
 
 /** 图片/文字模板清单项（GET /api/templates，template_type=image|article） */
@@ -389,7 +401,10 @@ export class StudioClient {
     if (opts.ratio) body.ratio = opts.ratio
     if (opts.model) body.model = opts.model
     if (opts.reference_image) body.reference_image = opts.reference_image
+    // 单双字段一起发：中台优先取复数、为空才回落单数，两个都带着更稳
+    if (opts.reference_images?.length) body.reference_images = opts.reference_images
     if (opts.quality) body.quality = opts.quality
+    if (opts.background) body.background = opts.background
     const r = await this.request('generate', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
@@ -500,7 +515,7 @@ export class StudioClient {
    */
   async reverse(input: { file?: string; imageUrl?: string }): Promise<ReverseResult> {
     if (input.file) {
-      return this.request('reverse', { method: 'POST', body: fileForm(input.file) })
+      return this.request('reverse', { method: 'POST', body: await fileForm(input.file) })
     }
     return this.request('reverse', {
       method: 'POST',
@@ -516,8 +531,12 @@ export class StudioClient {
    * 分类型限大小——图片 8MB / 音频 20MB / 视频 50MB。认不出类型直接 400。
    * 同一归属每小时 120 个的防滥用刹车在服务端，超了返回 429。
    */
+  /**
+   * 上传素材。图片会先压到视觉模型够用的尺寸再传（见 compress.ts）——
+   * 参考图是给模型看的，不是留档，原图直传只会拖慢上传和解析。
+   */
   async uploadRef(filePath: string): Promise<{ url: string; media_type?: string; mime?: string }> {
-    const r = await this.request('upload-ref', { method: 'POST', body: fileForm(filePath) })
+    const r = await this.request('upload-ref', { method: 'POST', body: await fileForm(filePath) })
     return { url: r.url, media_type: r.media_type, mime: r.mime }
   }
 
@@ -536,7 +555,7 @@ export class StudioClient {
     if (file) {
       // multipart 分支：中台 formOptions() 对这几个键做 JSON.parse（variables 还支持逗号分隔），
       // 所以对象/数组要自己序列化成字符串，不能直接塞进 FormData。
-      const fd = fileForm(file)
+      const fd = await fileForm(file)
       if (variables?.length) fd.append('variables', JSON.stringify(variables))
       if (variableLabels) fd.append('variable_labels', JSON.stringify(variableLabels))
       if (createTemplate) fd.append('create_template', 'true')
@@ -621,9 +640,18 @@ function sleep(ms: number): Promise<void> {
  * 带上原文件名：中台判类型靠字节魔数不靠这个，但文件名会进日志/对象存储的排查线索，
  * 匿名的 "blob" 出问题时谁也认不出是哪张图。故意不设 MIME——声明的 MIME 中台本来就不信。
  */
-function fileForm(filePath: string): FormData {
+/**
+ * 所有 multipart 上传的唯一入口，内置参考图压缩（见 compress.ts）。
+ * 压缩放这里而不是各调用点：uploadRef / reverse / image-to-template 都走它，
+ * 加在调用点就会漏——2026-08-16 就漏过 image-to-template，4.1MB 原图直传把任务拖挂了。
+ */
+async function fileForm(filePath: string): Promise<FormData> {
+  const { buffer, filename, note } = await compressForVision(filePath)
+  if (note) process.stderr.write(`  ${note}\n`)
   const fd = new FormData()
-  fd.append('file', new Blob([readFileSync(filePath)]), basename(filePath))
+  // Buffer → Uint8Array：Blob 的类型签名不收 Buffer（它可能背靠 SharedArrayBuffer）
+  const blob = buffer ? new Blob([new Uint8Array(buffer)]) : new Blob([new Uint8Array(readFileSync(filePath))])
+  fd.append('file', blob, buffer ? filename : basename(filePath))
   return fd
 }
 

package/src/commands/gen.ts

@@ -1,6 +1,9 @@
 /** museav gen —— 出图 / 出视频（核心命令） */
 import type { StudioClient } from '../client.js'
 
+/** 与中台/各租户后台口径一致：一次最多 5 张参考图 */
+const MAX_REFS = 5
+
 export async function gen(client: StudioClient, opts: {
   prompt?: string
   skill?: string
@@ -10,7 +13,8 @@ export async function gen(client: StudioClient, opts: {
   ratio?: string
   model?: string
   quality?: string
-  ref?: string
+  ref?: string[]      // 可重复：--ref a.jpg --ref b.jpg，顺序即「图片1、图片2…」
+  transparent?: boolean   // 透明背景 PNG；能不能做由中台按上游能力判定，做不了会明确报错
   // 视频
   video?: boolean
   duration?: number
@@ -33,6 +37,10 @@ export async function gen(client: StudioClient, opts: {
   if (opts.video && opts.skill) {
     throw new Error('--video 暂不支持配合 --skill（视频模板走 --template 或直接 --prompt）')
   }
+  // 视频没有 alpha 通道这回事（mp4 不带透明），本地就拦掉，别让用户等一趟往返才知道
+  if (opts.video && opts.transparent) {
+    throw new Error('--transparent 仅图片出图支持：视频输出是 mp4，没有 alpha 通道')
+  }
   let templateFields: Record<string, string> | undefined
   if (opts.fields) {
     try {
@@ -42,14 +50,26 @@ export async function gen(client: StudioClient, opts: {
     }
   }
 
-  // 可选：先上传垫图（图片出图 --ref / 视频图生视频 --image 都走这里）
+  // 可选：先上传垫图（图片出图 --ref 可给多张 / 视频图生视频 --image 单张）
+  //
+  // 顺序有语义：中台把数组按序喂给模型，提示词里写「参考图片1的排版、用图片2当背景」
+  // 时，图片N 对应的就是这里的第 N 个 --ref。所以上传要顺序执行、不能并发抢跑。
   let referenceImage: string | undefined
-  const refPath = opts.ref || opts.image
-  if (refPath) {
-    process.stderr.write(`上传垫图 ${refPath} ...\n`)
-    const up = await client.uploadRef(refPath)
-    referenceImage = up.url
-    process.stderr.write(`垫图就绪: ${referenceImage}\n`)
+  let referenceImages: string[] | undefined
+  const refPaths = [...(opts.ref || []), ...(opts.image ? [opts.image] : [])]
+  if (refPaths.length > MAX_REFS) {
+    throw new Error(`参考图最多 ${MAX_REFS} 张，收到 ${refPaths.length} 张`)
+  }
+  if (refPaths.length) {
+    const urls: string[] = []
+    for (const [i, refPath] of refPaths.entries()) {
+      process.stderr.write(`上传垫图 [图片${i + 1}] ${refPath} ...\n`)
+      const up = await client.uploadRef(refPath)
+      urls.push(up.url)
+      process.stderr.write(`  图片${i + 1} 就绪: ${up.url}\n`)
+    }
+    referenceImage = urls[0]                       // 兼容：中台单数字段仍收
+    referenceImages = urls.length > 1 ? urls : undefined
   }
 
   // ── 视频模式：走 /api/videos 独立链路 ──
@@ -99,6 +119,10 @@ export async function gen(client: StudioClient, opts: {
       model: opts.model,
       quality: opts.quality as 'low' | 'medium' | 'high' | undefined,
       reference_image: referenceImage,
+      reference_images: referenceImages,
+      // 开关 → 枚举：CLI 这层用布尔开关最顺手，中台契约是 background: transparent|opaque
+      // （跟上游 gpt-image 的参数同名同值）。不传就不发，行为跟以前完全一样。
+      background: opts.transparent ? 'transparent' : undefined,
     },
     (status) => {
       if (status === 'processing') process.stderr.write('生成中...\r')

package/src/compress.ts

@@ -0,0 +1,110 @@
+/**
+ * 参考图压缩 —— 上传前把图缩到视觉模型够用的尺寸。
+ *
+ * 参考图的用途是「让模型看懂画面」，不是留档，不需要原始分辨率。实测 4.1MB 的海报
+ * 直接传上去，中台那次图生模板任务卡在「解析图片」再没回来（后台任务被 Cloudflare
+ * 掐掉，任务永远 pending）。50MB 的图更不用说。
+ *
+ * sharp 是 optionalDependency：原生模块在个别平台会装不上，装不上也不能让整个 CLI
+ * 用不了。取不到就原样上传并提示——压缩是优化，不是前置条件。
+ */
+import { stat } from 'node:fs/promises'
+import { basename } from 'node:path'
+
+/** 长边上限：主流视觉模型的有效输入分辨率都在 1.5k 上下，再大只是浪费带宽和解析时间 */
+const MAX_EDGE = 1568
+/** 小于这个体积且尺寸不超标就原样传，不折腾 */
+const SKIP_BELOW_BYTES = 900 * 1024
+/** 压完仍超过它就再降一档质量 */
+const TARGET_BYTES = 1.5 * 1024 * 1024
+
+export interface CompressResult {
+  /** 要上传的数据；未压缩时为 null，表示用原文件 */
+  buffer: Buffer | null
+  /** 上传时用的文件名（转了格式要换扩展名） */
+  filename: string
+  /** 给人看的一行说明，未压缩时为空 */
+  note: string
+}
+
+async function loadSharp(): Promise<any | null> {
+  try {
+    const m = await import('sharp')
+    return (m as any).default ?? m
+  } catch {
+    return null
+  }
+}
+
+/**
+ * @param filePath 本地图片路径
+ * @returns 压缩结果；非图片、体积已达标、或 sharp 不可用时 buffer 为 null
+ */
+export async function compressForVision(filePath: string): Promise<CompressResult> {
+  const name = basename(filePath)
+  const orig = (await stat(filePath)).size
+
+  const sharp = await loadSharp()
+  if (!sharp) {
+    return {
+      buffer: null,
+      filename: name,
+      note: orig > SKIP_BELOW_BYTES
+        ? `未安装 sharp，${(orig / 1024 / 1024).toFixed(1)}MB 原图直传（大图可能导致解析超时）`
+        : '',
+    }
+  }
+
+  let meta
+  try {
+    meta = await sharp(filePath).metadata()
+  } catch {
+    return { buffer: null, filename: name, note: '' }   // 不是 sharp 认识的图（视频/音频）→ 原样传
+  }
+
+  const longEdge = Math.max(meta.width || 0, meta.height || 0)
+  if (orig <= SKIP_BELOW_BYTES && longEdge <= MAX_EDGE) {
+    return { buffer: null, filename: name, note: '' }
+  }
+
+  // 有 alpha 的保持 PNG（贴图类素材的透明通道不能丢），其余一律转 JPEG——
+  // 同样画质下 JPEG 比 PNG 小一个数量级，而参考图不需要无损。
+  //
+  // 只看 meta.hasAlpha 不够：截图工具产出的 PNG 普遍带一条**全不透明**的 alpha 通道，
+  // 照着它走 PNG 分支等于白白多存几倍体积（实测 4.1MB 海报按 PNG 只压到 1.16MB，
+  // 按 JPEG 是 0.2MB）。用 stats().isOpaque 判断透明通道有没有被真正用到。
+  let hasAlpha = !!meta.hasAlpha
+  if (hasAlpha) {
+    try {
+      const st = await sharp(filePath).stats()
+      if (st.isOpaque) hasAlpha = false
+    } catch { /* 统计失败就按有 alpha 保守处理 */ }
+  }
+  const pipeline = sharp(filePath).rotate()   // rotate() 不带参数=按 EXIF 摆正，否则手机竖拍图会躺着
+    .resize({ width: MAX_EDGE, height: MAX_EDGE, fit: 'inside', withoutEnlargement: true })
+
+  let out: Buffer
+  let ext: string
+  if (hasAlpha) {
+    out = await pipeline.png({ compressionLevel: 9, palette: true }).toBuffer()
+    ext = 'png'
+  } else {
+    out = await pipeline.jpeg({ quality: 82, mozjpeg: true }).toBuffer()
+    ext = 'jpg'
+    if (out.byteLength > TARGET_BYTES) {
+      out = await sharp(filePath).rotate()
+        .resize({ width: MAX_EDGE, height: MAX_EDGE, fit: 'inside', withoutEnlargement: true })
+        .jpeg({ quality: 68, mozjpeg: true }).toBuffer()
+    }
+  }
+
+  // 压完反而更大（本来就是小图/高压缩率的 WebP 之类）就别换了
+  if (out.byteLength >= orig) return { buffer: null, filename: name, note: '' }
+
+  const pct = Math.round((1 - out.byteLength / orig) * 100)
+  return {
+    buffer: out,
+    filename: name.replace(/\.[^.]+$/, '') + '.' + ext,
+    note: `已压缩 ${(orig / 1024 / 1024).toFixed(1)}MB → ${(out.byteLength / 1024 / 1024).toFixed(2)}MB（-${pct}%，长边 ≤ ${MAX_EDGE}px）`,
+  }
+}

package/src/index.ts

@@ -129,7 +129,13 @@ program
   .option('-r, --ratio <ratio>', '宽高比: 3:4 / 9:16 / 1:1 / 4:3 / 16:9（不指定则用技能/模板自己的比例，纯 prompt 模式兜底 3:4）')
   .option('-m, --model <name>', '指定模型，如 gpt-image-2 / seedance-2-fast / artsdance-2-0-pro-260801')
   .option('-q, --quality <level>', '质量: low / medium / high（仅 gpt-image）')
-  .option('--ref <file>', '垫图文件路径（图片图生图，自动上传）')
+  // 可重复：--ref 正面.jpg --ref 背景.jpg。顺序即语义——提示词里写「参考图片1的排版、
+  // 用图片2作为背景」时，图片N 对应第 N 个 --ref。commander 的 collect 保证顺序。
+  .option('--ref <file>', '垫图文件路径，可重复传多张（最多 5 张，顺序对应提示词里的「图片1、图片2…」）',
+    (v: string, acc: string[]) => [...acc, v], [] as string[])
+  // 透明背景是上游的 background 参数，不是提示词能表达的东西——提示词里写
+  // "transparent background" 只是在描述构图，模型照样铺一层白底。这个开关才是抠图开关。
+  .option('--transparent', '透明背景 PNG（抠掉背景，带 alpha 通道）。仅部分上游支持，不支持时中台明确报错、不会悄悄给白底图；服务端自动强制 PNG 输出（JPEG 没有 alpha 通道）')
   .option('--video', '生成视频（走 /api/videos 链路，模型如 seedance-2-fast / artsdance-2-0-pro）')
   .option('--duration <sec>', '视频时长（秒，仅 --video；由模型与上游支持范围决定）', (v) => Number(v))
   .option('--image <file>', '图生视频首帧图（仅 --video，自动上传）')