Inicio rápido
Esta es la referencia de API para interactuar programáticamente con Meshy.
¿Usas un asistente de codificación con IA? Consulta nuestra página de Integración con IA: instala el MCP server de Meshy para obtener acceso mediante llamadas a herramientas desde Claude Code, Cursor, Windsurf y otras herramientas compatibles con MCP, o dirige un agente de chat simple a llms.txt.
La Meshy API proporciona una interfaz sencilla para generar modelos 3D y texturas a partir de prompts de texto e imágenes. Sigue esta guía para empezar rápidamente.
Crear una clave de API
Crea una clave de API en la página de configuración de API aquí, que usarás para autenticar tus solicitudes de forma segura. El formato de la clave de API es msy-<random-string>.
Una vez que hayas generado una clave de API, guárdala en un lugar seguro.
Clave de API en modo de prueba
Durante el desarrollo y las pruebas, puedes usar nuestra clave de API en modo de prueba para explorar la API sin consumir tus créditos:
msy_dummy_api_key_for_test_mode_12345678
Esta clave de API especial tiene las siguientes características:
- Puede usarse para realizar solicitudes a todos los endpoints de la Meshy API
- No se consumen créditos al usar esta clave
- Todas las solicitudes válidas devolverán los mismos resultados de tarea de ejemplo, independientemente de los parámetros de entrada
- La estructura de datos de la respuesta coincidirá exactamente con la API de producción
- Perfecta para probar tu integración de API antes de cambiar a tu clave de API real
La clave de API en modo de prueba es solo para fines de desarrollo. Para uso en producción, utiliza tu propia clave de API.
Realizar tu primera solicitud de API de "Texto a 3D"
En este ejemplo, generaremos un modelo 3D a partir de un prompt de texto usando el text-to-3d endpoint. El proceso consta de dos etapas: la etapa de vista previa y la etapa de refinamiento. En la etapa de vista previa, se genera una malla base sin ninguna textura aplicada, lo que te permite evaluar la geometría. En la etapa de refinamiento, se aplica textura a la malla de vista previa según el prompt de texto.
Te mostraremos cómo realizar estas solicitudes en un script de Python.
Vista previa
Meshy proporciona un conjunto de endpoints de API REST. Puedes usarlos con cualquier cliente HTTP de tu elección. Independientemente de la API que llames, la clave de API siempre se pasa como un encabezado llamado Authorization. Recuerda exportar tu clave de API como una variable de entorno llamada MESHY_API_KEY antes de usar este script.
Los parámetros clave de la solicitud de vista previa son mode, que siempre es "preview", y prompt, una descripción del modelo que necesitas. En este ejemplo, también hemos especificado should_remesh, pero es opcional.
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)
Esto completa la llamada a la API de vista previa.
Ten en cuenta que la Meshy API adopta un modelo de ejecución asíncrona, lo que significa que cuando creas una tarea, el endpoint de API solo devuelve un ID de tarea. Luego debes sondear el endpoint de estado de la tarea con este ID para comprobar si la tarea ha finalizado.
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)
Una vez que la tarea haya finalizado, podrás acceder a las URLs del modelo desde su respuesta. Descarguemos el modelo desde el campo model_urls en la respuesta.
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.")
Si todo funciona correctamente hasta ahora, tu preview_model.glb debería verse similar a esto. No será una coincidencia exacta, debido a la aleatoriedad intrínseca del flujo de IA.
Refinamiento
Procedamos a la etapa de refinamiento. Para iniciar la solicitud de refinamiento, proporciona el ID de la tarea de vista previa como parámetro de entrada.
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.")
El modelo 3D refined_model.glb ahora tiene la textura completa ✨.
Unirlo todo
Aquí tienes el código completo para usar la API de Texto a 3D.
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.")
Copia y pega el código en un script de Python y ejecútalo.
Run the script
python api_request.py
Deberías ver una salida en tu terminal como la siguiente:
Siguientes pasos
- ¿Prefieres probar endpoints sin escribir código primero? Usa el API Playground para configurar y ejecutar una solicitud, luego copia el fragmento generado.
- Puedes encontrar la referencia completa de la API en la sección "Endpoints de API", que proporciona información detallada sobre cada API.
- Explora detalles sobre Precios, límites de tasa y cómo solucionar errores comunes.
- No olvides consultar nuestro registro de cambios regularmente para ver actualizaciones y correcciones de errores.
- ¿Tienes comentarios o estás enfrentando problemas? Únete a nuestra comunidad de Discord; ¡nos encantaría saber de ti!