image-to-3d

图像转 3D Blender 技能

使用 Meshy AI API 将用户提供的照片转换为带纹理的 3D 模型，然后将其导入当前 Blender 场景。

适用场景

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

• 用户想将照片／图像转换为 3D 模型
• 用户说“把这个做成 3D”“转换为 3D”或“根据图像创建 3D 模型”
• 用户提供图像，并希望将其作为 3D 对象导入 Blender

前置条件

• Meshy API 密钥：存储在环境变量 MESHY_API_KEY 中，或直接传入
• Blender MCP：必须已连接（blender-mcp 插件在端口 9876 上运行）
• 图像：本地文件路径（.jpg、.jpeg、.png）或可公开访问的 URL

流程

步骤 1：准备图像

如果用户提供本地文件路径，请将其编码为 base64：

BASE64_IMAGE=$(base64 -i "<image_path>")
DATA_URI="data:image/png;base64,${BASE64_IMAGE}"

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

curl -s https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${MESHY_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<data_uri_or_public_url>",
    "ai_model": "meshy-6",
    "enable_pbr": true,
    "should_remesh": true,
    "should_texture": true,
    "topology": "quad",
    "target_polycount": 30000,
    "target_formats": ["glb"]
  }'

响应会返回一个任务 ID：{"result": "<task_id>"}

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

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

每隔 10 秒轮询一次。检查 status 字段：

• PENDING — 排队中
• IN_PROGRESS — 正在生成（检查 progress 字段以查看百分比）
• SUCCEEDED — 已完成，model_urls.glb 中包含下载 URL
• FAILED — 检查 task_error.message

步骤 4：下载 GLB

curl -L -o "/Users/kevinbahrabadi/Blender Test/output/<filename>.glb" "<model_urls.glb>"

步骤 5：导入 Blender

使用 Blender MCP 的 execute_blender_code 工具：

import bpy

# Clear scene (optional, based on user preference)
bpy.ops.object.select_all(action='SELECT')
bpy.ops.object.delete()

# Import GLB
bpy.ops.import_scene.gltf(filepath="/Users/kevinbahrabadi/Blender Test/output/<filename>.glb")

# Center and frame the imported object
bpy.ops.object.select_all(action='SELECT')
bpy.ops.view3d.view_selected()

配置选项

选项	默认值	描述
ai_model	meshy-6	要使用的模型。选项：meshy-5、meshy-6、latest
model_type	standard	standard 用于生成细节丰富的模型，lowpoly 用于生成简洁的游戏网格
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	生成纹理（需要额外积分）
remove_lighting	true	清除纹理中烘焙的光照

输出

完成后，用户将获得：

• 已导入 Blender 场景的 3D 模型
• 应用了 PBR 材质的纹理（如果已启用）
• 可用于渲染、动画或进一步编辑

错误处理

• 402：Meshy 积分不足 — 告知用户
• 429：请求频率受限 — 等待后重试
• FAILED 状态：向用户报告 task_error.message
• Blender MCP 已断开连接：请用户重新连接插件