[AltaMills]

Summary

Meshy N1 (ai_model: "meshy-n1") makes a 2K base color texture from reference images only, for 10 credits. It takes either one --image-style-url, read as the front view, or 1–4 --multiview-image-urls, front first and the rest in any order.

Before this change, N1 could only be picked through --data, and the CLI's retexture defaults (enable_pbr: true, texture_resolution: "4k", meshy-7 pinned on multi-view) turned every such request into a 400.

Release only after Meshy N1 is live for every API user. Until then, the API refuses meshy-n1 for callers it has not enabled.

Changes

• New flag: retexture create --ai-model latest|meshy-7|meshy-6|meshy-n1.

  • meshy-5 is not offered, since it is retired.
  • meshy-6-lite stays reachable only through --data, as before. Its 2K limit clashes with the 4K default, and that default is unchanged here.

• Defaults for meshy-n1: enable_pbr: false and texture_resolution: "2k", with no meshy-7 pin on multi-view.

  • They apply whether N1 comes from the flag or from --data (the flag wins, the same precedence the merged payload uses).
  • Every other model keeps its defaults: PBR on, 4K, and meshy-7 on multi-view.

• Refused before the POST with N1 (exit 2), whether set by flag or by --data:

  • a text prompt;
  • enable_pbr: true;
  • 4k / 8k, or hd_texture: true;
  • remove_lighting.

  With no reference image, the CLI says N1 needs one.

• Also refused locally: --ai-model latest|meshy-6 together with --multiview-image-urls.

• Stricter than the API on purpose: a prompt beside one image (v1 drops it) and hd_texture: true beside an explicit "2k" (the API runs at 2k). The other N1 refusals are 400s on the API too.

• Not refused locally: only the inputs above are checked before the create. A --data multiview_image_urls with 5 views, an empty, numeric or null element goes to the API as given, which answers it. With an expired OAuth login the CLI refreshes the token first, so one token request precedes a local refusal.

• Face limit: the CLI does not check it. The skill points to meshy inspect faces and the limit in the API docs.

• Docs:

  • D-088 in docs/decisions.md records why N1 flips the defaults rather than the defaults changing for every model;
  • an example block in docs/usage.md;
  • a bullet in skills/meshy-cli/SKILL.md.

  No version bump, publish or tag.

Failures the tests guard

tests/retexture.test.ts runs the built CLI against a loopback API and checks the POST body. The new tests failed on main first. The loopback API answers every create with 200, so these tests prove the request body and the CLI's own refusals, not what the backend does with them.

• F1 / F2: N1 inherits PBR on or 4K, so every N1 request gets a 400.
• F3: the multi-view meshy-7 pin replaces an N1 pick, so a Meshy 7 task runs and is billed.
• F4: views are reordered or dropped, so the wrong image is read as the front view (checked with 1, 2 and 4 views).
• F5: N1 picked through --data keeps the Meshy 7 defaults.
• F6: N1 with a text prompt and no image is sent, or refused without saying that an image is needed.
• F7: a prompt next to an image in --data is sent, and the API drops it silently.
• F8: an explicit PBR, 4K, 8K, hd_texture or remove_lighting request with N1, by flag or by --data, is sent or quietly rewritten.
• F9: other models lose PBR, 4K or the meshy-7 multi-view pin (checked with no flag, meshy-7, meshy-6 and latest).
• F10: --ai-model accepts meshy-5 or a typo and spends a request on it.
• F11: latest or meshy-6 with multi-view is sent.
• F12: the flag no longer beats ai_model in --data, or the defaults do not follow the model that wins.
• F13: with an expired OAuth login, a refused N1 request skips the refresh or sends a create: the login is refreshed once and saved, then the CLI exits 2 with no create sent.

How to test

pnpm install --frozen-lockfile && pnpm typecheck && pnpm test && pnpm build   # 595 pass locally (the wait/SIGINT timing tests can flake under heavy machine load; they pass on their own)

Against an API where Meshy N1 is enabled for the caller:

meshy retexture create --input-task-id <id> --ai-model meshy-n1 --image-style-url ./front.png --format json
meshy retexture create --input-task-id <id> --ai-model meshy-n1 --multiview-image-urls ./front.png,./back.png --format json

Expected POST body: ai_model: "meshy-n1", enable_pbr: false, texture_resolution: "2k", and the views in the order given.

Not verified end to end against a live API from this branch.

Linear: ENG-5144.

🤖 Generated with Claude Code