快速开始

首先创建你的 API key

本指南中的每个请求都需要用到它。创建密钥只需不到一分钟。

使用 Meshy REST API，仅需四步即可生成你的第一个 3D 模型。

正在使用 AI 编程助手？ 参阅我们的 AI 集成页面——安装 Meshy MCP server，即可通过 Claude Code、Cursor、Windsurf 及其他兼容 MCP 的工具进行调用，或者让普通的聊天代理读取 llms.txt。

1获取你的 API key

在账户设置中创建一个 API key——离开该页面后你将无法再次查看它，因此请妥善保存。每个请求都通过 Authorization 请求头中的 Bearer 令牌进行 authentication——参阅 Authentication。

从 API 菜单打开 API Settings，然后创建你的密钥

安全提示： 避免将密钥直接粘贴到脚本中——建议将其存储为环境变量：export MESHY_API_KEY="msy_..."。

2发起你的第一个 Image-to-3D 请求

导出你的密钥，然后使用 Image to 3D 创建你的第一个任务。想要基于文本 prompt 或多张照片进行操作？请参阅 Text to 3D 或 Multi-Image to 3D。

导出你的密钥

export MESHY_API_KEY="<your-api-key>"

请在终端（macOS 上的 Terminal，Windows 上的 Command Prompt 或 PowerShell）中运行此命令——而不是在浏览器中。

下面的每个示例都使用了这张照片——你可以替换成自己的 image_url 来尝试其他内容。

请求

POST

/openapi/v1/image-to-3d

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检查任务状态

请求会立即返回一个任务 ID。请轮询同一个 endpoint，直到 status 变为 SUCCEEDED——将下方的 <task_id> 替换为步骤 2 中返回的 ID。

请求

GET

/openapi/v1/image-to-3d/:id

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

响应 — 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": ""
  }
}

不喜欢轮询？可以使用 SSE 流式传输或 webhook，在任务完成的瞬间收到通知。

4下载你的模型

从上方响应的 model_urls 中获取模型。每种格式（GLB、FBX、OBJ、USDZ、STL）都是一个带签名、有时效限制的 URL——你也可以跳过命令行，直接将该 URL 粘贴到浏览器地址栏中进行下载。

下载

model_urls.glb

curl -L "<model_urls.glb from the response above>" -o model.glb

在非 Enterprise 套餐中，文件会保留 3 天——参阅 Asset Retention。

整合到一起

想要用一段脚本完成整个流程——创建、轮询、下载？

完整脚本

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 },
);
const taskId = created.result;

// 2. Poll until it finishes
let task;
while (true) {
  const { data } = await axios.get(`https://api.meshy.ai/openapi/v1/image-to-3d/${taskId}`, { headers });
  task = data;
  if (task.status === 'SUCCEEDED' || task.status === 'FAILED') break;
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

// 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');

后续步骤

更喜欢图形界面？试试 API Playground——配置一个请求、运行它，并复制生成的代码。
浏览完整的 API 参考文档，查看每个 endpoint。
在正式投入生产环境之前，请查阅 Pricing、Rate Limits 和 Errors。
关注更新日志，了解更新和错误修复情况。
有反馈或遇到问题？加入我们的 Discord community——我们很乐意听取你的意见！