API Imagen a 3D

La API Imagen a 3D es una característica que te permite integrar las capacidades de Imagen a 3D de Meshy en tu propia aplicación. En esta sección, encontrarás toda la información que necesitas para empezar a utilizar esta API.

POST/openapi/v1/image-to-3d

Crear una Tarea de Imagen a 3D

Este endpoint te permite crear una nueva tarea de Imagen a 3D. Consulta el El Objeto de Tarea de Imagen a 3D para ver qué propiedades están incluidas en el objeto de tarea de Imagen a 3D.

Parámetros

Solo uno de input_task_id o image_url es requerido. Si se proporcionan ambos, input_task_id tiene prioridad.

Name
input_task_id
Type
string
Requerido
Description
El ID de una tarea de generación de imagen completada cuyo resultado debe ser utilizado como la imagen de entrada. Esta tarea debe ser una de las siguientes: Texto a Imagen o Imagen a Imagen. Además, debe haberse ejecutado a través de la API, tener un estado de SUCCEEDED, y producir exactamente una imagen.

Name
image_url
Type
string
Requerido
Description
Proporciona una imagen para que Meshy la use en la creación del modelo. Actualmente soportamos los formatos .jpg, .jpeg y .png.
Hay dos formas de proporcionar la imagen:
- URL accesible públicamente: Una URL que es accesible desde Internet pública.
- Data URI: Un Data URI en base64 de la imagen. Ejemplo de un Data URI: data:image/jpeg;base64,<tus datos de imagen codificados en base64>.

Name
model_type
Type
string
predeterminado standard
Description
Especifica el tipo de generación de malla 3D.
Valores disponibles:
- standard: Generación de malla 3D de alto detalle regular.
- smart-topology: Elige un modelo de Smart Topology con ai_model (meshy-t1 o meshy-t2).
- lowpoly (obsoleto): Genera mallas low-poly optimizadas para polígonos más limpios. Recomendamos usar smart-topology en su lugar.
Cuando se selecciona smart-topology, se ignoran topology, should_remesh y save_pre_remeshed_model.
Cuando se selecciona lowpoly, se ignoran ai_model, topology, target_polycount, should_remesh y save_pre_remeshed_model.
Name
ai_model
Type
string
predeterminado latest
Description
ID del modelo a usar. Los valores disponibles dependen de model_type.
Generación estándar (model_type: standard):
- meshy-5, meshy-6, meshy-7, latest (Meshy 7)
Generación de Smart Topology (model_type: smart-topology):
- meshy-t2 (predeterminado, recomendado): el modelo de Smart Topology — cleaner topology, partes separadas nativamente, salida en triángulos y un recuento de caras que puedes establecer con target_polycount.
- meshy-t1: el viejo modelo low-poly; no permite establecer un recuento de caras con target_polycount.
Name
ultra_mode
Type
boolean
predeterminado false
Description
Habilita la generación Ultra para una geometría de mayor fidelidad con detalles de superficie más finos.
Solo es compatible cuando ai_model es meshy-7 (o latest).
Name
should_texture
Type
boolean
predeterminado true
Description
Determina si se generan texturas. Configurarlo en false omite la fase de textura, proporcionando una malla sin texturas.

Solo aplica cuando should_texture = true

Name
enable_pbr
Type
boolean
predeterminado false
Description
Genera Mapas PBR (metálico, rugosidad, normal) además del color base. También se incluye un mapa de emisión cuando ai_model es meshy-6, excepto en texture_resolution: 8k. meshy-7 y latest no producen mapa de emisión.
Name
texture_resolution
Type
string
predeterminado 2k
Description
Resolución de textura de color base. Uno de 2k (2048×2048), 4k (4096×4096) o 8k (8192×8192). Las resoluciones más altas capturan más detalles de la superficie.
4k y 8k no están disponibles con ai_model: meshy-5. En 8k, no se produce mapa de emisión.
Name
hd_texture
Type
boolean
⚠ obsoleto
predeterminado false
Description
Usa texture_resolution en su lugar — equivalente a texture_resolution: "4k". Cuando ambos están configurados, texture_resolution tiene prioridad.
Name
texture_prompt
Type
string
Description
Proporciona un prompt textual para guiar el proceso de texturizado. Máximo 600 caracteres.
Name
texture_image_url
Type
string
Description
Proporciona una imagen en 2D para guiar el proceso de texturizado. Actualmente soportamos los formatos .jpg, .jpeg y .png.
Hay dos formas de proporcionar la imagen:
- URL accesible públicamente: Una URL que es accesible desde Internet pública
- Data URI: Un Data URI en base64 de la imagen. Ejemplo de un Data URI: data:image/jpeg;base64,<tus datos de imagen codificados en base64>
El texturizado de imágenes puede no funcionar óptimamente si hay diferencias substanciales de geometría entre el asset original y la imagen cargada. Solo uno de texture_image_url o texture_prompt puede ser usado para guiar el proceso de texturizado. Si se proporcionan ambos parámetros, entonces texture_prompt será usado para texturizar el modelo por defecto. El texturizado a través de texto o imagen costará 10 créditos por tarea.

Name
should_remesh
Type
boolean
predeterminado false (meshy-6, meshy-7), true (otros)
Description
Controla si habilitar la fase de remallado. Para el modelo de la más alta calidad, recomendamos configurar should_remesh en false.

Solo aplica cuando should_remesh = true

Name
topology
Type
string
predeterminado triangle
Description
Especifica la topology del modelo generado.
Valores disponibles:
- quad: Genera una malla dominante de cuadriláteros.
- triangle: Genera una malla de triángulos diezmada.
Name
decimation_mode
Type
integer
Description
Habilita la decimación adaptativa configurando un nivel de recuento de polígonos. Cuando se establece, se ignora target_polycount.
Valores disponibles:
- 1: Adaptativo — recuento ultra de polígonos.
- 2: Adaptativo — recuento alto de polígonos.
- 3: Adaptativo — recuento medio de polígonos.
- 4: Adaptativo — recuento bajo de polígonos.
Name
save_pre_remeshed_model
Type
boolean
predeterminado false
Description
Cuando se establece en true, Meshy también almacena un archivo GLB extra antes de que la fase de remallado finalice.

Name
target_polycount
Type
integer
Description
Número objetivo de polígonos (caras) en la salida. La cuenta real puede desviarse del objetivo dependiendo de la geometría.
target_polycount entra en efecto en dos casos independientes:
- Remesh — con should_remesh: true en un modelo standard. La malla se remalla (dieza) aproximadamente a este conteo. Rango de 100 a 300,000, por defecto 30,000. Si se establece decimation_mode, tiene prioridad y se ignora target_polycount.
- Smart Topology — con model_type: smart-topology y ai_model: meshy-t2. El modelo se genera directamente con este conteo de caras; no se ejecuta remesh y should_remesh no es necesario. Rango de 100 a 15,000, por defecto 4,000.

Name
symmetry_mode
Type
string
⚠ obsoleto
predeterminado auto
Description
Obsoleto. Este parámetro ya no afecta la salida.
El campo symmetry_mode controla el comportamiento de simetría durante el proceso de generación del modelo.
Los valores válidos son:
- off: Deshabilita la simetría.
- auto: Determina y aplica automáticamente la simetría basado en la geometría de entrada.
- on: Impone la simetría durante la generación.
Name
pose_mode
Type
string
predeterminado ""
Description
Especifica el modo de pose para el modelo generado.
Valores disponibles:
- a-pose: Genera el modelo en una pose A.
- t-pose: Genera el modelo en una pose T.
- "" (cadena vacía): No se aplica ninguna pose específica.
Name
is_a_t_pose
Type
boolean
⚠ obsoleto
predeterminado false
Description
Usa pose_mode en su lugar. Si generar el modelo en una pose A/T.
Name
image_enhancement
Type
boolean
predeterminado true
Description
Optimiza la imagen de entrada para obtener mejores resultados. Configúralo en false para preservar la apariencia exacta de la imagen de entrada sin ningún procesamiento de estilo.
Solo es compatible cuando ai_model es meshy-6, meshy-7 o latest.
Name
remove_lighting
Type
boolean
predeterminado true
Description
Elimina reflejos y sombras de la textura del color base, produciendo un resultado más limpio que funciona mejor bajo configuraciones de iluminación personalizadas.
Solo es compatible cuando ai_model es meshy-6.
Name
moderation
Type
boolean
predeterminado false
Description
Cuando se establece en true, el contenido de entrada se revisa automáticamente para detectar contenido potencialmente dañino. Si se detecta contenido dañino, la tarea no procederá a la generación.
El contenido de las entradas image_url, texture_image_url y texture_prompt será revisado.
Name
target_formats
Type
string[]
Description
Especifica qué formatos de archivo 3D incluir en la salida. Solo los formatos solicitados se generarán y se devolverán, lo que puede reducir el tiempo de finalización de la tarea. Cuando se omite, se incluyen todos los formatos compatibles.
Valores disponibles: glb, obj, fbx, stl, usdz, 3mf
Cuando se omite, se generan todos los formatos excepto 3mf. 3mf solo se incluye cuando se especifica explícitamente.
Name
auto_size
Type
boolean
predeterminado false
Description
Cuando se establece en true, el servicio utiliza visión de IA para estimar automáticamente la altura en el mundo real del objeto y redimensionar el modelo de acuerdo. El origen se fijará por defecto en bottom a menos que origin_at se establezca explícitamente.
Name
alpha_thumbnail
Type
boolean
predeterminado false
Description
Cuando se establece en true, la tarea adicionalmente renderiza una versión con fondo transparente (RGBA) de la vista previa y la retorna como alpha_thumbnail_url] en la respuesta GET. El campo existente thumbnail_url permanece sin cambios.
Name
multi_view_thumbnails
Type
boolean
predeterminado false
Description
Cuando se establece en true, la tarea adicionalmente renderiza cuatro miniaturas de vista cardinal (frontal, derecha, trasera, izquierda) y las devuelve bajo thumbnail_urls en la respuesta GET. El campo existente thumbnail_url permanece sin cambios y continúa apuntando a la vista frontal, por lo que los clientes existentes no se ven afectados.
Agrega aproximadamente 3 segundos a la latencia de la tarea.

Solo aplica cuando auto_size = true

Name
origin_at
Type
string
predeterminado bottom
Description
Posición del origen cuando auto_size está habilitado.
Valores disponibles: bottom, center.

Devuelve

La propiedad result de la respuesta contiene el id de la tarea recién creada de Imagen a 3D.

Modos de Fallo

Name
400 - Bad Request
Description
La solicitud era inaceptable. Causas comunes:
- Parámetro faltante: Debe proporcionarse image_url o input_task_id.
- Tarea de entrada inválida: El input_task_id debe referirse a una tarea de Texto a Imagen o Imagen a Imagen SUCCEEDED que produce exactamente una imagen.
- Formato de imagen inválido: La image_url proporcionada no es un formato soportado (.jpg, .jpeg, .png).
- URL inalcanzable: No se pudo descargar la image_url (404 o timeout).
- Data URI inválido: La cadena en base64 está mal formada.
- Combinación de parámetros inválida: enable_pbr solo es compatible cuando should_texture es verdadero.
Name
401 - Unauthorized
Description
Falló la autenticación. Por favor verifica tu clave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarea.
Name
429 - Too Many Requests
Description
Has excedido tu límite de tasa.

Solicitud

POST

/openapi/v1/image-to-3d

# Solicitud simple con parámetros requeridos
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<tu URL de imagen accesible públicamente o Data URI codificado en base64>"
  }'

# Con remesh, PBR y A-pose
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<tu URL de imagen accesible públicamente o Data URI codificado en base64>",
    "enable_pbr": true,
    "should_remesh": true,
    "target_polycount": 100000,
    "should_texture": true,
    "pose_mode": "a-pose",
    "target_formats": ["glb"]
  }'

Respuesta

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

GET/openapi/v1/image-to-3d/:id

Obtener una Tarea de Imagen a 3D

Este endpoint te permite obtener una tarea de Imagen a 3D dada un id válido. Consulta El Objeto de Tarea de Imagen a 3D para ver qué propiedades están incluidas en el objeto de tarea de Imagen a 3D.

Parámetros

Name
id
Type
path
Description
Identificador único para la tarea de Imagen a 3D a obtener.

Devuelve

La respuesta contiene el objeto de tarea de Imagen a 3D. Consulta la sección El Objeto de Tarea de Imagen a 3D para detalles.

Solicitud

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Respuesta

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "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=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}

DELETE/openapi/v1/image-to-3d/:id

Eliminar una Tarea de Imagen a 3D

Este endpoint elimina permanentemente una tarea de Imagen a 3D, incluyendo todos los modelos y datos asociados. Esta acción es irreversible.

Parámetros de Ruta

Name
id
Type
path
Description
El ID de la tarea de Imagen a 3D a eliminar.

Devuelve

Devuelve 200 OK en caso de éxito.

Solicitud

DELETE

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Respuesta

// Devuelve 200 Ok en caso de éxito.

GET/openapi/v1/image-to-3d

Listar Tareas de Imagen a 3D

Este endpoint te permite obtener una lista de tareas de Imagen a 3D.

Parámetros

Atributos opcionales

Name
page_num
Type
integer
Description
Número de página para paginación. Comienza y tiene como valor predeterminado 1.
Name
page_size
Type
integer
Description
Límite de tamaño de página. Por defecto es 10 elementos. El máximo permitido es 50 elementos.
Name
sort_by
Type
string
Description
Campo para ordenar. Valores disponibles:
- +created_at: Ordenar por hora de creación en orden ascendente.
- -created_at: Ordenar por hora de creación en orden descendente.

Devuelve

Devuelve una lista paginada de Los Objetos de Tarea de Imagen a 3D.

Solicitud

GET

/openapi/v1/image-to-3d

curl https://api.meshy.ai/openapi/v1/image-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Respuesta

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "image-to-3d",
    "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=***",
      "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
      "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "thumbnail_urls": {
      "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
      "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
      "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
      "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
    },
    "texture_prompt": "",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "expires_at": 1692771679037,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
        "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
        "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
        "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
        "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
      }
    ],
    "preceding_tasks": 0,
    "task_error": {
      "message": ""
    },
    "consumed_credits": 30
  }
]

GET/openapi/v1/image-to-3d/:id/stream

Transmitir una Tarea de Imagen a 3D

Este endpoint transmite actualizaciones en tiempo real para una tarea de Imagen a 3D usando Eventos Enviados por el Servidor (SSE).

Parámetros

Name
id
Type
path
Description
Identificador único para la tarea de Imagen a 3D a transmitir.

Devuelve

Devuelve un stream de Los Objetos de Tarea de Imagen a 3D como Eventos Enviados por el Servidor.

Para tareas PENDING o IN_PROGRESS, el stream de respuesta solo incluirá los campos necesarios progress y status.

Solicitud

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Stream de Respuesta

// Ejemplo de evento de error
event: error
data: {
  "status_code": 404,
  "message": "Tarea no encontrada"
}

// Ejemplos de eventos de mensaje que ilustran el progreso de la tarea.
// Para tareas PENDING o IN_PROGRESS, el stream de respuesta no incluirá todos los campos.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "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=***",
  "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
  "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
  "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
  "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}

El Objeto de Tarea de Imagen a 3D

El objeto de tarea de Imagen a 3D es una unidad de trabajo que Meshy rastrea para generar un modelo 3D a partir de una entrada de imagen. El objeto tiene las siguientes propiedades:

Propiedades

Name
id
Type
string
Description
Identificador único de la tarea. Aunque usamos un UUID ordenable por k para los ids de tareas como detalle de implementación, no debes hacer suposiciones sobre el formato del id.
Name
type
Type
string
Description
Tipo de la tarea de Imagen a 3D. El valor es image-to-3d.
Name
model_urls
Type
object
Description
URL descargable para el archivo del modelo 3D texturizado generado por Meshy. La propiedad para un formato se omitirá si el formato no es generado en lugar de devolver una cadena vacía.
- Name
  glb
  Type
  string
  Description
  URL descargable para el archivo GLB.
- Name
  fbx
  Type
  string
  Description
  URL descargable para el archivo FBX.
- Name
  obj
  Type
  string
  Description
  URL descargable para el archivo OBJ.
- Name
  usdz
  Type
  string
  Description
  URL descargable para el archivo USDZ.
- Name
  mtl
  Type
  string
  Description
  URL descargable para el archivo MTL, devuelto junto con las exportaciones OBJ cuando hay texturas presentes.
- Name
  stl
  Type
  string
  Description
  URL descargable para el archivo STL.
- Name
  3mf
  Type
  string
  Description
  URL descargable para el archivo 3MF. Solo presente cuando 3mf fue solicitado a través de target_formats.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  URL descargable para la salida GLB original antes del remallado.
  Disponible solo cuando la tarea fue creada con ambos should_remesh: true y save_pre_remeshed_model: true.
Name
thumbnail_url
Type
string
Description
URL descargable para la imagen de miniatura del archivo del modelo. Equivalente a thumbnail_urls.front cuando esté presente, mantenido para compatibilidad retroactiva.
Name
alpha_thumbnail_url
Type
string
Description
URL descargable para una versión con fondo transparente (RGBA) de thumbnail_url. Solo presente cuando la tarea fue creada con alpha_thumbnail: true y la vista previa transparente fue renderizada con éxito; de lo contrario, este campo se omite.
Name
thumbnail_urls
Type
object
Description
URLs descargables para cuatro miniaturas de vista cardinal del modelo 3D generado. Cada valor es una URL firmada a un PNG de 512×512 renderizado con los mismos materiales e iluminación que thumbnail_url. Útil para previsualizar el modelo desde varios ángulos en procesos por lotes sin descargar el GLB.
Solo presente cuando la tarea fue creada con multi_view_thumbnails: true y ha alcanzado SUCCEEDED. Las tareas más antiguas y las tareas creadas sin esta opción no incluirán este campo.
- Name
  front
  Type
  string
  Description
  Vista frontal, rotación de 0° alrededor del eje vertical (coincide con thumbnail_url).
- Name
  right
  Type
  string
  Description
  Vista derecha, rotación de 90°.
- Name
  back
  Type
  string
  Description
  Vista trasera, rotación de 180°.
- Name
  left
  Type
  string
  Description
  Vista izquierda, rotación de 270°.
Name
texture_prompt
Type
string
Description
El prompt textual que fue utilizado para guiar el proceso de texturizado.
Name
texture_image_url
Type
string
Description
URL descargable para la imagen de textura que fue usada para guiar el proceso de texturizado.
Name
ultra_mode
Type
boolean
Description
Refleja el valor de ultra_mode con el que se creó la tarea. Solo está presente para tareas de meshy-7 (o latest) que establecieron explícitamente ultra_mode; de lo contrario, se omite.
Name
progress
Type
integer
Description
Progreso de la tarea. Si la tarea aún no ha comenzado, esta propiedad será 0. Una vez que la tarea haya tenido éxito, esto se convertirá en 100.
Name
started_at
Type
timestamp
Description
Marca de tiempo de cuando la tarea fue iniciada, en milisegundos. Si la tarea aún no ha comenzado, esta propiedad será 0.
Una marca de tiempo representa el número de milisegundos transcurridos desde el 1 de enero de 1970 UTC, siguiendo el estándar RFC 3339. Por ejemplo, viernes 1 de septiembre de 2023 12:00:00 PM GMT se representa como 1693569600000. Esto se aplica a todas las marcas de tiempo en la API Meshy.
Name
created_at
Type
timestamp
Description
Marca de tiempo de cuando la tarea fue creada, en milisegundos.
Name
expires_at
Type
timestamp
Description
Marca de tiempo de cuando el resultado de la tarea expira, en milisegundos.
Name
finished_at
Type
timestamp
Description
Marca de tiempo de cuando la tarea fue finalizada, en milisegundos. Si la tarea aún no ha terminado, esta propiedad será 0.
Name
status
Type
string
Description
Estado de la tarea. Los valores posibles son PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Un array de objetos de URL de texturas que se generan a partir de la tarea. Normalmente esto solo contiene una URL de textura. Cada URL de textura tiene las siguientes propiedades:
- Name
  base_color
  Type
  string
  Description
  URL descargable para la imagen del mapa de color base.
- Name
  metallic
  Type
  string
  Description
  URL descargable para la imagen del mapa metálico.
  Si la tarea se crea con enable_pbr: false, esta propiedad se omitirá.
- Name
  normal
  Type
  string
  Description
  URL descargable para la imagen del mapa de normales.
  Si la tarea se crea con enable_pbr: false, esta propiedad se omitirá.
- Name
  roughness
  Type
  string
  Description
  URL descargable para la imagen del mapa de rugosidad.
  Si la tarea se crea con enable_pbr: false, esta propiedad se omitirá.
- Name
  emission
  Type
  string
  Description
  URL descargable para la imagen del mapa de emisión.
  Si la tarea se crea con enable_pbr: false, o ai_model es meshy-5, meshy-7, o latest, esta propiedad se omitirá.
Name
preceding_tasks
Type
integer
Description
El número de tareas precedentes.
El valor de este campo solo es significativo si el estado de la tarea es PENDING.
Name
task_error
Type
object
Description
Detalles de error para tareas fallidas. Consulta Errores para la referencia completa del objeto task_error.
Name
consumed_credits
Type
integer
Description
El número de créditos consumidos por esta tarea. Presente cuando el estado de la tarea es PENDING, IN_PROGRESS, o SUCCEEDED. Devuelve 0 para tareas FAILED (los créditos se reembolsan al fallar).

Ejemplo de Objeto de Tarea de Imagen a 3D

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "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=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "texture_image_url": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}