lowpoly se retira el 30 oct 2026. Cambia de modelo antes de estas fechas para evitar errores en las solicitudes.

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 API

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 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.

Abre la página API Keys en la Developer Platform y luego crea tu clave


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

Cada ejemplo a continuación utiliza esta foto: sustituye tu propia image_url para probar con algo diferente.

Sample fantasy character illustration used as the Image to 3D input in this guide
Sample input

Request

POST
/openapi/v1/image-to-3d
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

GET
/openapi/v1/image-to-3d/:id
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": ""
  }
}

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

model_urls.glb
curl -L "<model_urls.glb from the response above>" -o model.glb
El modelo 3D resultante generado a partir de la foto de muestra del personaje de fantasía
Tu resultado

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


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!