Inicio rápido

Cuatro pasos para obtener tu primer modelo 3D, usando la API REST de Meshy.

1Obtén tu clave de API

Crea una clave de API desde la página API Keys en la Plataforma para Desarrolladores — 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 Autenticación.

2Realiza tu primera solicitud de Imagen a 3D

Exporta tu clave y luego crea tu primera tarea con Imagen a 3D. ¿Prefieres trabajar con un prompt de texto o con varias fotos? Consulta Texto a 3D o Multi-imagen a 3D.

export MESHY_API_KEY="<your-api-key>"

Cada ejemplo a continuación usa esta foto — sustituye con tu propio image_url para probar algo diferente.

Copy image URL

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"
  }'

3Verifica el estado de la tarea

Las solicitudes devuelven un ID de tarea de inmediato. Consulta el mismo endpoint repetidamente hasta que status sea SUCCEEDED — reemplaza <task_id> a continuación con el ID devuelto en el paso 2.

curl https://api.meshy.ai/openapi/v1/image-to-3d/<task_id> \
  -H "Authorization: Bearer ${MESHY_API_KEY}"

{
  "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": ""
  }
}

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 con tiempo limitado — o puedes omitir la línea de comandos y pegar la URL directamente en la barra de direcciones de tu navegador para descargarla.

curl -L "<model_urls.glb from the response above>" -o model.glb

Júntalo todo

¿Prefieres un solo script que haga todo el proceso: crear, consultar, descargar?

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 },
);
const taskId = created.result;

// 2. Poll until it finishes
let task;
while (true) {
  const { data, headers: resHeaders } = await axios.get(`https://api.meshy.ai/openapi/v1/image-to-3d/${taskId}`, { headers });
  task = data;
  if (task.status === 'SUCCEEDED' || task.status === 'FAILED') break;
  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

Próximos pasos

• ¿Prefieres una interfaz gráfica? Abre la Plataforma para Desarrolladores — ejecuta solicitudes en el Playground, haz seguimiento del uso y de los registros de solicitudes, y gestiona webhooks.
• Explora la referencia completa de la API para conocer cada endpoint.
• Aprende con ejemplos prácticos: sigue recetas paso a paso en el Cookbook y lee tutoriales e historias de desarrollo en el Blog para Desarrolladores.
• Revisa Precios, Límites de velocidad 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!