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

不要把 key 放进你的脚本里。应像下一步展示的那样,将其存储在环境变量中。
2创建一个 Image to 3D 任务
将一张图片发送给 Image to 3D。如果你想改为从文本 prompt 或多张照片开始,可以使用 Text to 3D 或 Multi-Image to 3D。
首先,将你的 key 存储到一个环境变量中:
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 请求头中指定的秒数。
关于典型处理时间,以及在放弃之前应等待多久,请参阅 Task lifecycle。
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": null
}
如果任务失败,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 打印模型
将已完成的模型转换为多色 3MF 文件,可直接切片并打印。
Learn more →