快速開始

首先建立你的 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.cn/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.cn/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——我們很樂意聽取你的意見！