Inicio rápido

Comienza creando tu clave de API

Cada solicitud en esta guía necesita una. Crear una clave toma menos de un minuto.

Crea tu clave de API

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


1Obtén tu clave de API

Crea una clave de API desde la configuración de tu cuenta — no podrás verla de nuevo 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.

Abre la configuración de API desde el menú de API, luego crea tu clave


2Haz tu primera solicitud de Imagen a 3D

Exporta tu clave, luego crea tu primera tarea con Imagen a 3D. ¿Trabajando desde un prompt de texto o múltiples fotos? Consulta Texto a 3D o Multi-imagen a 3D.

Exporta tu clave

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

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

Ilustración de personaje de fantasía de muestra utilizada como entrada de Imagen a 3D en esta guía
Entrada de muestra

Solicitud

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

3Verifica el estado de la tarea

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

Solicitud

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

Respuesta — 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 de model_urls en la respuesta anterior. Cada formato (GLB, FBX, OBJ, USDZ, STL) es una URL firmada y con tiempo limitado — o salta la línea de comandos y pega la URL directamente en la barra de direcciones de tu navegador para descargarlo.

Descargar

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 personaje de fantasía de muestra
Tu resultado

Ponlo todo junto

¿Prefieres un script que haga todo — crear, consultar, descargar?

Script completo

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 } = await axios.get(`https://api.meshy.ai/openapi/v1/image-to-3d/${taskId}`, { headers });
  task = data;
  if (task.status === 'SUCCEEDED' || task.status === 'FAILED') break;
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

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