快速开始
这是用于以编程方式与 Meshy 交互的 API 参考。
Meshy API 提供了一个简单的界面，可以从文本提示和图像生成 3D 模型和纹理。请按照本指南快速入门。
创建 API 密钥
在此处的 API 设置页面中创建 API 密钥，您将使用它来安全地验证您的请求。API 密钥的格式为 msy-<random-string>。
一旦生成了 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 端点 从文本提示生成 3D 模型。该过程包括两个阶段：预览阶段和细化阶段。在预览阶段，生成一个没有纹理的基础网格，允许您评估几何形状。在细化阶段，预览网格根据文本提示进行纹理化。
我们将向您展示如何在 Python 脚本中发出这些请求。
预览
Meshy 提供了一组 REST API 端点。您可以使用任何您选择的 HTTP 客户端使用它们。无论调用哪个 API，API 密钥始终作为名为 Authorization 的标头传递。请记住在使用此脚本之前将您的 API 密钥导出为名为 MESHY_API_KEY 的环境变量。
预览请求的关键参数是 mode，始终为 "preview"，以及 prompt，即您需要的模型描述。在此示例中，我们还指定了 negative_prompt、art_style 和 should_remesh，但它们是可选的。
api_request.py
import requests
import os
import time
headers = {
"Authorization": f"Bearer {os.environ['MESHY_API_KEY']}"
}
# 1. 生成预览模型并获取任务 ID
generate_preview_request = {
"mode": "preview",
"prompt": "a monster mask",
"negative_prompt": "low quality, low resolution, low poly, ugly",
"art_style": "realistic",
"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("预览任务已创建。任务 ID:", preview_task_id)
这完成了预览 API 调用。
请注意，Meshy API 采用异步执行模型，这意味着当您创建任务时，API 端点仅返回任务 ID。然后您必须使用此 ID 轮询任务状态端点以检查任务是否已完成。
api_request.py
# 2. 轮询预览任务状态直到完成
preview_task = None
while True:
preview_task_response = requests.get(
一旦任务完成，您将能够从其响应中访问模型的URL。让我们从响应中的 `model_urls` 字段下载模型。
如果到目前为止一切正常，您的 `preview_model.glb` 应该看起来与此类似。由于AI管道中的内在随机性，它不会完全匹配。
### 精细化
让我们继续进行精细化阶段。要启动精细化请求，请提供预览任务ID作为输入参数。
已创建精细化任务。任务ID：
### 整合
以下是使用文本生成3D API的完整代码。
如果 preview_task["status"] == "SUCCEEDED":
print("预览任务已完成。")
break
print("预览任务状态:", preview_task["status"], "| 进度:", preview_task["progress"], "| 5秒后重试...")
time.sleep(5)
# 3. 下载 glb 格式的预览模型
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("预览模型已下载。")
# 4. 生成精炼模型并获取任务 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("精炼任务已创建。任务 ID:", refined_task_id)
# 5. 轮询精炼任务状态直到完成
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("精炼任务已完成。")
break
print("精炼任务状态:", refined_task["status"], "| 进度:", refined_task["progress"], "| 5秒后重试...")
time.sleep(5)
# 6. 下载 glb 格式的精炼模型
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("精炼模型已下载。")
将代码复制并粘贴到 Python 脚本中并运行。
运行脚本
python api_request.py
你应该会在终端看到如下输出：
