快速開始

從創建您的 API 金鑰開始

本指南中的每個請求都需要一個金鑰。創建金鑰不需要超過一分鐘。

創建您的 API 金鑰

四個步驟使用 Meshy REST API 完成您的第一個 3D 模型。


1獲取您的 API 金鑰

從您的帳戶設置中創建 API 金鑰 —— 您無法在此畫面後再次查看,因此請妥善保存。每個請求均使用 Authorization 標頭中的 Bearer token 進行身份驗證 —— 請參閱 身份驗證

從 API 菜單打開 API 設置,然後創建您的金鑰


2發起您的第一個影象生成 3D 請求

導出您的金鑰,然後使用 影象生成 3D 創建您的第一個任務。是否希望從文本 prompt 或多張照片工作?請參閱 文字生成 3D多圖生成 3D

導出您的金鑰

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

以下每個示例均使用此照片 —— 更換為您自己的 image_url 試試其他內容。

在本指南中用作影象生成 3D 輸入的示例貓照片
示例輸入

請求

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。輪詢同一個端點直到 statusSUCCEEDED —— 將下面的 <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": ""
  }
}

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
從示例貓照片生成的 3D 模型
您的結果

全部整合起來

更喜歡一個腳本完成所有事情——創建、輪詢、下載?

完整腳本

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. 創建任務
const { data: created } = await axios.post(
  'https://api.meshy.ai/openapi/v1/image-to-3d',
  { image_url: imageUrl },
  { headers },
);
const taskId = created.result;

// 2. 輪詢直到它完成
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. 下載結果
const { data: model } = await axios.get(task.model_urls.glb, { responseType: 'arraybuffer' });
fs.writeFileSync('model.glb', model);
console.log('已保存 model.glb');

探索常見工作流程


後續步驟

  • 更喜歡 UI?試試 API Playground —— 配置一個請求,運行它,並複製生成的代碼。
  • 瀏覽完整的 API 參考 以查看每個端點。
  • 在投入生產之前檢查 價格速率限制錯誤
  • 查看 更新日誌 獲取更新和錯誤修復。
  • 有反饋或遇到問題?加入我們的 Discord 社群 —— 我們樂意聽取您的意見!