multi-image-to-3d

多图转 3D Blender 技能

使用 Meshy AI 的 Multi-Image to 3D API，将同一物体的 1–4 张照片（拍摄角度不同）转换为带纹理的 3D 模型，然后将其导入当前 Blender 场景。角度越多，几何形状和纹理越准确。

适用场景

在以下情况下触发此技能：

• 用户提供了同一物体的多张照片，并希望生成 3D 模型
• 用户说“多角度 3D”“将这些图像转换为 3D”“用这些照片制作 3D 模型”
• 用户希望获得比单张图像生成更准确的 3D 模型
• 用户提供了产品、角色或物体的正面、背面或侧面照片

前置条件

• Meshy API 密钥：从记忆中获取（reference_meshy_api.md）
• Blender MCP：必须已连接（blender-mcp 插件正在端口 9876 上运行）
• 图像：1–4 个本地文件路径（.jpg、.jpeg、.png）或可公开访问的 URL
• 同一物体：所有图像都必须展示同一物体的不同角度

流程

步骤 1：准备图像

对每个本地文件进行 base64 编码，并转换为 data URI：

import base64, json

image_paths = ["front.png", "back.png", "side.png"]  # user-provided paths
image_urls = []

for path in image_paths:
    with open(path, 'rb') as f:
        b64 = base64.b64encode(f.read()).decode()
    ext = path.rsplit('.', 1)[-1].lower()
    mime = 'image/jpeg' if ext in ('jpg', 'jpeg') else 'image/png'
    image_urls.append(f"data:{mime};base64,{b64}")

步骤 2：创建多图转 3D 任务

将请求正文写入 JSON 文件（base64 字符串过大，不适合作为 CLI 参数）：

payload = {
    "image_urls": image_urls,  # array of 1-4 data URIs or public URLs
    "ai_model": "meshy-6",
    "enable_pbr": True,
    "should_texture": True,
    "target_formats": ["glb"]
}

with open("output/request.json", "w") as f:
    json.dump(payload, f)

然后发送 POST 请求：

curl -s https://api.meshy.ai/openapi/v1/multi-image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${MESHY_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d @output/request.json

响应：{"result": "<task_id>"}

步骤 3：轮询任务完成状态

curl -s https://api.meshy.ai/openapi/v1/multi-image-to-3d/<task_id> \
  -H "Authorization: Bearer ${MESHY_API_KEY}"

每隔 15 秒轮询一次。检查 status：

• PENDING — 排队中（检查 preceding_tasks 获取队列位置）
• IN_PROGRESS — 正在生成（检查 progress 获取百分比）
• SUCCEEDED — 已完成，从 model_urls.glb 下载
• FAILED — 检查 task_error.message

步骤 4：下载 GLB

curl -L -o "output/<filename>.glb" "<model_urls.glb>"

步骤 5：导入 Blender

使用 Blender MCP 的 execute_blender_code 工具：

import bpy

# Clear scene (optional)
for obj in bpy.data.objects:
    bpy.data.objects.remove(obj, do_unlink=True)

# Import GLB
bpy.ops.import_scene.gltf(filepath="<path_to_glb>")

# Frame imported object
bpy.ops.object.select_all(action='SELECT')

# Add basic lighting
import math
from mathutils import Vector, Euler
bpy.ops.object.light_add(type='AREA', location=(2, -2, 3))
key = bpy.context.active_object
key.data.energy = 500
key.data.size = 3

# Set viewport to material preview
for area in bpy.context.screen.areas:
    if area.type == 'VIEW_3D':
        for space in area.spaces:
            if space.type == 'VIEW_3D':
                space.shading.type = 'MATERIAL'

配置选项

选项	默认值	描述
ai_model	meshy-6	meshy-5、meshy-6 或 latest
topology	triangle	quad 或 triangle 网格
target_polycount	30000	100–300,000 个多边形
enable_pbr	true	金属度／粗糙度／法线贴图
symmetry_mode	auto	off、auto 或 on
pose_mode	""	a-pose、t-pose 或留空
should_texture	true	生成纹理
should_remesh	false	重网格化至目标多边形数／拓扑
remove_lighting	true	清理纹理，去除烘焙光照
image_enhancement	true	优化输入图像
target_formats	all	数组：glb、obj、fbx、stl、usdz、3mf

获得最佳效果的提示

• 不同角度：正面、背面、左侧面和右侧面效果最佳
• 光照一致：所有照片的光照条件应保持一致
• 背景干净：纯色／白色背景有帮助
• 同一物体：所有图像必须展示同一物体
• 2–4 张图像：角度越多，准确度越高，但超过 4 张后收益递减

错误处理

• 400：图像数量无效（必须为 1–4 张）、格式错误或 URL 无法访问
• 402：Meshy 额度不足
• 429：请求过于频繁 — 等待后重试
• FAILED 状态：向用户报告 task_error.message