如何使用Image to 3D Model API：完整指南 2026

Image to 3D Model API 可将单张照片在数秒内转换为可直接投入生产的 3D 模型——无需手动建模。手动为每个资产建模既缓慢又昂贵，对于游戏工作室、AR 应用和电商团队而言，这很快就会成为拖慢发布进度的瓶颈。Meshy 的 Image to 3D Model API 消除了这一障碍：发送一张图片，数秒内将其转换为 3D 模型，并以 GLB、FBX 和 OBJ 等格式下载带有完整纹理的网格。本指南将带你走完整个工作流程——从创建 API 密钥到下载第一个模型——并提供可直接复制粘贴的代码，几分钟内即可运行。

什么是 Image to 3D Model API？

其核心是，Image to 3D Model API 是一个由 Meshy 的 Image to 3D Model AI 驱动的 REST 端点。你发送一张单张图片（JPG、JPEG 或 PNG），以公共 URL 或 base64 字符串形式提供，API 会返回一个带纹理的 3D 模型——包含几何体和基础颜色纹理——格式为标准格式，如 GLB、FBX、OBJ、USDZ、STL 和 3MF。可选附加功能包括 PBR 贴图、高达 4K 的纹理以及多角度预览缩略图。

由我们最新的 Meshy 6 模型驱动，该 API 允许你配置拓扑和多边形数量、设置姿态模式，并通过文本提示或参考图像引导纹理生成——非常适合为游戏、AR/VR、3D 打印和产品可视化生成资产。

使用 Image to 3D API 需要什么？

遵循本指南你不需要太多准备。请确保你拥有：

• 一个 Meshy 账户 — 如果没有，请免费注册。你将在步骤 1 中从仪表盘生成 API 密钥。

• 一个 API 密钥 — 用于验证每个请求。我们将引导你创建一个，你可以使用免费的测试模式密钥跟随操作，无需消耗积分。

• 一张输入图片 — 一张清晰的 .jpg、.jpeg 或 .png 图片，托管在可公开访问的 URL 上（或编码为 base64）。干净的背景和清晰可见的主体能带来最佳效果。

• 一种发送 HTTP 请求的方式 — curl（在下面的示例中使用）、Postman 或你选择的任何语言的 HTTP 库。对 REST API 和 JSON 有基本了解会有所帮助，但并非必需。

仅此而已——无需 3D 建模经验。让我们开始吧。

如何使用 API 将图片转换为 3D 模型（分步指南）

步骤 1：设置你的 API 设置

开始构建所需的一切都在 API 设置页面上。这是你 Meshy API 的控制中心，包含三个关键部分：

• API 密钥 — 生成和管理用于验证请求的密钥。

• Webhooks — 当你的任务完成时自动收到通知。

• 使用情况 — 实时跟踪你的剩余积分余额和 API 消耗。

让我们逐一了解。

获取你的 API 密钥

在发出任何请求之前，你需要一个 API 密钥来安全地进行身份验证。在 API 设置页面上，点击生成 API 密钥。每个密钥的格式为 msy-<随机字符串>。

提示： 生成后，将你的 API 密钥存储在安全的地方（例如密码管理器或环境变量中）。像对待密码一样对待它——切勿将其提交到源代码控制或在客户端代码中暴露。

测试模式 API 密钥

在开发和测试期间，你可以使用测试模式 API 密钥来探索 API，而无需消耗你的积分：

msy_dummy_api_key_for_test_mode_12345678

这个特殊密钥具有以下特性：

• 可用于向所有 Meshy API 端点发出请求。

• 使用此密钥时不消耗任何积分。

• 所有有效请求都返回相同的示例任务结果，无论输入参数如何。

• 响应数据结构与生产 API 完全一致。

这使得它非常适合在切换到真实 API 密钥之前测试你的集成。

设置 Webhooks（可选）

生成 3D 模型需要时间，因此与其反复轮询 API 来检查任务是否完成，你可以让 Meshy 在任务完成时立即通知你。这就是 webhooks 的用途。

在设置页面的 Webhooks 部分，添加一个端点 URL，Meshy 将向该 URL 发送事件通知。当任务状态发生变化时（例如，当它完成或失败时），Meshy 会向你的 URL 发送一个 HTTP POST 请求，并在负载中包含任务详情。

提示： Webhooks 是生产环境的推荐方法。它们减少了不必要的 API 调用，并让你的应用程序能够实时响应结果。对于快速测试，轮询仍然可以正常工作。要本地测试 webhook 代码，请将其指向来自 smee.io 等服务的代理 URL。

无需代码尝试 — API Playground（可选）

已经有你的 API 密钥了？在编写任何代码之前，你可以直接在浏览器中运行一个真实的 Image to 3D 任务。

打开 meshy.ai/api-playground，从左侧面板选择 Image to 3D，然后填写三项内容：

1. Authorization — 粘贴你的 API 密钥（msy-xxxxxxxxxx）

2. Image — 从你的计算机上传一个 .jpg、.jpeg 或 .png 文件

3. 点击 Send

Playground 会自动提交任务并轮询结果。完成后，你将直接在浏览器中看到 3D 模型预览和下载链接——无需代码。

专业提示： 右侧的原始请求/响应面板精确显示了 API 发送和返回的内容。你可以直接复制内容——从响应中获取 task_id，并在任务完成后获取 model_urls。你将在接下来的步骤中使用这两者。

步骤 2：提交一个 Image to 3D 任务

准备好你的 API 密钥后，通过一个 POST 请求启动任务：

curl -X POST https://api.meshy.ai/openapi/v1/image-to-3d \
  -H "Authorization: Bearer $MESHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/your-image.png"
  }'

你将收到如下响应：

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

那个 result 值就是你的 task_id — 请保存它。你将在下一步中需要它来检查进度和检索模型。

可选： 要在任务完成时自动收到通知，请在 JSON 正文中添加一个 webhook_url 字段——例如 "webhook_url": "https://yourapp.com/webhooks/meshy"。请参阅步骤 3，选项 B 了解其工作原理。

步骤 3：获取你的结果

你的任务不会立即完成——Meshy 会在后台处理它。你有两种方式获取结果：

选项 A：轮询状态（最简单）

每 5 秒发送一个 GET 请求，直到 status 变为 SUCCEEDED：

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

响应如下所示：

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "SUCCEEDED",
  "progress": 100,
  "model_url": "https://assets.meshy.ai/.../model.glb",
  "model_urls": {
    "glb": "https://assets.meshy.ai/.../model.glb",
    "fbx": "https://assets.meshy.ai/.../model.fbx",
    "obj": "https://assets.meshy.ai/.../model.obj",
    "usdz": "https://assets.meshy.ai/.../model.usdz",
    "stl": "https://assets.meshy.ai/.../model.stl",
    "mtl": "https://assets.meshy.ai/.../model.mtl"
  },
  "thumbnail_url": "https://assets.meshy.ai/.../thumbnail.png",
  "consumed_credits": 30
}

几个值得了解的字段：

• model_urls 包含每种生成格式的下载链接。默认情况下，这包括 glb、fbx、obj、usdz、stl 和 mtl（与 obj 配对的材质文件）。

• model_url 是 GLB 链接的快捷方式——当你只需要 GLB 时非常方便。

• consumed_credits 显示任务消耗的积分数量（对于失败的任务为 0，因为积分会退还）。

• thumbnail_url 始终存在，指向正面视图的缩略图。

• thumbnail_urls 仅在 multi_view_thumbnails: true 时出现，包含正面、右侧、背面和左侧视图。

• alpha_thumbnail_url 仅在 alpha_thumbnail: true 时出现，包含透明背景的缩略图。

可能的 status 值：PENDING → IN_PROGRESS → SUCCEEDED / FAILED / CANCELED

选项 B：Webhook（推荐用于生产环境）

如果你在步骤 2 中设置了 webhook_url，Meshy 会自动将完成的任务对象 POST 到你的 URL——无需轮询。

{
  "image_url": "https://example.com/your-image.png",
  "webhook_url": "https://yourapp.com/webhooks/meshy"
}

💡 我应该使用哪个？ 轮询适用于原型设计和一次性任务。在生产环境中使用 webhooks——它更可靠且节省 API 调用。

步骤 4：下载你的 3D 模型

一旦 status 为 SUCCEEDED，从 model_urls 中获取下载 URL，并下载你需要的格式：

curl -o model.glb "https://assets.meshy.ai/.../model.glb"

-o model.glb 标志将文件保存到当前工作目录，并使用该名称——使用完整路径（例如 -o /path/to/model.glb）将其保存到其他位置。

默认情况下，每个任务都会返回 GLB、FBX、OBJ、USDZ、STL 和 MTL（OBJ 的材质文件）。3MF 是可选加入的——只有当你通过 target_formats 明确请求时才会获得（请参阅下面的参数表）。

⚠️ 链接在 3 天后过期（企业计划可获得永久链接）。请及时下载并存储你的模型——链接过期后将无法使用，你需要重新运行任务。

准备好在你喜欢的 DCC 工具中使用这个模型了吗？请参阅 Bridge to Blender 指南——Meshy 还提供了适用于 Unity、Unreal、Maya 和更多的桥接工具。

如何获得最佳的 Image to 3D 效果？

• 使用单一、清晰可见的主体。 一个主要物体，居中且完全在画面内，能为 AI 提供最清晰的参考——避免杂乱的场景、过度裁剪和极端角度。

• 优先选择干净、不杂乱的背景。 纯色或简单的背景有助于模型将主体与其周围环境分离。

• 使用均匀、漫射的光线。 强烈的阴影和高光可能会将误导性的细节烘焙到生成的纹理中。

• 从高分辨率、清晰的图像开始。 输入更多细节意味着输出更多细节——模糊或低分辨率的输入会产生较柔和的模型。

我可以使用哪些编程语言与 Image to 3D API 交互？

任何可以发出 HTTP 请求的语言——你发送一个带有 JSON 的 POST 请求，并使用 GET 进行轮询。常见选项：

• Python — 使用 requests 或 httpx 库

• JavaScript / TypeScript — 使用 fetch（内置）或 axios

• Go — 使用标准库中的 net/http

• cURL — 非常适合从终端进行快速测试

你还可以在 API Playground 中找到所有四种语言的即用代码示例。

一个 Image to 3D 任务需要多少积分？

成本取决于模型版本以及是否生成纹理。默认设置（meshy-6 带纹理）每个任务消耗 30 积分：

失败的任务会自动退还积分——consumed_credits 返回 0。请始终查看定价页面以获取最新费率。

Image to 3D API 接受哪些参数？

向 /openapi/v1/image-to-3d 发送 POST 请求，包含以下参数： 必需（二选一）：

可选：

Image to 3D API 的后续步骤

你现在已经掌握了完整的工作流程：创建 API 密钥、提交图片、轮询或使用 webhook 获取结果，然后下载你的模型。同样的四个步骤可以从快速原型扩展到生产管道，自动将数千张图片转换为 3D 资产。立即从 API 设置页面获取你的密钥，并交付你的第一个模型。更喜欢从提示而不是照片开始？请使用 Text to 3D Model API。

常见问题解答

如何通过 API 将图片转换为 3D 模型？

向 /openapi/v1/image-to-3d 发送一个 POST 请求，包含你的 image_url 和 API 密钥，然后轮询任务（或使用 webhook），直到其 status 变为 SUCCEEDED。响应会返回生成模型的下载链接。完整的四步流程——密钥、提交、检索、下载——已在上述分步指南中介绍。

API 支持哪些输出格式（STL、GLB、OBJ）？

默认情况下，每个任务都会返回 GLB、FBX、OBJ、USDZ、STL 和 MTL，3MF 可通过 target_formats 请求获得。GLB 最适合 Web 和 AR，FBX 和 OBJ 适用于 DCC 工具和游戏引擎，USDZ 适用于 iOS AR，STL 适用于 3D 打印。

我可以上传哪些图片格式？

Image to 3D API 支持 JPG、JPEG 和 PNG 图片，最大 100 MB——大于 Meshy Workspace UI 中 20 MB 的限制。为了获得最准确的结果，请使用透明或干净的白色背景的 PNG，这有助于 API 隔离主体并生成更高质量的 3D 模型。

我可以从 API 获得带纹理的 3D 模型吗？

可以。纹理生成默认启用（"should_texture": true）。要添加 PBR 贴图（金属度、粗糙度、法线），请设置 "enable_pbr": true——在 meshy-6/latest 上，这还包括一张自发光贴图。要获得 4K 基础颜色纹理，请设置 "hd_texture": true（仅 meshy-6/latest 支持；PBR 贴图保持 2K）。你还可以使用 texture_prompt 或 texture_image_url 来引导纹理样式。

我可以生成可用于 3D 打印（STL）的 3D 模型吗？

可以——STL 默认生成，因此 Image to 3D STL 转换无需额外参数：只需在任务完成时获取 model_urls.stl 即可。这使得 Image to 3D 打印工作流程变得简单，因为 STL 是切片器期望的标准格式。如果你只需要 STL，请设置 "target_formats": ["stl"] 以跳过其他格式并缩短生成时间。

哪些计划包含 API 访问权限？

API 访问权限适用于 Pro、Studio 和 Enterprise 计划——这是 Pro 及以上版本的功能。免费的 Starter 计划不包含 API 访问权限。详情请参阅定价。

下载链接的有效期是多久？

Pro 和 Studio 计划的下载链接有效期为 3 天。企业客户可获得永久链接。请及时保存你的文件——过期的链接无法恢复，你需要重新运行任务。

我可以同时运行多个任务吗？

可以，支持并发请求。如果你遇到 429 Too Many Requests 错误，说明你的账户已达到速率限制——请实现指数退避并重试。请参阅速率限制页面了解你计划的限制。

任务显示 FAILED——我该怎么办？

检查 task_error.message 以了解原因。常见问题：

如果问题仍然存在，请联系 Meshy 支持。