Inicio rápido
Empieza creando tu clave de API
Cada solicitud de esta guía necesita una. Crear una clave toma segundos.
Crea tu clave de APICrea tu primer modelo 3D con la API REST de Meshy en cuatro pasos, desde crear una clave de API hasta descargar el 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 soporte de MCP, usa llms.txt.
1Obtén tu clave de API
Crea una clave de API en la página de 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 tus propias claves, y el Playground usa una clave integrada para pruebas.

Mantén la clave fuera de tus scripts. Guárdala en una variable de entorno, como se muestra en el siguiente paso.
2Crea una tarea de Imagen a 3D
Envía una imagen a Imagen a 3D. Para empezar en su lugar con un prompt de texto o varias fotos, 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"
}'
3Comprueba el estado de la tarea
La tarea se ejecuta en segundo plano y suele tardar 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 la cantidad de segundos indicada en el encabezado Retry-After.
Para conocer los tiempos de procesamiento típicos y cuánto 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": null
}
Si la tarea falla, status será FAILED, y task_error indicará el motivo. Corrige la entrada o crea otra tarea. Consulta Errores.
Para recibir una notificación cuando la tarea termine en lugar de hacer polling, 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 finalice 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');
Explora flujos de trabajo comunes
Personaje listo para el juego
Aplica rigging a una malla humanoide con un esqueleto para que esté lista para animarse en Unity o Unreal.
Learn more →Malla con Smart Topology
Configura model_type como smart-topology en Imagen a 3D para obtener una malla de triángulos limpia y lista para el juego.
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 cada endpoint en la referencia de la API.
- Antes de pasar a producción, consulta Precios, Límites de tasa y Errores.
- Sigue recetas paso a paso en el Cookbook.