Cómo usar la API de Image to 3D Model: Guía completa 2026

La API de Imagen a Modelo 3D convierte una sola foto en un modelo 3D listo para producción en segundos—sin necesidad de modelado manual. Modelar a mano cada activo es lento y costoso, y para estudios de juegos, aplicaciones de RA y equipos de comercio electrónico, rápidamente se convierte en el cuello de botella que retrasa los lanzamientos. La API de imagen a modelo 3D de Meshy elimina esa fricción: envía una imagen, conviértela en un modelo 3D en segundos y descarga una malla completamente texturizada en formatos como GLB, FBX y OBJ. Esta guía te lleva a través de todo el flujo de trabajo—desde crear tu clave API hasta descargar tu primer modelo—con código listo para copiar y pegar que puedes ejecutar en minutos.

¿Qué es la API de Imagen a Modelo 3D?

En esencia, la API de Imagen a Modelo 3D es un endpoint REST impulsado por la IA de imagen a modelo 3D de Meshy. Envías una sola imagen (JPG, JPEG o PNG) como una URL pública o cadena base64, y la API devuelve un modelo 3D texturizado—geometría y texturas de color base incluidas—en formatos estándar como GLB, FBX, OBJ, USDZ, STL y 3MF. Los complementos opcionales incluyen mapas PBR, texturas de hasta 4K y miniaturas de vista previa multiángulo.

Impulsada por nuestro último modelo Meshy 6, la API te permite configurar la topología y el recuento de polígonos, establecer modos de pose y guiar el texturizado con un prompt de texto o una imagen de referencia—ideal para generar activos para juegos, AR/VR, impresión 3D y visualización de productos.

¿Qué necesitas para usar la API de Imagen a 3D?

No necesitas mucho para seguir esta guía. Asegúrate de tener:

• Una cuenta de Meshy — regístrate gratis si no tienes una. Generarás tu clave API desde el panel en el Paso 1.

• Una clave API — se usa para autenticar cada solicitud. Te guiaremos en la creación de una, y puedes usar la clave de modo de prueba gratuita para seguir la guía sin gastar créditos.

• Una imagen de entrada — un .jpg, .jpeg o .png claro alojado en una URL de acceso público (o codificado como base64). Un fondo limpio y un sujeto claramente visible dan los mejores resultados.

• Una forma de hacer solicitudes HTTP — curl (usado en los ejemplos a continuación), Postman o cualquier biblioteca HTTP en el lenguaje de tu elección. La familiaridad básica con las API REST y JSON es útil pero no necesaria.

Eso es todo—no se necesita experiencia en modelado 3D. Empecemos.

Cómo convertir una imagen en un modelo 3D con la API (Guía paso a paso)

Paso 1: Configura tus ajustes de API

Todo lo que necesitas para empezar a construir está en la página de configuración de API. Este es tu centro de control para la API de Meshy y tiene tres secciones clave:

• Claves API — genera y gestiona las claves que autentican tus solicitudes.

• Webhooks — recibe notificaciones automáticas cuando tus tareas finalicen.

• Uso — rastrea tu saldo de crédito restante y el consumo de la API en tiempo real.

Repasemos cada una.

Obtén tu clave API

Antes de hacer cualquier solicitud, necesitas una clave API para autenticarte de forma segura. En la página de configuración de API, haz clic en Generar clave API. Cada clave sigue el formato msy-<cadena-aleatoria>.

Consejo: Una vez generada, guarda tu clave API en un lugar seguro (por ejemplo, un gestor de contraseñas o una variable de entorno). Trátala como una contraseña—nunca la subas al control de versiones ni la expongas en código del lado del cliente.

Clave API de modo de prueba

Durante el desarrollo y las pruebas, puedes usar la clave API de modo de prueba para explorar la API sin consumir tus créditos:

msy_dummy_api_key_for_test_mode_12345678

Esta clave especial tiene las siguientes características:

• Se puede usar para hacer solicitudes a todos los endpoints de la API de Meshy.

• No se consumen créditos al usar esta clave.

• Todas las solicitudes válidas devuelven el mismo resultado de tarea de muestra, independientemente de los parámetros de entrada.

• La estructura de datos de la respuesta coincide exactamente con la API de producción.

Esto la hace perfecta para probar tu integración antes de cambiar a tu clave API real.

Configurar webhooks (Opcional)

Generar un modelo 3D lleva tiempo, así que en lugar de sondear la API repetidamente para verificar si una tarea ha terminado, puedes dejar que Meshy te notifique en el momento en que finalice. Para eso sirven los webhooks.

En la sección Webhooks de la página de configuración, añade una URL de endpoint donde Meshy deba enviar las notificaciones de eventos. Cuando una tarea cambia de estado (por ejemplo, cuando se completa o falla), Meshy envía una solicitud HTTP POST a tu URL con los detalles de la tarea en el payload.

Consejo: Los webhooks son el enfoque recomendado para producción. Reducen las llamadas API innecesarias y permiten que tu aplicación reaccione a los resultados en tiempo real. Para pruebas rápidas, el sondeo sigue funcionando bien. Para probar el código de webhook localmente, apúntalo a una URL proxy de un servicio como smee.io.

Pruébalo sin código — API Playground (Opcional)

¿Ya tienes tu clave API? Antes de escribir código, puedes ejecutar una tarea real de Imagen a 3D directamente en tu navegador.

Abre meshy.ai/api-playground, selecciona Image to 3D en el panel izquierdo y completa tres cosas:

1. Authorization — pega tu clave API (msy-xxxxxxxxxx)

2. Image — sube un .jpg, .jpeg o .png desde tu computadora

3. Presiona Send

El Playground envía la tarea y sondea los resultados automáticamente. Una vez que termina, verás la vista previa del modelo 3D y los enlaces de descarga directamente en el navegador—sin necesidad de código.

Pro tip: El panel de solicitud/respuesta sin procesar a la derecha muestra exactamente lo que la API envía y devuelve. Puedes copiar el contenido directamente—toma el task_id de la respuesta y los model_urls una vez que la tarea finalice. Usarás ambos en los siguientes pasos.

Paso 2: Envía una tarea de Imagen a 3D

Con tu clave API lista, inicia una tarea con una sola solicitud POST:

curl -X POST https://api.meshy.ai/openapi/v1/image-to-3d \
  -H "Authorization: Bearer $MESHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/your-image.png"
  }'

Obtendrás una respuesta como esta:

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Ese valor de result es tu task_id — guárdalo. Lo necesitarás en el siguiente paso para verificar el progreso y recuperar tu modelo.

Opcional: Para recibir una notificación automática cuando la tarea finalice, añade un campo webhook_url al cuerpo JSON—por ejemplo "webhook_url": "https://yourapp.com/webhooks/meshy". Consulta el Paso 3, Opción B para ver cómo funciona.

Paso 3: Obtén tus resultados

Tu tarea no finaliza instantáneamente—Meshy la procesa en segundo plano. Tienes dos formas de obtener el resultado:

Opción A: Sondear el estado (La más simple)

Envía una solicitud GET cada 5 segundos hasta que status cambie a SUCCEEDED:

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

La respuesta se ve así:

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "SUCCEEDED",
  "progress": 100,
  "model_url": "https://assets.meshy.ai/.../model.glb",
  "model_urls": {
    "glb": "https://assets.meshy.ai/.../model.glb",
    "fbx": "https://assets.meshy.ai/.../model.fbx",
    "obj": "https://assets.meshy.ai/.../model.obj",
    "usdz": "https://assets.meshy.ai/.../model.usdz",
    "stl": "https://assets.meshy.ai/.../model.stl",
    "mtl": "https://assets.meshy.ai/.../model.mtl"
  },
  "thumbnail_url": "https://assets.meshy.ai/.../thumbnail.png",
  "consumed_credits": 30
}

Algunos campos que vale la pena conocer:

• model_urls contiene un enlace de descarga para cada formato generado. Por defecto, esto incluye glb, fbx, obj, usdz, stl y mtl (el archivo de material que se empareja con obj).

• model_url es un acceso directo al enlace GLB—útil cuando solo necesitas GLB.

• consumed_credits muestra cuántos créditos usó la tarea (es 0 para tareas fallidas, ya que los créditos se reembolsan).

• thumbnail_url siempre está presente y apunta a la miniatura de la vista frontal.

• thumbnail_urls aparece solo cuando multi_view_thumbnails: true, y contiene las vistas frontal, derecha, trasera e izquierda.

• alpha_thumbnail_url aparece solo cuando alpha_thumbnail: true, y contiene la miniatura con fondo transparente.

Posibles valores de status: PENDING → IN_PROGRESS → SUCCEEDED / FAILED / CANCELED

Opción B: Webhook (Recomendado para producción)

Si configuraste un webhook_url en el Paso 2, Meshy enviará el objeto de la tarea completada a tu URL automáticamente—sin necesidad de sondeo.

{
  "image_url": "https://example.com/your-image.png",
  "webhook_url": "https://yourapp.com/webhooks/meshy"
}

💡 ¿Cuál debería usar? El sondeo está bien para prototipos y tareas únicas. Usa webhooks en producción—es más confiable y ahorra llamadas API.

Paso 4: Descarga tu modelo 3D

Una vez que status sea SUCCEEDED, toma las URL de descarga de model_urls y descarga el formato que necesites:

curl -o model.glb "https://assets.meshy.ai/.../model.glb"

El flag -o model.glb guarda el archivo en tu directorio de trabajo actual con ese nombre—usa una ruta completa (ej. -o /path/to/model.glb) para guardarlo en otro lugar.

Por defecto, cada tarea devuelve GLB, FBX, OBJ, USDZ, STL y MTL (el archivo de material para OBJ). 3MF es opcional—solo lo obtienes cuando lo solicitas explícitamente a través de target_formats (consulta la tabla de parámetros a continuación).

⚠️ Los enlaces caducan en 3 días (los planes Enterprise obtienen enlaces permanentes). Descarga y almacena tus modelos rápidamente—los enlaces no funcionarán después de la caducidad y tendrás que volver a ejecutar la tarea.

¿Listo para usar este modelo en tu herramienta DCC? Consulta la guía Bridge to Blender—Meshy también tiene puentes para Unity, Unreal, Maya y más.

¿Cómo obtener los mejores resultados de imagen a 3D?

• Usa un solo sujeto claramente visible. Un objeto principal, centrado y completamente en el encuadre, le da a la IA la referencia más limpia—evita escenas ocupadas, recortes excesivos y ángulos extremos.

• Prefiere un fondo limpio y sin desorden. Los fondos sólidos o simples ayudan al modelo a separar el sujeto de su entorno.

• Usa una iluminación uniforme y difusa. Las sombras marcadas y los reflejos fuertes pueden incorporar detalles engañosos en la textura generada.

• Comienza con una imagen de alta resolución y nítida. Cuantos más detalles de entrada, más detalles de salida—las entradas borrosas o de baja resolución producen modelos más suaves.

¿Qué lenguajes de programación puedo usar con la API de Imagen a 3D?

Cualquier lenguaje que pueda hacer solicitudes HTTP—envías un POST con JSON y sondeas con GET. Opciones comunes:

• Python — usa la biblioteca requests o httpx

• JavaScript / TypeScript — usa fetch (integrado) o axios

• Go — usa net/http de la biblioteca estándar

• cURL — excelente para pruebas rápidas desde la terminal

También puedes encontrar ejemplos de código listos para copiar para los cuatro en el API Playground.

¿Cuántos créditos cuesta una tarea de Imagen a 3D?

El costo depende de la versión del modelo y de si generas texturas. La configuración predeterminada (meshy-6 con texturizado) cuesta 30 créditos por tarea:

Las tareas fallidas se reembolsan automáticamente—consumed_credits devuelve 0. Siempre consulta Precios para conocer las tarifas más recientes.

¿Qué parámetros acepta la API de Imagen a 3D?

Envía un POST a /openapi/v1/image-to-3d con estos parámetros: Requerido (uno de):

Opcional:

Próximos pasos con la API de Imagen a 3D

Ahora tienes el flujo de trabajo completo: crea una clave API, envía una imagen, sondea o usa un webhook para obtener el resultado, luego descarga tu modelo. Los mismos cuatro pasos escalan desde un prototipo rápido hasta un pipeline de producción que convierte miles de imágenes en activos 3D automáticamente. Obtén tu clave desde la página de configuración de API y lanza tu primer modelo hoy. ¿Prefieres empezar desde un prompt en lugar de una foto? Usa la API de Texto a Modelo 3D.

Preguntas frecuentes

¿Cómo convierto una imagen en un modelo 3D a través de la API?

Envía una solicitud POST a /openapi/v1/image-to-3d con tu image_url y clave API, luego sondea la tarea (o usa un webhook) hasta que su status sea SUCCEEDED. La respuesta devuelve enlaces de descarga para el modelo generado. El flujo completo de cuatro pasos—clave, envío, recuperación, descarga—se cubre en la guía paso a paso anterior.

¿Qué formatos de salida (STL, GLB, OBJ) admite la API?

Cada tarea devuelve GLB, FBX, OBJ, USDZ, STL y MTL por defecto, con 3MF disponible bajo petición a través de target_formats. GLB es mejor para web y RA, FBX y OBJ para herramientas DCC y motores de juegos, USDZ para RA en iOS y STL para impresión 3D.

¿Qué formatos de imagen puedo subir?

La API de Imagen a 3D admite imágenes JPG, JPEG y PNG de hasta 100 MB—más grande que el límite de 20 MB en la interfaz del Workspace de Meshy. Para obtener los resultados más precisos, usa un PNG con fondo transparente o blanco limpio, lo que ayuda a la API a aislar el sujeto y generar un modelo 3D de mayor calidad.

¿Puedo obtener un modelo 3D texturizado de la API?

Sí. El texturizado está habilitado por defecto ("should_texture": true). Para añadir mapas PBR (metálico, rugosidad, normal), establece "enable_pbr": true—en meshy-6/latest esto también incluye un mapa de emisión. Para una textura de color base de 4K, establece "hd_texture": true (compatible solo con meshy-6/latest; los mapas PBR se mantienen en 2K). También puedes dirigir el estilo de la textura con un texture_prompt o un texture_image_url.

¿Puedo generar un modelo 3D listo para impresión 3D (STL)?

Sí—STL se genera por defecto, por lo que una conversión de imagen a 3D STL no necesita parámetros adicionales: solo toma model_urls.stl cuando la tarea se complete. Esto hace que los flujos de trabajo de imagen a impresión 3D sean simples, ya que STL es el formato estándar que esperan los slicers. Si solo quieres STL, establece "target_formats": ["stl"] para omitir los otros formatos y reducir el tiempo de generación.

¿Qué planes incluyen acceso a la API?

El acceso a la API está disponible en los planes Pro, Studio y Enterprise—es una función de Pro y superiores. El plan Starter gratuito no incluye acceso a la API. Consulta Precios para más detalles.

¿Cuánto tiempo son válidos los enlaces de descarga?

Los enlaces de descarga son válidos durante 3 días en los planes Pro y Studio. Los clientes Enterprise obtienen enlaces permanentes. Guarda tus archivos rápidamente—los enlaces caducados no se pueden recuperar y tendrás que volver a ejecutar la tarea.

¿Puedo ejecutar varias tareas al mismo tiempo?

Sí, las solicitudes concurrentes son compatibles. Si recibes un error 429 Too Many Requests, tu cuenta ha alcanzado su límite de velocidad—implementa un backoff exponencial y reintenta. Consulta la página de Límites de velocidad para conocer los límites de tu plan.

La tarea muestra FAILED — ¿qué hago?

Revisa task_error.message para conocer la causa. Algunas comunes:

Si el problema persiste, contacta al soporte de Meshy.