快速开始
这是用于以编程方式与 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. Generate a preview model and get the task 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("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",
"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("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
你应该会在终端看到如下输出：
