@genex-ai/cli-demo 1.34.3-dev.705 → 1.34.4-dev.706

package/README.md

@@ -18,6 +18,7 @@ genex texture "<prompt>"   # generate a texture   → prints an asset URL
 genex image "<prompt>"     # generate an image    → prints an asset URL
 genex video "<prompt>"     # generate a video     → prints an asset URL
 genex character "<brief>"  # generate 3 neutral-A-pose concept candidates
+genex character --image ./front.jpg --image ./back.jpg  # Meshy from your own views
 genex character preview <concept-id> --candidate 1 --user-approved
 genex character finalize <preview-id> --user-approved --approve-remesh 10000
 genex character animate <id> --action <action-id>  # add a same-rig Meshy action
@@ -164,6 +165,20 @@ one call (`image-main` + `image-alt-N` URLs) — pick the best instead of re-rol
 
 ## Meshy characters and animations
 
+Use your own reference images directly with Meshy:
+
+```bash
+genex character --image ./front.jpg --image ./back.jpg --texture 8k --polycount 100000 --pose t-pose --no-wait
+```
+
+Repeat `--image` for 1-4 PNG/JPEG views of the same character, one view per
+image. Local files may total up to 4 MB; Genex asset URLs are also accepted.
+This starts a one-shot rigged character, skipping concept generation. An
+optional brief labels the ledger entry; Meshy's image endpoints do not use it
+as text conditioning. `creature --image` works with the same references and
+keeps creature defaults (no controller pack). Do not combine `--image` with
+`--direct-text`, guided subcommands or their approval flags.
+
 The default Meshy lane is an approval-gated, three-command workflow through the
 same authenticated credit, BullMQ/Redis, and R2 generation pipeline:
 
@@ -187,8 +202,9 @@ horizontal root/hip translation may be normalized for Rapier ownership.
 `finalize`; requested actions run only after the controller pack succeeds.
 `--height` and `--no-wait` carry through the approval flow. The guided lane
 always installs neutral-v3. `genex character "<prompt>" --direct-text` is the
-explicit compatibility path; only that path accepts `--polycount` or
-`--no-controller-pack`, and its default polycount is also 10,000.
+explicit text-only compatibility path. Both one-shot paths (`--direct-text`
+and `--image`) accept `--polycount` and `--no-controller-pack`, with a default
+polycount of 10,000.
 
 Search before spending:
 

package/dist/index.js

@@ -8748,6 +8748,14 @@ function buildGenOptions(kind, opts) {
 }
 async function runGenerate(kind, opts) {
   const log = createLogger({ quiet: opts.quiet || opts.json });
+  if (kind === "model" && opts.imageUrls !== void 0) {
+    if (opts.imageUrls.length > 1) {
+      log.error("genex model accepts one --image reference. Use character --image for multiple character views.");
+      process.exitCode = 1;
+      return;
+    }
+    opts = { ...opts, imageUrl: opts.imageUrls[0] ?? opts.imageUrl };
+  }
   let typedPrompt = opts.prompt?.trim();
   if (!typedPrompt && kind === "model" && opts.imageUrl) {
     const ref = opts.imageUrl.startsWith("data:") ? "local image" : opts.imageUrl;
@@ -20079,6 +20087,7 @@ async function resolveAdoptTarget(selector) {
   return { ok: true, characterId, from: file };
 }
 async function runCharacterAdopt(opts) {
+  if (refuseSubcommandImages(opts)) return;
   const log = createLogger({ quiet: opts.quiet || opts.json });
   const target = await resolveAdoptTarget(opts.characterId);
   if (!target.ok) {
@@ -20139,6 +20148,7 @@ async function runCharacterAdopt(opts) {
   });
 }
 async function runCharacterImport(opts) {
+  if (refuseSubcommandImages(opts)) return;
   const log = createLogger({ quiet: opts.quiet || opts.json });
   const filePath = opts.importPath?.trim();
   if (!filePath) {
@@ -20215,17 +20225,67 @@ async function runCharacterImport(opts) {
   });
 }
 async function runCharacter(opts) {
+  const references = opts.imageUrls ?? (opts.imageUrl === void 0 ? [] : [opts.imageUrl]);
+  if (references.length > 0) {
+    if (opts.directText) {
+      fail2(opts, "--image cannot be combined with --direct-text. Omit --direct-text to build from the supplied references.");
+      return;
+    }
+    if (opts.candidate !== void 0 || opts.userApproved !== void 0 || opts.approveRemesh !== void 0) {
+      fail2(opts, "--image starts a one-shot character. --candidate / --user-approved / --approve-remesh belong to the guided preview/finalize flow; use --polycount for the reference character's face budget.");
+      return;
+    }
+    const prepared = await prepareCharacterImages(references);
+    if (!prepared.ok) {
+      fail2(opts, prepared.error);
+      return;
+    }
+    await runOneShotCharacter(opts, prepared.imageUrls);
+    return;
+  }
   if (opts.directText) {
-    await runDirectTextCharacter(opts);
+    await runOneShotCharacter(opts);
     return;
   }
   await runCharacterConcept(opts);
 }
+async function prepareCharacterImages(references) {
+  if (references.length > 4) return { ok: false, error: "--image accepts 1-4 references to the same character, one view per image." };
+  const imageUrls = [];
+  let inlineBytes = 0;
+  for (const reference of references) {
+    let image = reference.trim();
+    if (!image) return { ok: false, error: "--image needs a PNG/JPEG file or asset URL." };
+    if (!/^(https?:\/\/|data:)/i.test(image)) {
+      if (!/\.(png|jpe?g)$/i.test(image)) return { ok: false, error: "Character --image references must be PNG or JPEG files." };
+      const inlined = await inlineLocalImage(image, "--image");
+      if (!inlined.ok) return inlined;
+      image = inlined.dataUri;
+    }
+    if (/^data:/i.test(image)) {
+      const match = /^data:image\/(png|jpeg);base64,([A-Za-z0-9+/]+={0,2})$/.exec(image);
+      if (!match || match[2].length % 4 !== 0) return { ok: false, error: "Character --image data must be a base64 PNG or JPEG." };
+      const bytes = Buffer.from(match[2], "base64");
+      const isPng2 = bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]));
+      const isJpeg = bytes.length >= 3 && bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255;
+      if (!(match[1] === "png" ? isPng2 : isJpeg)) return { ok: false, error: "Character --image contents must match their PNG/JPEG format." };
+      inlineBytes += bytes.length;
+      if (inlineBytes > 4 * 1024 * 1024) return { ok: false, error: "--image references exceed the combined 4 MB inline limit. Compress them or use Genex asset URLs." };
+    }
+    imageUrls.push(image);
+  }
+  return { ok: true, imageUrls };
+}
 function fail2(opts, message, kind = "character") {
   if (opts.json) writeJson({ kind, status: "failed", error: message });
   else createLogger({ quiet: opts.quiet }).error(message);
   process.exitCode = 1;
 }
+function refuseSubcommandImages(opts) {
+  if (opts.imageUrl === void 0 && !opts.imageUrls?.length) return false;
+  fail2(opts, "--image starts a new reference character; it cannot be combined with a character subcommand.");
+  return true;
+}
 function requestedBuild(opts, actionIds) {
   return {
     actionIds,
@@ -20310,15 +20370,15 @@ async function runCharacterConcept(opts) {
     return;
   }
   if (opts.polycount !== void 0) {
-    fail2(opts, "--polycount is only available with --direct-text. The approval flow takes its face budget on `character finalize --approve-remesh <faces>`.", "character_concept");
+    fail2(opts, "--polycount is only available with --direct-text or --image. The approval flow takes its face budget on `character finalize --approve-remesh <faces>`.", "character_concept");
     return;
   }
   if (opts.texture !== void 0 || opts.ultra === false || opts.pose !== void 0) {
-    fail2(opts, "--texture / --no-ultra / --pose apply to the paid mesh call: pass them to `character preview` (guided) or `character --direct-text` / `creature` (one shot). Concepts are images.", "character_concept");
+    fail2(opts, "--texture / --no-ultra / --pose apply to the paid mesh call: pass them to `character preview` (guided) or `character --direct-text` / `character --image` / `creature` (one shot). Concepts are images.", "character_concept");
     return;
   }
   if (opts.controllerPack === false) {
-    fail2(opts, "--no-controller-pack is only available with --direct-text. The guided Meshy parity flow always installs neutral-v3.", "character_concept");
+    fail2(opts, "--no-controller-pack is only available with --direct-text or --image. The guided Meshy parity flow always installs neutral-v3.", "character_concept");
     return;
   }
   const resolved = resolveActionSelectors(opts.actions ?? []);
@@ -20363,13 +20423,26 @@ async function runCharacterConcept(opts) {
     })
   });
 }
-async function runDirectTextCharacter(opts) {
+async function runOneShotCharacter(opts, imageUrls) {
   const log = createLogger({ quiet: opts.quiet || opts.json });
-  const prompt = opts.prompt?.trim();
+  const prompt = opts.prompt?.trim() || (imageUrls ? "Character from supplied reference images" : void 0);
   if (!prompt) {
     fail2(opts, 'Missing prompt. Usage: genex character "<prompt>" --direct-text.');
     return;
   }
+  const badTexture = badCharacterTexture(opts);
+  if (badTexture) {
+    fail2(opts, badTexture);
+    return;
+  }
+  if (opts.polycount !== void 0 && (!Number.isInteger(opts.polycount) || opts.polycount < REMESH_TARGET_MIN || opts.polycount > REMESH_TARGET_MAX)) {
+    fail2(opts, `--polycount must be an integer between ${REMESH_TARGET_MIN} and ${REMESH_TARGET_MAX}.`);
+    return;
+  }
+  if (opts.pose !== void 0 && !["a-pose", "t-pose"].includes(opts.pose)) {
+    fail2(opts, "--pose must be a-pose or t-pose.");
+    return;
+  }
   const resolved = resolveActionSelectors(opts.actions ?? []);
   if (!resolved.ok) {
     showAmbiguity(resolved.selector, resolved.candidates, log, opts.json);
@@ -20381,16 +20454,26 @@ async function runDirectTextCharacter(opts) {
     return;
   }
   const controllerPack = opts.controllerPack !== false;
-  const price = await quote(`${ctx.apiUrl}/api/characters/quote`, ctx.token, {
+  const generationOptions = {
     actionIds: resolved.actionIds,
-    controllerPack
-  });
+    controllerPack,
+    ...opts.height === void 0 ? {} : { heightMeters: opts.height },
+    targetPolycount: opts.polycount ?? 1e4,
+    ...meshyQualityOptions(opts),
+    ...opts.pose === void 0 ? {} : { poseMode: opts.pose },
+    ...imageUrls === void 0 ? {} : { imageUrls }
+  };
+  const price = await quote(`${ctx.apiUrl}/api/characters/quote`, ctx.token, generationOptions);
   if (!price) {
     process.exitCode = 1;
     return;
   }
+  if (imageUrls && price.referenceImageCount !== imageUrls.length) {
+    fail2(opts, "This server did not confirm support for all character reference images. No generation was started. Update the Genex API to a version supporting character --image, then run this command.");
+    return;
+  }
   if (!opts.json) {
-    log.plain(c.bold("Direct-text character quote"));
+    log.plain(c.bold(imageUrls ? "Reference character quote" : "Direct-text character quote"));
     log.plain(`  ${price.credits} Genex credits = base ${price.baseCredits} + actions ${price.animationCredits}`);
     if (price.controllerPackKey) {
       const version = price.controllerPackVersion === void 0 ? "" : ` v${price.controllerPackVersion}`;
@@ -20408,14 +20491,7 @@ async function runDirectTextCharacter(opts) {
     token: ctx.token,
     apiUrl: ctx.apiUrl,
     quotedCredits: price.credits,
-    generationOptions: {
-      actionIds: resolved.actionIds,
-      controllerPack,
-      ...opts.height === void 0 ? {} : { heightMeters: opts.height },
-      targetPolycount: opts.polycount ?? 1e4,
-      ...meshyQualityOptions(opts),
-      ...opts.pose === void 0 ? {} : { poseMode: opts.pose }
-    }
+    generationOptions
   });
 }
 var CHARACTER_TEXTURE_SIZES = ["2k", "4k", "8k"];
@@ -20433,6 +20509,7 @@ function badCharacterTexture(opts) {
   return `--texture ${opts.texture} is a \`genex model\` tier. A character takes a texture SIZE: ${CHARACTER_TEXTURE_SIZES.join("|")} (default 4k).`;
 }
 async function runCharacterPreview(opts) {
+  if (refuseSubcommandImages(opts)) return;
   const log = createLogger({ quiet: opts.quiet || opts.json });
   const conceptId = opts.conceptId?.trim();
   if (!conceptId) {
@@ -20486,6 +20563,7 @@ async function runCharacterPreview(opts) {
   });
 }
 async function runCharacterFinalize(opts) {
+  if (refuseSubcommandImages(opts)) return;
   const log = createLogger({ quiet: opts.quiet || opts.json });
   const previewId = opts.previewId?.trim();
   if (!previewId) {
@@ -20513,7 +20591,7 @@ async function runCharacterFinalize(opts) {
     return;
   }
   if (opts.controllerPack === false) {
-    fail2(opts, "--no-controller-pack is only available with --direct-text. Guided finalization requires neutral-v3.");
+    fail2(opts, "--no-controller-pack is only available with --direct-text or --image. Guided finalization requires neutral-v3.");
     return;
   }
   const resolved = resolveActionSelectors(opts.actions ?? []);
@@ -20583,6 +20661,7 @@ async function runCharacterFinalize(opts) {
   });
 }
 async function runCharacterAnimate(opts) {
+  if (refuseSubcommandImages(opts)) return;
   const log = createLogger({ quiet: opts.quiet || opts.json });
   const characterId = opts.characterId?.trim();
   if (!characterId) {
@@ -23803,6 +23882,7 @@ ${c.bold("Usage")}
   genex image "<prompt>" [options]   Generate an image (PNG); prints a public asset URL.
   genex video "<prompt>" [options]   Generate a video (mp4); prints a public asset URL.
   genex character "<brief>"          Generate 3 character concepts for user selection.
+  genex character --image <path|url> Build directly from 1-4 supplied views (repeat --image).
   genex character preview <concept-id>
                                      Generate an unremeshed Meshy 7 preview of one
                                      explicitly user-approved concept candidate.
@@ -24050,6 +24130,10 @@ ${c.bold("Options for `list`")}
   --auth-url <url>     Override the auth site (used only if sign-in is needed).
 
 ${c.bold("Options for `character` / `animations search`")}
+  --image <path|url>   Build from supplied PNG/JPEG references; repeat up to 4 times.
+                       One view per image, same character; local files total \u22644 MB,
+                       or Genex asset URLs. Brief optional (ledger label only).
+                       Starts one shot; cannot combine with --direct-text or guided flags.
   --animation <id|q>   (character/finalize) add an action; repeatable. Ambiguous queries print
                        ranked action IDs instead of choosing silently.
   --candidate <1|2|3>  (character preview) selected concept candidate.
@@ -24060,15 +24144,15 @@ ${c.bold("Options for `character` / `animations search`")}
                        hero). The number IS the approval.
   --direct-text        One-shot path: skip concept/preview approval and generate
                        directly from text (defaults to a 10,000-face target).
-  --no-controller-pack (character --direct-text only) skip the validated locomotion pack.
+  --no-controller-pack (character one shot) skip the validated locomotion pack.
   --height <meters>    (character) target character height, 0.5-3 meters.
-  --polycount <count>  (character --direct-text / creature) target 10000-100000 polygons.
+  --polycount <count>  (character one shot / creature) target 10000-100000 polygons.
   --texture <res>      (character/creature/preview) texture size 2k | 4k (default) | 8k
                        (+5 credits). Meshy 7 on every lane.
   --no-ultra           (character/creature/preview) skip Meshy Ultra (\u22125 credits, less
                        surface detail).
   --pose <a-pose|t-pose>
-                       (character --direct-text / creature) preferred rest pose; the
+                       (character one shot / creature) preferred rest pose; the
                        other stays the QA fallback.
   --no-fingers         (character import) skip finger joints in the Uthana rig.
   --no-wait            (character/preview/finalize/animate) enqueue and return a generation id.
@@ -24141,6 +24225,7 @@ ${c.bold("Examples")}
   genex character preview <concept-id> --candidate 2 --user-approved
   genex character finalize <preview-id> --user-approved --approve-remesh 10000 --animation 466
   genex character "stylized sci-fi courier" --direct-text --no-wait
+  genex character --image ./front.jpg --image ./back.jpg --texture 8k --polycount 100000 --no-wait
   genex character animate <character-id> --action <action-id>
   genex character animate <character-id> "overhead slam" "parry and recover" --no-wait
   genex character animate <character-id> --locomotion --no-wait
@@ -24193,6 +24278,7 @@ ${c.bold("Characters")}
                                      The rigged, game-ready character.     ${cr("character_finalize")}
   genex character "<brief>" --direct-text
                                      One shot, no approval steps.          ${cr("character")}
+  genex character --image <path|url> One shot from 1-4 supplied PNG/JPEG views.
   genex creature "<desc>"            A rigged enemy (biped-shaped bodies).  ${String(CREATURE_TYPICAL_CREDITS).padStart(3)} cr
   genex character import <file.glb>  Your own humanoid mesh (or a genex model), ${cr("character_import")}
                                      auto-rigged by Uthana; the upload is free.
@@ -24253,6 +24339,11 @@ ${c.bold("Make one")}
   genex character finalize <preview-id> --user-approved --approve-remesh <faces>
                                                    The rigged, game-ready character (step 3).
   genex character "<brief>" --direct-text          One shot, no approval steps.
+  genex character --image <path|url> [--image \u2026]   One shot from 1-4 supplied PNG/JPEG views.
+                                                   Local files total \u22644 MB or Genex asset URLs.
+                                                   One view per image, same character. Optional
+                                                   brief is a ledger label, not text conditioning.
+                                                   Do not combine with --direct-text or guided flags.
   genex creature "<desc>"                          The one-shot lane with enemy defaults (no controller pack).
   genex character import <file.glb> [--height <m>] [--no-fingers]
                                                    Your own humanoid mesh \u2014 or a \`genex model\` GLB \u2014
@@ -24748,6 +24839,22 @@ function parseArgs(argv) {
       }
     }
   }
+  const imageCount = parsed.options.imageUrls?.length ?? 0;
+  if (imageCount > 0) {
+    if (parsed.command === "model" && imageCount > 1) {
+      parsed.error = "genex model accepts one --image reference. Use character --image for multiple character views.";
+    } else if (parsed.command === "character" || parsed.command === "creature") {
+      if (["preview", "finalize", "import", "animate", "motions", "adopt"].includes(parsed.options.name ?? "")) {
+        parsed.error = "--image starts a new reference character; it cannot be combined with a character subcommand.";
+      } else if (imageCount > 4) {
+        parsed.error = "--image accepts 1-4 references to the same character, one view per image.";
+      } else if (parsed.options.directText) {
+        parsed.error = "--image cannot be combined with --direct-text. Omit --direct-text to build from the supplied references.";
+      } else if (parsed.options.candidate !== void 0 || parsed.options.userApproved !== void 0 || parsed.options.approveRemesh !== void 0) {
+        parsed.error = "--image cannot be combined with guided --candidate / --user-approved / --approve-remesh flags. Use --polycount for the reference character's face budget.";
+      }
+    }
+  }
   return parsed;
 }
 function applyValueFlag(options, flag, value) {
@@ -25025,7 +25132,9 @@ function applyValueFlag(options, flag, value) {
       options.refs = [...options.refs ?? [], value];
       break;
     case "--image":
+      if (!value.trim() || value.startsWith("--")) throw new Error("Missing value for --image");
       options.imageUrl = value;
+      (options.imageUrls ??= []).push(value);
       break;
     case "--texture":
       if (!TEXTURE_FLAG_VALUES.includes(value)) {
@@ -25267,7 +25376,7 @@ async function main() {
         await runCharacter({
           ...parsed.options,
           prompt: parsed.options.name,
-          directText: true,
+          directText: parsed.options.imageUrls?.length ? parsed.options.directText : true,
           controllerPack: false
         });
         break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "1.34.3-dev.705",
+  "version": "1.34.4-dev.706",
   "description": "Set up your project's agent workspace (.claude/.codex/.cursor in the game folder), authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

package/templates/skills/genex-ai-character/SKILL.md

@@ -52,6 +52,24 @@ no code to rewrite, which is exactly why there is no excuse to skip it.
   selection, then an explicit approval of the separate 10,000-face
   remesh. Never compress these two stops for a user-initiated ask.
 
+## Build from supplied reference images
+
+When the user supplies a character reference to reproduce, use it directly:
+
+```bash
+npx genex character --image ./front.jpg --image ./back.jpg --texture 8k --polycount 100000 --pose t-pose --no-wait
+```
+
+Repeat `--image` for 1-4 PNG/JPEG views of the same character, one view per
+image. Split a contact sheet into individual views first. Local files total
+at most 4 MB; Genex asset URLs also work. Meshy uses these images directly,
+skipping concept generation, then remeshes and rigs the result. An optional
+brief is only a ledger label, not text conditioning. Do not combine with
+`--direct-text`, guided subcommands or their approval flags. One-shot quality,
+pose, face-budget and controller options apply; `creature --image` omits the
+controller pack by default. The following guided flow is for a new look from
+text, when no supplied images already define the character.
+
 ## Generate a controller-ready character
 
 Before generating a Meshy character, discuss two or three visual directions.
@@ -172,8 +190,8 @@ npx genex wait <generation-id>
 ```
 
 `--animation <id-or-query>` is repeatable on `finalize`.
-`--no-controller-pack` is available only with the explicit `--direct-text`
-compatibility path. The guided parity workflow always installs neutral-v3.
+`--no-controller-pack` is available with the one-shot `--direct-text` and
+`--image` paths. The guided parity workflow always installs neutral-v3.
 `--no-wait` returns a generation id for `genex wait`; it does not create a
 second paid request. In the default lane, `--user-approved` and
 `--approve-remesh <faces>` record the pick you made and announced after showing

package/templates/skills/genex-tool-character/SKILL.md

@@ -12,9 +12,26 @@ For a prop, vehicle or building, use `$genex-tool-model`. For a non-humanoid
 body plan (quadruped, flier, serpent) use that skill's `model rig` lane — this
 one produces biped-shaped bodies.
 
+## From the user's reference images
+
+When the user supplies a character reference, send those images to Meshy:
+
+```bash
+npx genex character --image ./front.jpg --image ./back.jpg --texture 8k --polycount 100000 --pose t-pose --no-wait
+```
+
+`--image` is repeatable, 1-4 PNG/JPEG views of the same character, one view per
+image. Local files must total at most 4 MB; Genex asset URLs also work. Split a
+contact sheet into individual views first. This is one shot: it skips concept
+generation and rigs the reference-derived mesh. An optional brief is only a
+ledger label, not text conditioning. Do not add `--direct-text`, guided
+subcommands or their approval flags. Ultra is on by default; select texture
+size and face budget for the requested quality. `creature --image` uses this
+same route without the player controller pack.
+
 ## The guided flow (three steps, one approval each)
 
-Use this when the character's LOOK matters and a person is choosing it:
+Use this when creating a new look from text and a person is choosing it:
 
 ```bash
 npx genex character "stylized sci-fi courier, practical layered clothing"