lowpoly se retira el 30 oct 2026. meshy-7 se retira como modelo de generación 3D el 31 dic 2026; como modelo de texturas sigue disponible. Cambia de modelo antes de estas fechas para evitar errores en las solicitudes. Ver todas las obsolescencias

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

# Textured with Meshy N1 from the input image
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",
    "texture_model": "meshy-n1"
  }'

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 quieres 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,<tus datos de imagen codificados en base64>. Si envías ambos, Meshy usa input_task_id.

    La imagen debe ser un archivo JPG, JPEG, PNG o WebP de como máximo 20 MB, al menos 32 píxeles en cada lado, y como máximo 178.956.970 píxeles (ancho × alto).

  • Name
    model_type
    Type
    string
    predeterminado standard
    Description

    El tipo de malla 3D a generar.

    Valores disponibles:

    • standard: una malla de alto detalle
    • smart-topology: una malla 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. Se retira el 31 de diciembre de 2026.

    Los modelos Smart Topology (model_type: smart-topology) producen triángulos, con un número de caras que puedes configurar con target_polycount:

    • meshy-t2: topología más limpia y partes separadas de forma nativa
    • meshy-t2.5 (predeterminado): detalle más nítido para assets de videojuegos

    Consulta Modelos para saber qué modelo se adapta a tu proyecto, como un personaje de videojuego o una impresión 3D.

  • 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 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 es lo mismo que 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
    texture_model
    Type
    string
    predeterminado depends on ai_model
    Description

    El modelo de IA que texturiza el modelo 3D, en la misma tarea. Omítelo para usar el modelo de textura predeterminado para tu ai_model. No cambia el costo en créditos.

    Valores disponibles:

    • meshy-7: Meshy 7, con mapas PBR y texturas de hasta 8K
    • meshy-n1: Meshy N1, una textura de color base de 2K solo a partir de imágenes de referencia
    • meshy-6-lite: Meshy 6 Lite, una textura de 2K al menor costo
    • meshy-6: Meshy 6, solo como predeterminado para ai_model: meshy-6

    Todos los ai_model admiten meshy-7, meshy-n1 y meshy-6-lite. Una opción que el modelo de textura elegido no admite devuelve 400. Con meshy-n1, un modelo generado con más de 7.999.999 triángulos hace fallar la tarea, y Meshy reembolsa sus créditos. Con should_texture: false, Meshy ignora texture_model, pero un valor desconocido igual devuelve 400.

    Consulta Modelos para saber qué hace cada modelo de textura y cuál elegir.

  • 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 texture_model: meshy-n1, true devuelve 400.

    El modelo de textura Meshy 6 también genera un mapa de emisión, excepto con texture_resolution: 8k.

  • 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 requieren el modelo de textura Meshy 7 o Meshy 6, y devuelven 400 con los demás. En 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 es lo mismo que 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. Con texture_model: meshy-n1, enviarlo 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,<tus datos de imagen codificados en base64>. La imagen debe ser un archivo JPG, JPEG, PNG o WebP de como máximo 20 MB, al menos 32 píxeles en cada lado, y como máximo 178.956.970 píxeles (ancho × alto).

    Meshy guía la textura con solo uno de texture_prompt o texture_image_url. Si envías ambos, Meshy usa texture_prompt. Para el costo en créditos del texturizado, consulta Precios.

    Con texture_model: meshy-n1, Meshy texturiza a partir de esta imagen como la vista frontal, o a partir de la imagen de entrada cuando la omites.

  • 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 de triángulos decimada

    La salida de Smart Topology es solo de triángulos, por lo que quad con meshy-t2 o meshy-t2.5 devuelve 400. Con texture_model: meshy-n1, quad devuelve 400 cuando el modelo se remalla, lo que meshy-6-lite hace de forma predeterminada.

  • 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 al que se apunta. 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 hasta 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:

    CasoRangoPredeterminado
    Remallado100 a 30000030000
    meshy-t2100 a 150004000
    meshy-t2.5100 a 3000015000

    Un valor fuera del rango devuelve 400.

    Para un asset de videojuego low-poly, usa un modelo Smart Topology en lugar de remallar un modelo estándar. Consulta Modelos.

  • 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
    Description

    La pose para un modelo de personaje, a-pose o t-pose. Para no tener ninguna pose, omite pose_mode e is_a_t_pose.

  • Name
    is_a_t_pose
    Type
    boolean
    ⚠ obsoleto
    predeterminado false
    Description

    Usa pose_mode en su lugar. Si se debe generar el modelo en una pose A o T.

  • Name
    surface_mode
    Type
    string
    ⚠ obsoleto
    Description

    Usa ai_model en su lugar. No afecta el resultado, porque la generación de modelos que seleccionaba está retirada.

    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 reflejos y sombras de la textura de color base. El resultado es más limpio y funciona mejor bajo tu propia iluminación.

    Solo tiene efecto con el modelo de textura Meshy 6, y un modelo de textura que no lo admita devuelve 400 para true. Con model_type: smart-topology, o con ai_model: meshy-6-lite y su modelo de textura predeterminado, enviarlo devuelve 400.

  • Name
    moderation
    Type
    boolean
    predeterminado false
    Description

    Si se deben filtrar 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 una tarea.

  • Name
    target_formats
    Type
    string[]
    Description

    Los formatos de archivo a generar. Meshy genera y devuelve solo los formatos que enumeres, lo que puede acortar la tarea. Si lo omites, Meshy genera todos los formatos excepto 3mf, que solo obtienes si lo incluyes en la lista.

    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 de IA y redimensionar el modelo a esa medida. 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 cuando obtienes 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 cuando obtienes 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 puede ejecutarse. El mensaje de error indica qué problema encontró. Por ejemplo:

    • Parámetro faltante: 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 se agota el tiempo de espera.
    • Imagen demasiado grande: La imagen de image_url o texture_image_url supera los 20 MB.
    • Tamaño de imagen no válido: La imagen de image_url o texture_image_url tiene un lado más corto de 32 píxeles, o más de 178.956.970 píxeles (ancho × alto).
    • Data URI no válido: La cadena 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 las opciones de imagen: uno de estos:
      • Se envió image_enhancement con ai_model: "meshy-6-lite" o model_type: "smart-topology".
      • Se envió remove_lighting con model_type: "smart-topology", o con ai_model: "meshy-6-lite" y su modelo de textura predeterminado.
    • Modelo de textura no válido: texture_model no es uno de los valores disponibles.
    • Modelo de textura no disponible: texture_model es meshy-6 con un ai_model distinto de meshy-6. Envía meshy-7, meshy-n1 o meshy-6-lite, o bien omítelo.
    • Opción no compatible con el modelo de textura: La solicitud pide al modelo de textura una opción que no admite, como enable_pbr: true con meshy-n1 o una textura 4k con meshy-6-lite. Consulta Modelos.

    Corrige la solicitud y envíala de nuevo. Consulta Errores.

  • Name
    401 - Unauthorized
    Description

    La clave de API falta o no es válida. Revisa el encabezado Authorization.

  • Name
    402 - Payment Required
    Description

    Por ejemplo:

    • Créditos insuficientes: La cuenta no tiene suficientes créditos para esta tarea, o la cuenta 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
    403 - Forbidden
    Description

    La moderación de contenido bloqueó el prompt o una imagen de entrada. Cambia la entrada y vuelve a intentarlo.

  • Name
    404 - Not Found
    Description

    input_task_id no coincide con ninguna de tus tareas. Revisa el ID de la tarea y envía la solicitud de nuevo.

  • 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 por 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": null,
  "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": null,
    "consumed_credits": 30
  }
]

Parámetros

  • Name
    page_num
    Type
    integer
    predeterminado 1
    Description

    El número de página a devolver, hasta 255. Un valor mayor devuelve 400.

  • Name
    page_size
    Type
    integer
    predeterminado 10
    Description

    La cantidad de tareas por página, hasta 100.

  • Name
    sort_by
    Type
    string
    Description

    El orden de clasificación.

    Valores disponibles:

    • +created_at: las más antiguas primero
    • -created_at: las más recientes 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

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": null,
  "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 de Imagen a 3D

Un objeto de tarea de 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": null,
  "consumed_credits": 30
}
  • Name
    id
    Type
    string
    Description

    El ID de la tarea. Trátelo como una cadena opaca y no dependa 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 creó la tarea con should_remesh: true y save_pre_remeshed_model: true a la vez.

  • 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 creó 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. Úselas para previsualizar el modelo desde varios ángulos, por ejemplo en una canalización por lotes, sin descargar el GLB.

    Presente solo cuando creó 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° alrededor del eje vertical. Coincide con thumbnail_url.

    • Name
      right
      Type
      string
      Description

      La vista derecha, a 90°.

    • Name
      back
      Type
      string
      Description

      La vista trasera, 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

    Consulte geometry_resolution en su lugar.

  • Name
    geometry_resolution
    Type
    string
    Description

    El nivel Ultra con el que se ejecutó la tarea, 2k o 4k. Una tarea standard no incluye este campo.

  • Name
    progress
    Type
    integer
    Description

    Cuánto de la tarea está completado, como porcentaje. Es 0 hasta que la tarea comienza y 100 cuando tiene éxito.

  • Name
    started_at
    Type
    timestamp
    Description

    Hora en que comenzó la tarea, en milisegundos Unix. Es 0 hasta que la tarea comienza.

  • Name
    created_at
    Type
    timestamp
    Description

    Hora en que se creó la tarea, en milisegundos Unix.

  • Name
    expires_at
    Type
    timestamp
    Description

    Hora en que expira el resultado de la tarea, en milisegundos Unix.

  • Name
    finished_at
    Type
    timestamp
    Description

    Hora en que finalizó la tarea, 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 array 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 creó la tarea con enable_pbr: false.

    • Name
      normal
      Type
      string
      Description

      URL de descarga para el mapa de normales. El campo está ausente cuando creó la tarea con enable_pbr: false.

    • Name
      roughness
      Type
      string
      Description

      URL de descarga para el mapa de rugosidad. El campo está ausente cuando creó la tarea con enable_pbr: false.

    • Name
      emission
      Type
      string
      Description

      URL de descarga para el mapa de emisión. Meshy lo incluye solo cuando creó la tarea con todo lo siguiente:

      • ai_model: meshy-6, con su modelo de textura predeterminado
      • enable_pbr: true
      • un texture_resolution de 2k o 4k
  • Name
    preceding_tasks
    Type
    integer
    Description

    El número de tareas por delante de esta en la cola. El valor solo es significativo mientras la tarea está PENDING.

  • Name
    task_error
    Type
    object
    Description

    Los detalles del error cuando la tarea falla. Es null a menos que el estado sea FAILED. Consulte 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.