快速开始
首先创建你的 API key
本指南中的每个请求都需要一个 API key。创建密钥只需几秒钟。
创建你的 API key通过四个步骤,使用 Meshy REST API 制作你的第一个 3D 模型,从创建 API key 到下载模型。
1获取您的 API key
在开发者平台的 API Keys 页面创建一个 API key。离开该页面后您将无法再次查看该密钥,因此请将其妥善保存。在每个请求中,将其作为 Bearer 令牌放在 Authorization 标头中发送。请参阅Authentication。
您需要付费计划才能创建和管理 API key。在免费计划下,您无法创建自己的密钥,Playground 会使用内置密钥进行测试。

请勿将密钥保留在脚本中。应将其存储在环境变量中,如下一步所示。
2创建一个 Image to 3D 任务
将一张图片发送给 Image to 3D。如果想改用文本 prompt 或多张照片作为起点,请使用 Text to 3D 或 Multi-Image to 3D。
首先,将你的密钥存储到环境变量中:
Export your key
export MESHY_API_KEY="<your-api-key>"
请在终端中运行此命令(macOS 上的 Terminal,Windows 上的命令提示符或 PowerShell),而不是在浏览器中运行。
以下示例均使用这张照片。若要尝试其他图片,请修改 image_url。

Request
curl 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": "https://docs.meshy.ai/images/api/quick-start/source-photo.webp"
}'
3检查任务状态
任务在后台运行,通常需要几分钟。请持续从同一个 endpoint 获取任务,直到 status 变为 SUCCEEDED、FAILED 或 CANCELED。在以下请求中,将 <task_id> 替换为第 2 步返回的 ID。两次请求之间,请等待 Retry-After 响应头中指定的秒数。
有关典型处理时间以及放弃等待的时间,请参阅任务生命周期。
Request
curl https://api.meshy.ai/openapi/v1/image-to-3d/<task_id> \
-H "Authorization: Bearer ${MESHY_API_KEY}"
Response: SUCCEEDED
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"status": "SUCCEEDED",
"progress": 100,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"task_error": {
"message": ""
}
}
如果任务失败,status 会显示为 FAILED,并且 task_error 会说明原因。请修正输入或创建另一个任务。请参阅 Errors。
4下载你的模型
这些文件位于上一步响应的 model_urls 中。每种格式(GLB、FBX、OBJ、USDZ 和 STL)都有一个在有限时间内有效的签名 URL。你也可以将该 URL 粘贴到浏览器中下载文件。
Download
curl -L "<model_urls.glb from the response above>" -o model.glb

除企业版方案外,Meshy 在所有方案中都会将文件保留 3 天。请在此之前下载你所需的文件。请参阅 资产保留期。
整合到一起
这个脚本会创建任务、等待任务完成,并下载模型。
Full script
import axios from 'axios';
import fs from 'fs';
const headers = { Authorization: `Bearer ${process.env.MESHY_API_KEY}` };
const imageUrl = 'https://docs.meshy.ai/images/api/quick-start/source-photo.webp';
// 1. Create the task
const { data: created } = await axios.post(
'https://api.meshy.ai/openapi/v1/image-to-3d',
{ image_url: imageUrl },
{ headers, timeout: 60_000 },
);
const taskId = created.result;
// 2. Poll until it finishes, for up to 60 minutes
const deadline = Date.now() + 60 * 60 * 1000;
let task;
while (true) {
const { data, headers: resHeaders } = await axios.get(
`https://api.meshy.ai/openapi/v1/image-to-3d/${taskId}`,
{ headers, timeout: 30_000 },
);
task = data;
if (['SUCCEEDED', 'FAILED', 'CANCELED'].includes(task.status)) break;
if (Date.now() > deadline) {
// The task is still running. Check it again later with the same task ID instead of creating a new one.
throw new Error(`Task ${taskId} is still ${task.status}; check it again later`);
}
const waitSeconds = Number(resHeaders['retry-after']) || 5;
await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1000));
}
// 3. Download the result (only if the task succeeded)
if (task.status !== 'SUCCEEDED') {
throw new Error(`Task ${task.status}: ${task.task_error?.message || 'unknown error'}`);
}
const { data: model } = await axios.get(task.model_urls.glb, { responseType: 'arraybuffer' });
fs.writeFileSync('model.glb', model);
console.log('Saved model.glb');
探索常见工作流程
适用于游戏的角色
为类人体型 mesh 绑定骨骼,使其可以在 Unity 或 Unreal 中直接用于动画制作。
Learn more →Smart Topology mesh
在 Image to 3D 中将 model_type 设置为 smart-topology,即可获得干净、适用于游戏的三角形 mesh。
3D 打印模型
将完成的模型 Convert 为多色 3MF 文件,可直接用于切片和打印。
Learn more →