Inicio rápido
Empieza creando tu clave de API
Cada solicitud de esta guía la necesita. Crear una clave lleva solo unos segundos.
Crea tu clave de APICrea tu primer modelo 3D con la API REST de Meshy en cuatro pasos, desde la creación de una clave de API hasta la descarga del modelo.
¿Usas un asistente de codificación con IA? Para conectar Claude Code, Cursor, Windsurf u otro cliente MCP a Meshy, consulta Integración con IA. Para un agente de chat sin compatibilidad con MCP, usa llms.txt.
1Obtén tu clave de API
Crea una clave de API en la página API Keys de la Developer Platform. No podrás volver a ver la clave después de salir de esa pantalla, así que guárdala en un lugar seguro. Envíala en cada solicitud como un token Bearer en el encabezado Authorization. Consulta Autenticación.
Necesitas un plan de pago para crear y gestionar claves de API. En el plan gratuito no puedes crear claves propias, y el Playground usa una clave integrada para realizar pruebas.

Mantén la clave fuera de tus scripts. Guárdala en una variable de entorno, tal como se muestra en el siguiente paso.
2Crea una tarea de Imagen a 3D
Envía una imagen a Imagen a 3D. Para empezar a partir de un prompt de texto o de varias fotos en su lugar, usa Texto a 3D o Multi-imagen a 3D.
Primero, guarda tu clave en una variable de entorno:
Export your key
export MESHY_API_KEY="<your-api-key>"
Ejecuta esto en tu terminal (Terminal en macOS, Símbolo del sistema o PowerShell en Windows), no en un navegador.
Los siguientes ejemplos usan todos esta foto. Para probar con otra imagen, cambia image_url.

Request
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"
}'
3Comprobar el estado de la tarea
La tarea se ejecuta en segundo plano y normalmente tarda unos minutos. Obtén la tarea desde el mismo endpoint hasta que status sea SUCCEEDED, FAILED o CANCELED. En la siguiente solicitud, reemplaza <task_id> con el ID que devolvió el paso 2. Entre solicitudes, espera el número de segundos indicado en el encabezado Retry-After.
Para conocer los tiempos de procesamiento habituales y cuánto tiempo esperar antes de desistir, consulta Ciclo de vida de la tarea.
Request
curl https://api.meshy.ai/openapi/v1/image-to-3d/<task_id> \
-H "Authorization: Bearer ${MESHY_API_KEY}"
Response: 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": ""
}
}
Si la tarea falla, status es FAILED, y task_error indica el motivo. Corrige la entrada o crea otra tarea. Consulta Errores.
Para recibir una notificación cuando la tarea termine en lugar de hacer sondeos, transmite la tarea o usa un webhook.
4Descarga tu modelo
Los archivos están en model_urls de la respuesta anterior. Cada formato (GLB, FBX, OBJ, USDZ y STL) tiene una URL firmada que funciona durante un tiempo limitado. También puedes pegar la URL en tu navegador para descargar el archivo.
Download
curl -L "<model_urls.glb from the response above>" -o model.glb

En todos los planes excepto Enterprise, Meshy conserva los archivos durante 3 días. Descarga los archivos que necesites antes de ese plazo. Consulta Retención de recursos.
Pon todo junto
Este script crea la tarea, espera a que termine y descarga el modelo.
Full script
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. Create the task
const { data: created } = await axios.post(
'https://api.meshy.ai/openapi/v1/image-to-3d',
{ image_url: imageUrl },
{ headers, timeout: 60_000 },
);
const taskId = created.result;
// 2. Poll until it finishes, for up to 60 minutes
const deadline = Date.now() + 60 * 60 * 1000;
let task;
while (true) {
const { data, headers: resHeaders } = await axios.get(
`https://api.meshy.ai/openapi/v1/image-to-3d/${taskId}`,
{ headers, timeout: 30_000 },
);
task = data;
if (['SUCCEEDED', 'FAILED', 'CANCELED'].includes(task.status)) break;
if (Date.now() > deadline) {
// The task is still running. Check it again later with the same task ID instead of creating a new one.
throw new Error(`Task ${taskId} is still ${task.status}; check it again later`);
}
const waitSeconds = Number(resHeaders['retry-after']) || 5;
await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1000));
}
// 3. Download the result (only if the task succeeded)
if (task.status !== 'SUCCEEDED') {
throw new Error(`Task ${task.status}: ${task.task_error?.message || 'unknown error'}`);
}
const { data: model } = await axios.get(task.model_urls.glb, { responseType: 'arraybuffer' });
fs.writeFileSync('model.glb', model);
console.log('Saved model.glb');
Explore common workflows
Personaje listo para videojuegos
Aplica un rig a una malla humanoide con un esqueleto para que esté lista para animarse en Unity o Unreal.
Learn more →Malla de Smart Topology
Establece model_type en smart-topology en Imagen a 3D para obtener una malla de triángulos limpia y lista para videojuegos.
Modelo para impresión 3D
Convierte un modelo terminado en un archivo 3MF multicolor, listo para laminar e imprimir.
Learn more →Próximos pasos
- Explora todos los endpoints en la referencia de la API.
- Antes de pasar a producción, revisa Precios, Límites de velocidad y Errores.
- Sigue las recetas paso a paso en el Cookbook.