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

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 API

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


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.

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


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

Los siguientes ejemplos usan todos esta foto. Para probar con otra imagen, cambia image_url.

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

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

Si la tarea falla, status es FAILED, y task_error indica el motivo. Corrige la entrada o crea otra tarea. Consulta Errores.


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

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

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


Próximos pasos