API de Imagen a 3D

Convierte una imagen en un modelo 3D, con o sin textura, en los formatos que elijas. Envía la imagen, o utiliza el resultado de una tarea de Texto a imagen o Imagen a imagen.

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

Crear una tarea de Imagen a 3D

Crea una tarea de Imagen a 3D. La tarea se ejecuta en segundo plano. Para saber cuánto suele tardar una tarea, consulta Tiempos de procesamiento.

Request

POST

/openapi/v1/image-to-3d

# Simple request with required params
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": "<your publicly accessible image url or base64-encoded data URI>"
  }'

# With Ultra 4K geometry, remesh, PBR, and 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": "<your publicly accessible image url or base64-encoded data URI>",
    "ai_model": "meshy-7.1",
    "geometry_resolution": "4k",
    "enable_pbr": true,
    "should_remesh": true,
    "target_polycount": 100000,
    "should_texture": true,
    "pose_mode": "a-pose",
    "target_formats": ["glb"]
  }'

Response

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

Parámetros

Name
input_task_id
Type
string
Requerido
Description
Obligatorio a menos que envíes image_url. El ID de una tarea de Texto a Imagen o Imagen a Imagen cuya imagen quieras usar como entrada. La tarea debe ser una que hayas creado con la API, tener el estado SUCCEEDED y haber producido exactamente una imagen.

Name
image_url
Type
string
Requerido
Description
Obligatorio a menos que envíes input_task_id. La imagen que se convertirá en un modelo 3D, como una URL pública o un Data URI codificado en base64, como data:image/jpeg;base64,<your base64-encoded image data>. Si envías ambos, Meshy usa input_task_id.
La imagen debe ser un archivo JPG, JPEG, PNG o WebP de hasta 20 MB.

Name
model_type
Type
string
predeterminado standard
Description
El tipo de malla 3D que se generará.
Valores disponibles:
- standard: una malla de alto detalle
- smart-topology: una malla a partir de un modelo Smart Topology, que eliges con ai_model (meshy-t2 o meshy-t2.5)
Con smart-topology, Meshy ignora should_remesh, save_pre_remeshed_model y decimation_mode, y solo acepta topology: triangle.
Name
ai_model
Type
string
predeterminado latest
Description
El modelo de IA que genera el modelo 3D. Los valores disponibles dependen de model_type.
Modelos estándar (model_type: standard):
- latest: Meshy 7.1
- meshy-7.1
- meshy-6
- meshy-6-lite
- meshy-7 (obsoleto): usa meshy-7.1 en su lugar
Los modelos Smart Topology (model_type: smart-topology) producen triángulos, con un número de caras que puedes definir con target_polycount:
- meshy-t2: topología más limpia y partes separadas de forma nativa
- meshy-t2.5 (predeterminado): detalle más definido para assets de juegos
Name
geometry_resolution
Type
string
predeterminado standard
Description
La pasada de generación de geometría.
Valores disponibles:
- standard
- 2k: ejecuta la pasada Ultra a 2048³
- 4k: ejecuta la pasada Ultra a 4096³, para obtener el mayor detalle de superficie
2k necesita meshy-7.1, latest o el obsoleto meshy-7. 4k necesita meshy-7.1 o latest.
Name
ultra_mode
Type
boolean
⚠ obsoleto
predeterminado false
Description
Usa geometry_resolution en su lugar. ultra_mode: true equivale a geometry_resolution: "2k".
Name
should_texture
Type
boolean
predeterminado true
Description
Si se deben generar texturas. true devuelve un modelo con textura, y false omite el texturizado y devuelve una malla sin textura.

Solo aplica cuando should_texture = true

Name
enable_pbr
Type
boolean
predeterminado false
Description
Si también se deben generar mapas PBR (metálico, rugosidad y normal) además del color base. true requiere should_texture: true, y devuelve 400 con should_texture: false.
Con meshy-6, Meshy también genera un mapa de emisión, excepto con texture_resolution: 8k. Estos modelos no producen mapa de emisión:
- meshy-6-lite
- meshy-7
- meshy-7.1
- meshy-t2
- meshy-t2.5
- latest
Name
texture_resolution
Type
string
predeterminado 2k
Description
El tamaño de la textura de color base. Una textura más grande captura más detalle de superficie.
Valores disponibles:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
4k y 8k no están disponibles con meshy-6-lite, y devuelven 400 con ese modelo. Con 8k, Meshy no produce un mapa de emisión.
Name
hd_texture
Type
boolean
⚠ obsoleto
predeterminado false
Description
Usa texture_resolution en su lugar. hd_texture: true equivale a texture_resolution: "4k". Si envías ambos, Meshy usa texture_resolution.
Name
texture_prompt
Type
string
Description
Texto que guía la textura, hasta 800 caracteres. Un texto más largo devuelve 400.
Name
texture_image_url
Type
string
Description
Una imagen que guía la textura, como una URL pública o un Data URI codificado en base64, como data:image/jpeg;base64,<your base64-encoded image data>. La imagen debe ser un archivo JPG, JPEG, PNG o WebP de hasta 20 MB.
Meshy guía la textura con solo uno de texture_prompt o texture_image_url. Si envías ambos, Meshy usa texture_prompt. Para conocer el costo en créditos del texturizado, consulta Precios.
El texturizado a partir de una imagen puede no funcionar bien cuando la forma de la imagen difiere mucho de la geometría del modelo 3D.

Name
should_remesh
Type
boolean
predeterminado true (meshy-6-lite), false (other models)
Description
Si se debe ejecutar la fase de remallado. Para obtener el modelo 3D de mayor calidad, configúralo como false.

Solo aplica cuando should_remesh = true

Name
topology
Type
string
predeterminado triangle
Description
El tipo de cara del modelo remallado.
Valores disponibles:
- quad: una malla predominantemente de cuadriláteros
- triangle: una malla triangular decimada
La salida de Smart Topology es solo de triángulos, por lo que quad con meshy-t2 o meshy-t2.5 devuelve 400.
Name
decimation_mode
Type
integer
Description
Número de caras adaptativo, por nivel. Cuando lo configuras, Meshy ignora target_polycount.
Valores disponibles:
- 1: ultra
- 2: alto
- 3: medio
- 4: bajo
Name
save_pre_remeshed_model
Type
boolean
predeterminado false
Description
Si también se debe almacenar un GLB del modelo previo a la fase de remallado. Meshy lo devuelve en model_urls.pre_remeshed_glb.

Name
target_polycount
Type
integer
Description
El número de caras objetivo. El resultado puede diferir del objetivo, según la geometría del modelo.
Se aplica en dos casos distintos:
- Remallado: Cuando should_remesh es true en un modelo standard, Meshy decima la malla a aproximadamente este número. Si configuras decimation_mode, Meshy lo usa e ignora target_polycount.
- Smart Topology: Cuando model_type es smart-topology y ai_model es meshy-t2 o meshy-t2.5, Meshy genera el modelo con este número de caras. No se ejecuta ningún remallado, y no necesitas should_remesh.
El rango y el valor predeterminado dependen del caso:
Caso Rango Predeterminado
Remallado 100 a 300000 30000
meshy-t2 100 a 15000 4000
meshy-t2.5 100 a 30000 15000
Un valor fuera del rango devuelve 400.

Caso	Rango	Predeterminado
Remallado	`100` a `300000`	`30000`
`meshy-t2`	`100` a `15000`	`4000`
`meshy-t2.5`	`100` a `30000`	`15000`

Name
symmetry_mode
Type
string
⚠ obsoleto
predeterminado auto
Description
Omítelo, porque no afecta el resultado. Sus valores controlaban la simetría durante la generación:
- off: sin simetría
- auto: simetría elegida a partir de la geometría de entrada
- on: simetría forzada
Name
pose_mode
Type
string
predeterminado ""
Description
La pose para el modelo generado.
Valores disponibles:
- a-pose: una pose en A
- t-pose: una pose en T
- "" (cadena vacía): sin pose específica
Name
is_a_t_pose
Type
boolean
⚠ obsoleto
predeterminado false
Description
Usa pose_mode en su lugar. Indica si se debe generar el modelo en pose A o T.
Name
surface_mode
Type
string
⚠ obsoleto
Description
Usa ai_model en su lugar. No afecta el resultado, porque el modo de generación de modelos que seleccionaba está retirado.
Los valores aceptados son organic y hard. Cualquier otro valor devuelve 400.
Name
image_enhancement
Type
boolean
predeterminado true
Description
Si se debe optimizar la imagen de entrada antes de generar. false conserva el aspecto exacto de la imagen de entrada, sin procesamiento de estilo.
Solo funciona con meshy-6, meshy-7.1 o latest. Con meshy-6-lite o model_type: smart-topology, devuelve 400.
Name
remove_lighting
Type
boolean
predeterminado true
Description
Si se deben eliminar los brillos y sombras de la textura de color base. El resultado es más limpio y funciona mejor con tu propia iluminación.
Solo surte efecto con meshy-6. meshy-7.1 y latest lo aceptan pero lo ignoran. Con meshy-6-lite o model_type: smart-topology, devuelve 400.
Name
moderation
Type
boolean
predeterminado false
Description
Si se debe examinar estas entradas en busca de contenido dañino antes de generar:
- image_url
- texture_image_url
- texture_prompt
Si Meshy detecta contenido dañino, la solicitud devuelve 400 y Meshy no crea la tarea.
Name
target_formats
Type
string[]
Description
Los formatos de archivo que se generarán. Meshy genera y devuelve solo los formatos que indiques, lo que puede acortar la tarea. Si lo omites, Meshy genera todos los formatos excepto 3mf, que solo obtienes si lo indicas.
Valores disponibles:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
auto_size
Type
boolean
predeterminado false
Description
Si se debe estimar la altura real del objeto con visión por IA y redimensionar el modelo a esa altura. Meshy coloca el origen en la parte inferior a menos que configures origin_at.
Name
alpha_thumbnail
Type
boolean
predeterminado false
Description
Si también se debe renderizar una vista previa con fondo transparente (RGBA), devuelta en alpha_thumbnail_url al obtener la tarea. thumbnail_url no cambia.
Name
multi_view_thumbnails
Type
boolean
predeterminado false
Description
Si también se deben renderizar vistas previas frontal, derecha, trasera e izquierda, devueltas en thumbnail_urls al obtener la tarea. thumbnail_url no cambia y sigue mostrando la vista frontal. Esto añade unos 5 segundos a la tarea.

Solo aplica cuando auto_size = true

Name
origin_at
Type
string
predeterminado bottom
Description
Dónde colocar el origen del modelo, bottom o center.

Resultados

El campo result de la respuesta contiene el ID de la nueva tarea de Imagen a 3D.

Modos de fallo

Name
400 - Bad Request
Description
La solicitud no se puede ejecutar. El mensaje de error indica qué problema encontró. Por ejemplo:
- Falta un parámetro: no se envió ni image_url ni input_task_id.
- Tarea de entrada no válida: input_task_id no es una tarea SUCCEEDED de Texto a Imagen o Imagen a Imagen que haya producido exactamente una imagen.
- Formato de imagen no válido: la imagen de image_url no es un archivo JPG, JPEG, PNG o WebP.
- URL inaccesible: Meshy no puede descargar la imagen de image_url, porque la URL devuelve 404 o agota el tiempo de espera.
- Imagen demasiado grande: la imagen de image_url o texture_image_url supera los 20 MB.
- Data URI no válido: la cadena en base64 tiene un formato incorrecto.
- Combinación de parámetros no válida: enable_pbr es true, y should_texture es false.
- Modelo no compatible con Ultra: geometry_resolution es 2k o 4k, con un ai_model que no puede ejecutarlo.
- Modelo no compatible con opciones de imagen: se envió image_enhancement o remove_lighting con ai_model: "meshy-6-lite" o model_type: "smart-topology".
Corrige la solicitud y vuelve a enviarla. Consulta Errores.
Name
401 - Unauthorized
Description
Falta la clave de API o no es válida. Verifica el encabezado Authorization.
Name
402 - Payment Required
Description
Por ejemplo:
- Créditos insuficientes: la cuenta no tiene créditos suficientes para esta tarea, o alcanzó un límite de créditos. Revisa tu saldo de créditos y vuelve a intentarlo.
- Plan gratuito: crear una tarea requiere un plan de pago. Mejora tu plan en la configuración de tu suscripción y vuelve a intentarlo.
Name
404 - Not Found
Description
input_task_id no coincide con ninguna de tus tareas. Verifica el ID de la tarea y vuelve a enviar la solicitud.
Name
429 - Too Many Requests
Description
Superaste tu límite de tasa. Espera y vuelve a intentarlo. Consulta Límites de tasa.

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

Obtener una tarea de Imagen a 3D

Devuelve una tarea de Imagen a 3D según su ID.

Request

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

Response

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

Parámetros

Name
id
Type
path
Description
El ID de la tarea proveniente de la respuesta de creación.

Devuelve

El objeto de tarea de Imagen a 3D.

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

Eliminar una tarea de Imagen a 3D

Elimina permanentemente una tarea de Imagen a 3D, incluyendo sus modelos y datos. No puedes deshacer una eliminación.

Request

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

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

Parámetros de ruta

Name
id
Type
path
Description
El ID de la tarea que se va a eliminar.

Estado de la tarea

Eliminar una tarea PENDING reembolsa los créditos que usó al crearla.

Una tarea IN_PROGRESS no se puede eliminar. La solicitud devuelve 409 Conflict, y la tarea sigue ejecutándose. Meshy no reembolsa una tarea que ya ha comenzado, así que eliminarla te costaría tanto los créditos como el resultado. Espera a que alcance el estado SUCCEEDED, FAILED o CANCELED, y luego elimínala.

Eliminar una tarea en un estado final (SUCCEEDED, FAILED o CANCELED) no reembolsa sus créditos.

Devuelve

200 OK cuando la tarea se elimina, o 409 Conflict cuando la tarea está IN_PROGRESS.

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

Listar tareas de Imagen a 3D

Devuelve una lista de tus tareas de Imagen a 3D.

Request

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

Response

[
  {
    "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
  }
]

Parámetros

Name
page_num
Type
integer
predeterminado 1
Description
El número de página a devolver. Las páginas comienzan en 1.
Name
page_size
Type
integer
predeterminado 10
Description
El número de tareas por página, hasta 100.
Name
sort_by
Type
string
Description
El orden de clasificación.
Valores disponibles:
- +created_at: más antiguo primero
- -created_at: más reciente primero

Devuelve

Una lista paginada de objetos de tarea de Imagen a 3D.

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

Transmitir una tarea de Imagen a 3D en streaming

Transmite las actualizaciones de una tarea de Imagen a 3D como eventos enviados por el servidor (SSE).

Request

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

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// These examples are shortened. Each event holds the full task object.
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
}

Parámetros

Name
id
Type
path
Description
El ID de la tarea proveniente de la respuesta de creación.

Devuelve

Un flujo de objetos de tarea de Imagen a 3D como eventos enviados por el servidor.

Cada evento contiene el objeto de tarea completo, con la misma forma que devuelve el endpoint Get. Mientras la tarea esté en PENDING o IN_PROGRESS, sus campos de resultado aún no tienen valores.

El objeto de tarea Imagen a 3D

Un objeto de tarea Imagen a 3D describe una generación de un modelo 3D a partir de una imagen. Contiene el estado, el progreso y los archivos del modelo cuando la tarea tiene éxito.

Propiedades

Example Image to 3D Task Object

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

Name
id
Type
string
Description
El ID de la tarea. Trátalo como una cadena opaca y no dependas de su formato.
Name
type
Type
string
Description
El tipo de tarea, siempre image-to-3d.
Name
model_urls
Type
object
Description
URLs de descarga para el modelo 3D generado, una por cada formato de archivo. Un formato que la tarea no generó no tiene clave, en lugar de una cadena vacía.
- Name
  glb
  Type
  string
  Description
  El archivo GLB.
- Name
  fbx
  Type
  string
  Description
  El archivo FBX.
- Name
  obj
  Type
  string
  Description
  El archivo OBJ.
- Name
  usdz
  Type
  string
  Description
  El archivo USDZ.
- Name
  mtl
  Type
  string
  Description
  El archivo MTL, devuelto junto con un archivo OBJ cuando el modelo tiene texturas.
- Name
  stl
  Type
  string
  Description
  El archivo STL.
- Name
  3mf
  Type
  string
  Description
  El archivo 3MF. Presente solo cuando target_formats incluye 3mf.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  El archivo GLB previo al remallado. Presente solo cuando creaste la tarea con tanto should_remesh: true como save_pre_remeshed_model: true.
Name
thumbnail_url
Type
string
Description
URL de descarga para una imagen de vista previa del modelo 3D. Cuando thumbnail_urls está presente, es la misma imagen que thumbnail_urls.front. Meshy la conserva por compatibilidad con versiones anteriores.
Name
alpha_thumbnail_url
Type
string
Description
URL de descarga para una versión de thumbnail_url con fondo transparente (RGBA). Presente solo cuando creaste la tarea con alpha_thumbnail: true y Meshy renderizó la vista previa transparente.
Name
thumbnail_urls
Type
object
Description
URLs de descarga para vistas previas del modelo 3D desde cuatro lados. Cada valor es una URL firmada a un PNG de 512×512, renderizado con los mismos materiales e iluminación que thumbnail_url. Úsalas para previsualizar el modelo desde varios ángulos, por ejemplo en un flujo de procesamiento por lotes, sin descargar el GLB.
Presente solo cuando creaste la tarea con multi_view_thumbnails: true y la tarea alcanzó el estado SUCCEEDED. Las tareas creadas sin multi_view_thumbnails: true no incluyen este campo.
- Name
  front
  Type
  string
  Description
  La vista frontal, a 0° sobre el eje vertical. Coincide con thumbnail_url.
- Name
  right
  Type
  string
  Description
  La vista derecha, a 90°.
- Name
  back
  Type
  string
  Description
  La vista posterior, a 180°.
- Name
  left
  Type
  string
  Description
  La vista izquierda, a 270°.
Name
texture_prompt
Type
string
Description
El prompt de texto que guió la textura.
Name
texture_image_url
Type
string
Description
URL de descarga para la imagen que guió la textura.
Name
ultra_mode
Type
boolean
⚠ obsoleto
Description
Consulta geometry_resolution en su lugar.
Name
geometry_resolution
Type
string
Description
El nivel Ultra en el que se ejecutó la tarea, 2k o 4k. Una tarea standard no incluye este campo.
Name
progress
Type
integer
Description
Cuánto se ha completado la tarea, como porcentaje. Es 0 hasta que la tarea comienza y 100 cuando tiene éxito.
Name
started_at
Type
timestamp
Description
Momento en que la tarea comenzó, en milisegundos Unix. Es 0 hasta que la tarea comienza.
Name
created_at
Type
timestamp
Description
Momento en que se creó la tarea, en milisegundos Unix.
Name
expires_at
Type
timestamp
Description
Momento en que expira el resultado de la tarea, en milisegundos Unix.
Name
finished_at
Type
timestamp
Description
Momento en que la tarea finalizó, en milisegundos Unix. Es 0 hasta que la tarea finaliza.
Name
status
Type
string
Description
El estado de la tarea, uno de PENDING, IN_PROGRESS, SUCCEEDED, FAILED o CANCELED.
Name
texture_urls
Type
array
Description
Los mapas de textura que generó la tarea, como un arreglo de objetos. Normalmente contiene un objeto, con estos campos:
- Name
  base_color
  Type
  string
  Description
  URL de descarga para el mapa de color base.
- Name
  metallic
  Type
  string
  Description
  URL de descarga para el mapa metálico. El campo está ausente cuando creaste la tarea con enable_pbr: false.
- Name
  normal
  Type
  string
  Description
  URL de descarga para el mapa de normales. El campo está ausente cuando creaste la tarea con enable_pbr: false.
- Name
  roughness
  Type
  string
  Description
  URL de descarga para el mapa de rugosidad. El campo está ausente cuando creaste la tarea con enable_pbr: false.
- Name
  emission
  Type
  string
  Description
  URL de descarga para el mapa de emisión. El campo está ausente cuando creaste la tarea con enable_pbr: false o texture_resolution: 8k, o cuando ai_model es uno de estos modelos:
  
  meshy-6-lite
  
  meshy-7
  
  meshy-7.1
  
  meshy-t2
  
  meshy-t2.5
  
  latest
Name
preceding_tasks
Type
integer
Description
El número de tareas por delante de esta en la cola. El valor solo tiene sentido mientras la tarea está PENDING.
Name
task_error
Type
object
Description
Los detalles del error cuando la tarea falla. Consulta Errores.
Name
consumed_credits
Type
integer
Description
El número de créditos que usó la tarea. Presente cuando el estado es PENDING, IN_PROGRESS o SUCCEEDED. Es 0 para una tarea FAILED, porque Meshy reembolsa los créditos cuando una tarea falla.