scenario-meshy

Scenario Meshy 3D

概述

Scenario 上的 Meshy 是一套工具链，而不是单个模型：图像转 3D 生成器（Meshy 7 Image to 3D、Meshy 7 Multi Image to 3D、Meshy T2 Smart Topology）、Meshy 6 Text-to-3D，以及 GLB 输入、GLB 输出工具（Retexture、Remesh、UV Unwrap、Rigging、Animation）。工作以流水线方式进行：生成网格、优化网格，然后绑定骨骼或制作动画；每个阶段都有自己的 model_run，其 model 参数接收上一阶段返回的 3D 资产 ID。使用 search 查找成员，并将 model_schema_get 视为接口约定：各成员的默认值甚至 enablePbr 这样基础的设置都可能不同（编写时，Image to 3D 默认为 true，Multi Image 和 Retexture 默认为 false）。

连接和核心工作流程：参阅此仓库中的 scenario 技能；与模型无关的 3D 工作（查看器、捕获、引擎导入）：参阅 scenario-3d 技能。如果此处提到的关联技能未出现在你可用的技能中，请让用户安装它（npx skills add scenario-labs/skills --skill <name>）；若无需人工介入，则根据工具架构继续操作，并指出这一缺失。

快速参考

成员及其注意事项（名称来自实时架构，以下限制为编写时的数据）：

成员	核心输入	注意事项
7 Image to 3D	image（1-4 张）	ultraMode 仅接受单张图像；默认生成原始网格
7 Multi Image to 3D	image（1-4 张，第一张为正面视图）	在运行中重新网格化；savePreRemeshedModel 可保留原始 GLB
T2 Smart Topology	image（1-4 张）	适合制作动画的拓扑；targetPolycount 上限为 15,000
6 Text-to-3D	prompt（600 个字符）	默认关闭 shouldRemesh
Retexture	model + 一种风格输入	不修改几何体；输入网格建议接近 30K 个多边形；enableOriginalUv
Remesh	model	targetPolycount 为 100 到 300,000；resizeHeight、originAt
UV Unwrap	model	拒绝超过 44,000 个面的网格；先用 Remesh 降低面数
Rigging	model、heightMeters	人形骨架和蒙皮权重
Animation	model、actionId	自动绑定骨骼，然后应用动画片段

所有纹理控制都有一条不言自明的规则：图像优先于文本。对于生成器，textureImage 会覆盖 texturePrompt（文本会被忽略，不会混合使用），而且两者都要求开启 shouldTexture（Text-to-3D 没有此开关：它始终会生成纹理）。Retexture 的限制更严格：textStylePrompt、imageStyle 或 multiviewImage 三者必须且只能设置一个（1 到 4 个视图，第一张为正面视图）。textureResolution 可设为 2k、4k 或 8k；设为 8k 时，PBR 贴图会以 4K 返回，且不包含发光贴图（Meshy 7 不会生成发光贴图），同时 8k 仅能与重网格化时的三角形拓扑搭配使用。poseMode 接受小写的 "a-pose" 或 "t-pose"：任何准备进行骨骼绑定的角色都要设置其中一个。

生成原始网格，有目的地进行优化

Meshy 7 Image to 3D 默认应关闭 shouldRemesh（架构也建议如此）：生成时先获取原始网格，再使用 Remesh 控制多边形数量。Remesh 负责设置 targetPolycount、拓扑、以米为单位的 resizeHeight（0 表示保持比例）和原点位置。生成器上的 targetPolycount 在关闭 shouldRemesh 时不起作用。ultraMode 可通过增加成本换取更精细的几何体，但只接受一张输入图像；当隐藏面细节比微小细节更重要时，不妨将预算用于最多四个视图。成本差异很大（编写时，单图 Meshy 7 的 p50 成本是多图版本的三倍），因此批量运行前先使用 dry_run。

绑定骨骼或制作动画，二选一

绑定骨骼和制作动画是两种替代方案，并非前后两个阶段。制作动画会在内部自动绑定骨骼，然后应用由 actionId 指定的动画片段；该值是 Meshy 动画库中的一个编号（编号列表见 docs.meshy.ai/en/api/animation-library）。如果你想为自己的动画片段获取绑定骨骼的 GLB，请单独运行绑定骨骼；如果想让角色动起来，则直接运行制作动画，并可选择将 postProcessOperation 设为 change_fps（postProcessFps 可设为 24、25、30 或 60）或 extract_armature。两者都会根据 heightMeters 缩放骨骼，因此请传入角色的实际身高。

示例：从照片到动画角色

1. 使用 target="models"、query="meshy"、public=true 调用 search。单张图片流程：model_meshy-7-img23d（撰写本文时可用；每次会话都应重新查找）。search 不会标记计划访问权限；撰写本文时，Meshy 的多个成员功能（包括制作动画和绑定骨骼）都需要高于入门级的计划：在第 3 步付费前，使用 capability="3d23d" 和动画需求调用 recommend；如果制作动画条目带有 requires_plan_upgrade，请提示升级计划，或停留在静态网格阶段，否则第 3 步计费后，第 5 步会失败并返回注明计划名称的 403 错误（ModelAccessRestrictedError）。
2. 使用该 ID 调用 model_schema_get，然后上传角色照片作为 upload_asset（参见 scenario 技能）。
3. 使用 dry_run=true 和 parameters={"image": ["asset_photo"], "poseMode": "t-pose", "texturePrompt": "worn leather armor, muted palette", "enablePbr": true} 调用 model_run 获取费用预估；然后用 wait=false 再次运行，并通过 jobs_wait 等待任务，超时后使用 pending_job_ids 再次调用；切勿再次调用 model_run。
4. 使用 asset_display 查看 GLB；继续投入费用前，先检查轮廓和纹理。
5. 搜索动画成员，调用 model_schema_get，然后使用 parameters={"model": "<GLB asset id from step 4>", "heightMeters": 1.8, "actionId": <id from the library>} 调用 model_run。
6. 调用 jobs_wait 和 asset_display，然后调用 asset_download，以便导入引擎。

常见错误

• 同时设置 texturePrompt 和 textureImage，期望两者融合：图片优先，文本会被忽略。
• 在重新纹理时输入两种风格：只能选择提示词、风格图片或多视角图片之一。
• 使用多张图片时设置 ultraMode: true：Ultra 要求只提供一张输入图片。
• 在高密度网格上执行 UV 展开：面数超过 44,000 时任务会被拒绝；请先执行重新网格化以降低面数。
• 在制作动画前先绑定骨骼：制作动画会自行绑定骨骼，因此这一流程会浪费一次任务。
• 在图像转 3D 或文本转 3D 中关闭 shouldRemesh 时设置 targetPolycount：该参数不会生效。
• 当架构要求数组时却传入纯字符串：单张照片应写作 ["asset_x"]。
• 使用占位资源 ID 估算第 5 步的费用：文件 ID 会先解析，然后才检查计划访问权限，因此试运行会返回 404，无法确认价格或访问权限。