Inicio rápido
Comienza creando tu clave de API
Cada solicitud de esta guía necesita una. Crear una clave toma solo segundos.
Crea tu clave de APICuatro pasos para obtener tu primer modelo 3D, usando la API REST de 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 de llamada a herramientas desde Claude Code, Cursor, Windsurf y otras herramientas compatibles con MCP, o dirige un agente de chat simple a llms.txt.
1Obtén tu clave de API
Crea una clave de API desde la página API Keys en la Developer Platform — no podrás volver a verla después de esta pantalla, así que guárdala en un lugar seguro. Cada solicitud se autentica con un token Bearer en el encabezado Authorization — consulta Authentication.
Crear y gestionar claves de API requiere un plan de pago. Las cuentas gratuitas obtienen una clave dedicada e integrada para realizar pruebas en el Playground, pero no pueden crear ni gestionar sus propias claves.

Consejo de seguridad: evita pegar tu clave directamente en scripts — en su lugar, guárdala como una variable de entorno: export MESHY_API_KEY="msy_...".
2Realiza tu primera solicitud de Imagen a 3D
Exporta tu clave y luego crea tu primera tarea con Image to 3D. ¿Prefieres trabajar a partir de un prompt de texto o de varias fotos? Consulta Text to 3D o Multi-Image to 3D.
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.
Cada ejemplo a continuación utiliza esta foto: sustituye tu propia image_url para probar con algo diferente.

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. Sondea el mismo endpoint hasta que status sea SUCCEEDED, FAILED o CANCELED, reemplazando <task_id> a continuación con el ID devuelto en el paso 2. Para conocer los tiempos habituales y cuánto hay que esperar, 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": ""
}
}
¿El sondeo no es tu estilo? Usa streaming SSE o un webhook para recibir una notificación en el momento en que finalice una tarea.
4Descarga tu modelo
Obtén el modelo desde model_urls en la respuesta anterior. Cada formato (GLB, FBX, OBJ, USDZ, STL) es una URL firmada y de tiempo limitado; o bien, en lugar de usar la línea de comandos, pega la URL directamente en la barra de direcciones de tu navegador para descargarlo.
Download
curl -L "<model_urls.glb from the response above>" -o model.glb

Los archivos se conservan durante 3 días en los planes que no son Enterprise; consulta Retención de recursos.
Pongámoslo todo junto
¿Prefieres un solo script que haga todo el proceso: crear, consultar el estado y descargar?
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');
Explorar flujos de trabajo comunes
Personaje listo para el juego
Aplica rigging a una malla humanoide con un esqueleto para que esté lista para animar en Unity o Unreal.
Learn more →Asset lowpoly
Configura model_type como smart-topology en Imagen a 3D para obtener una malla 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
- ¿Prefieres una interfaz gráfica? Abre la Developer Platform — ejecuta solicitudes en el Playground, haz seguimiento del uso y de los registros de solicitudes, y gestiona webhooks.
- Explora la referencia de la API completa para cada endpoint.
- Aprende con ejemplos prácticos: sigue las recetas paso a paso en el Cookbook y lee tutoriales e historias de desarrollo en el Developer Blog.
- Consulta Precios, Rate Limits y Errores antes de pasar a producción.
- Consulta el registro de cambios para ver actualizaciones y correcciones de errores.
- ¿Tienes comentarios o problemas? Únete a nuestra comunidad de Discord — ¡nos encantaría saber de ti!