快速開始

這是用於以程式方式與 Meshy 互動的 API 參考文件。

正在使用 AI 程式設計助理？ 請參閱我們的 AI 整合 頁面 — 安裝 Meshy MCP 伺服器，以便從 Claude Code、Cursor、Windsurf 等 MCP 相容工具進行工具呼叫存取，或將一般聊天代理指向 llms.txt。

Meshy API 提供了一個簡單的介面，可以從文字 prompt 和圖片生成 3D 模型與紋理。請依照本指南快速入門。

建立 API 金鑰

在此處的 API 設定頁面中建立 API 金鑰，您將使用它來安全地驗證您的請求。API 金鑰的格式為 msy-<random-string>。

產生 API 金鑰

一旦產生了 API 金鑰，請將其儲存在安全的位置。

測試模式 API 金鑰

在開發和測試期間，您可以使用我們的測試模式 API 金鑰來探索 API，而不消耗您的點數：

msy_dummy_api_key_for_test_mode_12345678

此特殊 API 金鑰具有以下特性：

  • 可用於向所有 Meshy API 端點發出請求
  • 使用此金鑰時不會消耗點數
  • 所有有效請求都會傳回相同的範例任務結果，無論輸入參數為何
  • 回應資料結構將與正式環境 API 完全相符
  • 非常適合在切換到真實 API 金鑰之前測試您的 API 整合

測試模式 API 金鑰僅供開發用途。正式環境使用時，請使用您自己的 API 金鑰。

發出您的第一個「文字生成 3D」API 請求

在此範例中，我們將使用 text-to-3d 端點 從文字 prompt 生成 3D 模型。此流程包含兩個階段：預覽階段和細化階段。在預覽階段，會生成一個沒有紋理的基礎網格，讓您評估幾何形狀。在細化階段，會根據文字 prompt 對預覽網格套用紋理。

我們將向您示範如何在 Python 指令碼中發出這些請求。

預覽

Meshy 提供了一組 REST API 端點。您可以使用任何您選擇的 HTTP 用戶端來使用它們。無論呼叫哪個 API，API 金鑰一律會作為名為 Authorization 的標頭傳遞。請記得在使用此指令碼之前，將您的 API 金鑰匯出為名為 MESHY_API_KEY 的環境變數。

預覽請求的關鍵參數是 mode，一律為 "preview"，以及 prompt，也就是您需要的模型描述。在此範例中，我們也指定了 should_remesh，但它是選用的。

api_request.py

import requests
import os
import time

headers = {
  "Authorization": f"Bearer {os.environ['MESHY_API_KEY']}"
}

# 1. Generate a preview model and get the task ID

generate_preview_request = {
  "mode": "preview",
  "prompt": "a monster mask",
  "should_remesh": True,
}

generate_preview_response = requests.post(
  "https://api.meshy.ai/openapi/v2/text-to-3d",
  headers=headers,
  json=generate_preview_request,
)

generate_preview_response.raise_for_status()

preview_task_id = generate_preview_response.json()["result"]

print("Preview task created. Task ID:", preview_task_id)

這就完成了預覽 API 呼叫。

請注意，Meshy API 採用非同步執行模型，這表示當您建立任務時，API 端點只會傳回任務 ID。接著您必須使用此 ID 輪詢任務狀態端點，以檢查任務是否已完成。

api_request.py

# 2. Poll the preview task status until it's finished

preview_task = None

while True:
  preview_task_response = requests.get(
    f"https://api.meshy.ai/openapi/v2/text-to-3d/{preview_task_id}",
    headers=headers,
  )

  preview_task_response.raise_for_status()

  preview_task = preview_task_response.json()

  if preview_task["status"] == "SUCCEEDED":
    print("Preview task finished.")
    break

  print("Preview task status:", preview_task["status"], "| Progress:", preview_task["progress"], "| Retrying in 5 seconds...")
  time.sleep(5)

任務完成後，您就能從其回應中存取模型的 URL。讓我們從回應中的 model_urls 欄位下載模型。

api_request.py

# 3. Download the preview model in glb format

preview_model_url = preview_task["model_urls"]["glb"]

preview_model_response = requests.get(preview_model_url)
preview_model_response.raise_for_status()

with open("preview_model.glb", "wb") as f:
  f.write(preview_model_response.content)

print("Preview model downloaded.")

如果到目前為止一切正常，您的 preview_model.glb 應該會看起來與此類似。由於 AI 管線中的內在隨機性，它不會完全相同。

預覽模型

細化

讓我們繼續進行細化階段。若要啟動細化請求，請提供預覽任務 ID 作為輸入參數。

api_request.py

# 4. Generate a refined model and get the task ID

generate_refined_request = {
  "mode": "refine",
  "preview_task_id": preview_task_id,
}

generate_refined_response = requests.post(
  "https://api.meshy.ai/openapi/v2/text-to-3d",
  headers=headers,
  json=generate_refined_request,
)

generate_refined_response.raise_for_status()

refined_task_id = generate_refined_response.json()["result"]

print("Refined task created. Task ID:", refined_task_id)

# 5. Poll the refined task status until it's finished

refined_task = None

while True:
  refined_task_response = requests.get(
    f"https://api.meshy.ai/openapi/v2/text-to-3d/{refined_task_id}",
    headers=headers,
  )

  refined_task_response.raise_for_status()

  refined_task = refined_task_response.json()

  if refined_task["status"] == "SUCCEEDED":
    print("Refined task finished.")
    break

  print("Refined task status:", refined_task["status"], "| Progress:", refined_task["progress"], "| Retrying in 5 seconds...")
  time.sleep(5)

# 6. Download the refined model in glb format

refined_model_url = refined_task["model_urls"]["glb"]

refined_model_response = requests.get(refined_model_url)
refined_model_response.raise_for_status()

with open("refined_model.glb", "wb") as f:
  f.write(refined_model_response.content)

print("Refined model downloaded.")

3D 模型 refined_model.glb 現在已完整套用紋理 ✨。

細化模型

整合

以下是使用文字生成 3D API 的完整程式碼。

api_request.py

import requests
import os
import time

headers = {
  "Authorization": f"Bearer {os.environ['MESHY_API_KEY']}"
}

# 1. Generate a preview model and get the task ID

generate_preview_request = {
  "mode": "preview",
  "prompt": "a monster mask",
  "should_remesh": True,
}

generate_preview_response = requests.post(
  "https://api.meshy.ai/openapi/v2/text-to-3d",
  headers=headers,
  json=generate_preview_request,
)

generate_preview_response.raise_for_status()

preview_task_id = generate_preview_response.json()["result"]

print("Preview task created. Task ID:", preview_task_id)

# 2. Poll the preview task status until it's finished

preview_task = None

while True:
  preview_task_response = requests.get(
    f"https://api.meshy.ai/openapi/v2/text-to-3d/{preview_task_id}",
    headers=headers,
  )

  preview_task_response.raise_for_status()

  preview_task = preview_task_response.json()

  if preview_task["status"] == "SUCCEEDED":
    print("Preview task finished.")
    break

  print("Preview task status:", preview_task["status"], "| Progress:", preview_task["progress"], "| Retrying in 5 seconds...")
  time.sleep(5)

# 3. Download the preview model in glb format

preview_model_url = preview_task["model_urls"]["glb"]

preview_model_response = requests.get(preview_model_url)
preview_model_response.raise_for_status()

with open("preview_model.glb", "wb") as f:
  f.write(preview_model_response.content)

print("Preview model downloaded.")

# 4. Generate a refined model and get the task ID

generate_refined_request = {
  "mode": "refine",
  "preview_task_id": preview_task_id,
}

generate_refined_response = requests.post(
  "https://api.meshy.ai/openapi/v2/text-to-3d",
  headers=headers,
  json=generate_refined_request,
)

generate_refined_response.raise_for_status()

refined_task_id = generate_refined_response.json()["result"]

print("Refined task created. Task ID:", refined_task_id)

# 5. Poll the refined task status until it's finished

refined_task = None

while True:
  refined_task_response = requests.get(
    f"https://api.meshy.ai/openapi/v2/text-to-3d/{refined_task_id}",
    headers=headers,
  )

  refined_task_response.raise_for_status()

  refined_task = refined_task_response.json()

  if refined_task["status"] == "SUCCEEDED":
    print("Refined task finished.")
    break

  print("Refined task status:", refined_task["status"], "| Progress:", refined_task["progress"], "| Retrying in 5 seconds...")
  time.sleep(5)

# 6. Download the refined model in glb format

refined_model_url = refined_task["model_urls"]["glb"]

refined_model_response = requests.get(refined_model_url)
refined_model_response.raise_for_status()

with open("refined_model.glb", "wb") as f:
  f.write(refined_model_response.content)

print("Refined model downloaded.")

將程式碼複製並貼到 Python 指令碼中，然後執行。

运行脚本

python api_request.py

您應該會在終端機看到如下輸出：

執行指令碼

下一步

  • 想先在不寫程式碼的情況下試用各個端點？使用 API Playground 設定並執行請求，然後複製產生的程式碼片段。
  • 您可以在 "API 端點" 區段找到完整的 API 參考文件，其中提供了每個 API 的詳細資訊。
  • 探索有關 定價、速率限制 的詳細資訊，以及如何排查 常見錯誤。
  • 別忘了定期查看我們的 更新日誌，以取得更新和錯誤修正。
  • 有意見回饋或遇到問題？加入我們的 Discord 社群 - 我們期待聽到您的聲音！