快速開始
先建立你的 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 →