API de Texto a 3D

Genera modelos 3D a partir de indicaciones de texto en tu propia aplicación.

Texto a 3D funciona en dos pasos. Primero, crea una tarea de preview (mode: "preview") para generar una malla 3D sin textura, de modo que puedas revisar la forma. Luego, envía el ID de la tarea de preview exitosa a una tarea de refine (mode: "refine") para texturizar la malla. Ambos pasos usan el mismo endpoint.

POST/openapi/v2/text-to-3d

Crear una tarea de preview de Texto a 3D

Crea una tarea de preview de Texto a 3D, que genera una malla 3D sin textura (solo geometría) a partir de un prompt de texto. Este es el primer paso del flujo de trabajo de dos pasos. Después de que el preview tenga éxito, envía su ID de tarea en una tarea de refine para texturizar la malla. Consulta Crear una tarea de refine de Texto a 3D. Para ver el esquema completo de la respuesta, consulta El objeto de tarea de Texto a 3D.

La tarea se ejecuta en segundo plano. Para saber cuánto tiempo suele tardar una tarea, consulta Tiempos de procesamiento.

Request

POST

/openapi/v2/text-to-3d

# Simple preview with required params only
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a monster mask"
}'

# Preview with Ultra 4K geometry, remesh, and A-pose
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a futuristic robot warrior",
  "ai_model": "meshy-7.1",
  "geometry_resolution": "4k",
  "should_remesh": true,
  "target_polycount": 100000,
  "pose_mode": "a-pose",
  "target_formats": ["glb"]
}'

Response

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

Parámetros

Name
mode
Type
string
Requerido
Description
El paso del flujo de trabajo de dos pasos. Envía preview para crear una tarea de preview.
Name
prompt
Type
string
Requerido
Description
Texto que describe el objeto a generar, hasta 800 caracteres. Un texto más largo devuelve 400.
Name
model_type
Type
string
predeterminado standard
Description
El tipo de malla 3D a generar.
Valores disponibles:
- standard: una malla 3D de alto detalle
- smart-topology: una malla Smart Topology. Elige el modelo con ai_model (meshy-t2 o meshy-t2.5).
Con smart-topology, Meshy ignora should_remesh 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):
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest: Meshy 7.1
- meshy-7 (obsoleto): envía meshy-7.1 en su lugar
Modelos Smart Topology (model_type: smart-topology):
- meshy-t2: topology más limpia, partes separadas de forma nativa, salida en triángulos y un número de caras que defines con target_polycount
- meshy-t2.5 (predeterminado): detalle más nítido para assets de juegos, salida en triángulos y un número de caras que defines con target_polycount
Name
geometry_resolution
Type
string
predeterminado standard
Description
La pasada de generación de geometría. Se aplica solo a tareas de preview. Un refine con este parámetro devuelve 400.
Valores disponibles:
- standard
- 2k: ejecuta la pasada Ultra a 2048³
- 4k: ejecuta la pasada Ultra a 4096³, para un detalle de superficie más fino
2k necesita meshy-7.1, latest, o el obsoleto meshy-7. 4k necesita meshy-7.1 o latest. Otros modelos devuelven 400.
Name
ultra_mode
Type
boolean
⚠ obsoleto
predeterminado false
Description
Envía geometry_resolution en su lugar. ultra_mode: true es lo mismo que geometry_resolution: "2k".
Name
should_remesh
Type
boolean
predeterminado true (meshy-6-lite), false (other models)
Description
Si se debe remallar el modelo después de la generación. Para obtener el modelo 3D de mayor calidad, envía 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. Enviar quad con ai_model meshy-t2 o meshy-t2.5 devuelve 400.
Name
decimation_mode
Type
integer
Description
Número de caras adaptativo, por nivel. Cuando lo defines, Meshy ignora target_polycount.
Valores disponibles:
- 1: ultra
- 2: alto
- 3: medio
- 4: bajo

Name
target_polycount
Type
integer
Description
El número de caras objetivo. El resultado puede diferir del objetivo, según la geometría. Se aplica en dos casos distintos:
- Remallado: con should_remesh: true en un modelo standard. Meshy remalla (decima) la malla hasta aproximadamente este número. Si defines decimation_mode, Meshy lo usa e ignora target_polycount.
- Smart Topology: con model_type: smart-topology y ai_model meshy-t2 o meshy-t2.5. Meshy genera el modelo directamente con este número de caras. No se ejecuta ningún remallado, y no necesitas should_remesh.
La siguiente tabla muestra el rango y el valor predeterminado para cada 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. Este parámetro no afecta la salida.
Valores disponibles:
- off: desactiva la simetría
- auto: aplica simetría según la geometría de entrada
- on: impone simetría durante la generación
Name
pose_mode
Type
string
predeterminado ""
Description
La pose del 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
Envía pose_mode en su lugar. Si se debe generar el modelo en pose A o pose T.
Name
art_style
Type
string
⚠ obsoleto
predeterminado realistic
Description
Omítelo. Meshy lo ignora.
Name
moderation
Type
boolean
predeterminado false
Description
Si se debe analizar prompt en busca de contenido dañino antes de generar. 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 a generar. Meshy genera y devuelve solo estos formatos, lo que puede acortar la tarea. Si lo omites, Meshy genera todos los formatos excepto 3mf, que solo genera cuando lo solicitas.
Valores disponibles:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
predeterminado false
Description
Si también se debe renderizar un preview con fondo transparente (RGBA), devuelto en alpha_thumbnail_url al obtener la tarea. thumbnail_url no cambia.
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 según ella. Meshy coloca el origen en la parte inferior a menos que definas origin_at.

Solo aplica cuando auto_size = true

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

Devuelve

El campo result de la respuesta contiene el ID de la nueva tarea de Texto 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: Falta un parámetro requerido, como prompt o mode.
- Prompt demasiado largo: prompt supera el límite de caracteres.
- Modelo no compatible con Ultra: geometry_resolution es 2k o 4k, con un ai_model que no puede ejecutarlo.
Corrige la solicitud y envíala de nuevo. Consulta Errores.
Name
401 - Unauthorized
Description
Falta la clave de API 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 tu configuración de suscripción y vuelve a intentarlo.
Name
429 - Too Many Requests
Description
Superaste tu límite de tasa. Espera y vuelve a intentarlo. Consulta Límites de tasa.

POST/openapi/v2/text-to-3d

Crear una tarea de refine de Texto a 3D

Crea una tarea de refine de Texto a 3D, que texturiza la malla de una tarea de preview completada. Envía el ID de una tarea de preview exitosa como preview_task_id. Consulta Crear una tarea de preview de Texto a 3D. Este es el segundo paso del flujo de trabajo de dos pasos.

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

Request

POST

/openapi/v2/text-to-3d

# Basic refine task
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "enable_pbr": true
}'

# Refine with auto-size and GLB format
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "target_formats": ["glb"],
  "auto_size": true
}'

Response

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

Parámetros

Name
mode
Type
string
Requerido
Description
El paso del flujo de trabajo de dos pasos. Envía refine para crear una tarea de refine.
Name
preview_task_id
Type
string
Requerido
Description
El ID de la tarea de preview a texturizar. La tarea de preview debe tener el estado SUCCEEDED.
Name
enable_pbr
Type
boolean
predeterminado false
Description
Indica si se deben generar también mapas PBR (metallic, roughness y normal) junto con el color base.
Con ai_model meshy-6, Meshy también genera un mapa de emisión, excepto con texture_resolution: 8k. meshy-6-lite, meshy-7, meshy-7.1 y latest no generan un mapa de emisión. Tampoco lo genera un refine de una preview de meshy-t2 o meshy-t2.5 que no establezca ai_model.
Name
texture_resolution
Type
string
predeterminado 2k
Description
La resolución de la textura de color base. Se aplica solo a las tareas de refine. Una preview con este parámetro devuelve 400.
Valores disponibles:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
Las resoluciones más altas capturan más detalle de superficie. 4k y 8k necesitan ai_model meshy-6, meshy-7.1 o latest. A 8k, Meshy no genera un mapa de emisión.
Name
hd_texture
Type
boolean
⚠ obsoleto
predeterminado false
Description
Envía texture_resolution en su lugar. hd_texture: true es igual a texture_resolution: "4k". Si envías ambos, Meshy usa texture_resolution.
Name
texture_prompt
Type
string
Description
Texto que guía la texturización, de hasta 800 caracteres. Un texto más largo devuelve 400. Envía texture_prompt o texture_image_url, no ambos. Si envías ambos, Meshy usa texture_prompt.
Name
texture_image_url
Type
string
Description
Una imagen 2D que guía la texturización, 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 un máximo de 20 MB.
La texturización a partir de una imagen podría no funcionar bien cuando la forma de la imagen difiere mucho del modelo.
Name
ai_model
Type
string
predeterminado inherited from the preview task
Description
El modelo de IA que texturiza la malla.
Valores disponibles:
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest: Meshy 7.1
- meshy-7 (obsoleto): envía meshy-7.1 en su lugar
Omítelo para usar el modelo de la tarea de preview, de modo que la preview y su refine se ejecuten de principio a fin en el mismo modelo. Envía un valor para sobrescribirlo. Un latest explícito se resuelve de la misma manera que en la tarea de preview, de modo que una preview latest y su refine latest siempre usan el mismo modelo de texturizado.
Name
moderation
Type
boolean
predeterminado false
Description
Indica si se debe analizar texture_prompt y texture_image_url en busca de contenido dañino antes de generar. Si Meshy detecta contenido dañino, la solicitud devuelve 400 y Meshy no crea la tarea.
Name
remove_lighting
Type
boolean
predeterminado true
Description
Indica si se deben eliminar los reflejos y las sombras de la textura de color base. El resultado más limpio funciona mejor bajo iluminación personalizada.
Solo tiene efecto cuando ai_model es meshy-6. meshy-7.1 y latest lo aceptan pero lo ignoran, al igual que un refine de una preview de meshy-t2 o meshy-t2.5 que no establezca ai_model. Enviarlo con meshy-6-lite devuelve 400.
Name
target_formats
Type
string[]
Description
Los formatos de archivo a generar. Meshy genera y devuelve solo estos formatos, lo que puede acortar la tarea. Si lo omites, Meshy genera todos los formatos excepto 3mf, que genera únicamente cuando lo solicitas.
Valores disponibles:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
predeterminado false
Description
Indica si se debe renderizar también una vista previa con fondo transparente (RGBA), devuelta en alpha_thumbnail_url al obtener la tarea. thumbnail_url no cambia.
Name
auto_size
Type
boolean
predeterminado false
Description
Indica si se debe estimar la altura real del objeto en el mundo real mediante visión por IA y redimensionar el modelo a esa altura. Meshy coloca el origen en la parte inferior a menos que establezcas origin_at.

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 devueltos

El campo result de la respuesta contiene el ID de la nueva tarea de Texto 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:
- ID de tarea inválido: preview_task_id no es válido o no coincide con ninguna de tus tareas de preview.
- Tarea no lista: La tarea de preview aún no se ha completado con éxito.
- Incompatibilidad de modelo: El modelo de IA de la tarea de preview no funciona con el modelo de refine solicitado.
- Modelo no compatible con remove_lighting: Se envió remove_lighting con ai_model: "meshy-6-lite".
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 suficientes créditos para esta tarea, o la cuenta alcanzó un límite de créditos. Verifica tu saldo de créditos y vuelve a intentarlo.
- Plan gratuito: Crear una tarea requiere un plan de pago. Actualiza tu plan en la configuración de suscripción y vuelve a intentarlo.
Name
429 - Too Many Requests
Description
Excediste tu límite de tasa. Espera y vuelve a intentarlo. Consulta Límites de tasa.

GET/openapi/v2/text-to-3d/:id

Obtener una tarea de Texto a 3D

Devuelve una tarea de Texto a 3D por su ID. Funciona tanto para tareas de preview como de refine.

Request

GET

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?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=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "prompt": "a monster mask",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 20
}

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 Texto a 3D.

Ejemplos

La siguiente tabla muestra un modelo de ejemplo para cada mode.

Mode	Modelo de ejemplo
Preview
Refine

DELETE/openapi/v2/text-to-3d/:id

Eliminar una tarea de Texto a 3D

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

Request

DELETE

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v2/text-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.

No se puede eliminar una tarea IN_PROGRESS. 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/v2/text-to-3d

Listar tareas de Texto a 3D

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

Request

GET

/openapi/v2/text-to-3d

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-3d-preview",
    "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=***",
      "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "prompt": "a monster mask",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
      }
    ],
    "preceding_tasks": 0,
    "task_error": {

      "message": ""

    },

    "consumed_credits": 20
  }
]

Parámetros

Name
page_num
Type
integer
predeterminado 1
Description
El número de página a devolver.
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 Texto a 3D.

GET/openapi/v2/text-to-3d/:id/stream

Transmitir una tarea de Texto a 3D en streaming

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

Request

GET

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

curl -N https://api.meshy.ai/openapi/v2/text-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",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
},
"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": 20
}

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 Texto 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 Texto a 3D

Un objeto de tarea de Texto a 3D describe una tarea que genera un modelo 3D a partir de un prompt de texto. Contiene el estado, el progreso y los archivos del modelo cuando la tarea tiene éxito. Texto a 3D tiene dos etapas, preview y refine. Una tarea preview genera un modelo 3D que contiene solo la malla, y una tarea refine genera un modelo 3D texturizado a partir del resultado del preview.

Propiedades

Example Text to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  },
  "prompt": "a monster mask",
  "texture_prompt": "green slimy skin with scales and warts",
  "texture_image_url": "",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "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": 20
}

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, text-to-3d-preview para una tarea preview o text-to-3d-refine para una tarea refine.
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
  usdz
  Type
  string
  Description
  El archivo USDZ.
- Name
  obj
  Type
  string
  Description
  El archivo OBJ.
- Name
  mtl
  Type
  string
  Description
  El archivo MTL.
- Name
  stl
  Type
  string
  Description
  El archivo STL.
- Name
  3mf
  Type
  string
  Description
  El archivo 3MF. Presente solo cuando target_formats incluye 3mf.
Name
prompt
Type
string
Description
El prompt que envió para crear la tarea, sin modificar.
Name
texture_prompt
Type
string
Description
El prompt de texto que envió para guiar el texturizado en la etapa refine.
Name
ultra_mode
Type
boolean
⚠ obsoleto
Description
En su lugar, consulte geometry_resolution.
Name
geometry_resolution
Type
string
Description
El nivel Ultra con el que se ejecutó la tarea preview, 2k o 4k. El campo está ausente para standard.
Name
texture_image_url
Type
string
Description
URL de descarga para la imagen que envió para guiar el texturizado.
Name
thumbnail_url
Type
string
Description
URL de descarga para una imagen de miniatura del modelo 3D.
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
video_url
Type
string
⚠ obsoleto
Description
No dependa de este campo, porque una versión futura lo eliminará. URL de descarga para el video de vista previa.
Name
progress
Type
integer
Description
Cuánto de la tarea está completado, como un porcentaje. Es 0 hasta que la tarea comienza y 100 cuando tiene éxito.
Name
started_at
Type
timestamp
Description
Hora en que la tarea comenzó, 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
finished_at
Type
timestamp
Description
Hora en que la tarea terminó, en milisegundos Unix. Es 0 hasta que la tarea termina.
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
URLs de descarga para los mapas de textura generados, como un array de objetos. Normalmente contiene un objeto. Cada objeto tiene estos campos:
- Name
  base_color
  Type
  string
  Description
  El mapa de color base.
- Name
  metallic
  Type
  string
  Description
  El mapa metálico. Ausente cuando creó la tarea con enable_pbr: false.
- Name
  normal
  Type
  string
  Description
  El mapa de normales. Ausente cuando creó la tarea con enable_pbr: false.
- Name
  roughness
  Type
  string
  Description
  El mapa de rugosidad. Ausente cuando creó la tarea con enable_pbr: false.
- Name
  emission
  Type
  string
  Description
  El mapa de emisión. Ausente en cualquiera de estos casos:
  
  Creó la tarea con enable_pbr: false.
  
  ai_model es meshy-6-lite, meshy-7, meshy-7.1 o latest.
  
  texture_resolution es 8k.
  
  La tarea refina un preview de meshy-t2 o meshy-t2.5 sin establecer ai_model.
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. 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.