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

Crea una tarea de vista previa 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 la vista previa se complete con é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 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 vista previa.

  • 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 de 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. Se retira el 31 de diciembre de 2026.

    Modelos de 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 configuras 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 configuras con target_polycount

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

  • Name
    geometry_resolution
    Type
    string
    predeterminado standard
    Description

    El pase de generación de geometría. Se aplica solo a las tareas de preview. Un refine con este parámetro devuelve 400.

    Valores disponibles:

    • standard
    • 2k: ejecuta el pase Ultra a 2048³
    • 4k: ejecuta el pase 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 diezmada

    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 configuras, 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 (diezma) la malla hasta aproximadamente este número. Si configuras 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:

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

    Un valor fuera del rango devuelve 400.

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

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

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

  • 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 una 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 una vista previa con fondo transparente (RGBA), devuelta en alpha_thumbnail_url cuando obtienes 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 de IA y redimensionar el modelo según esa altura. Meshy coloca el origen en la parte inferior a menos que configures 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:

    • 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 créditos suficientes 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
    429 - Too Many Requests
    Description

    Excediste 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
}'

# Refine with Meshy N1 from the preview's stored reference image
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",
  "ai_model": "meshy-n1"
}'

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

    Si también se deben generar 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 y latest no generan un mapa de emisión. Tampoco lo hace un refine de una preview meshy-t2 o meshy-t2.5 que no establece ai_model. Con ai_model: meshy-n1, true devuelve 400.

  • Name
    texture_resolution
    Type
    string
    predeterminado 2k
    Description

    La resolución de la textura de color base. Se aplica solo a tareas de refine. Un 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 la superficie. 4k y 8k necesitan ai_model meshy-6, meshy-7 o latest. Con meshy-n1, devuelven 400. 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 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 texturización, 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. Con ai_model: meshy-n1, enviarlo devuelve 400.

  • 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, por ejemplo data:image/jpeg;base64,<your base64-encoded image data>.

    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).

    Con ai_model: meshy-n1, Meshy texturiza a partir de esta imagen como la vista frontal.

  • Name
    ai_model
    Type
    string
    predeterminado inherited from the preview task
    Description

    El modelo de IA que texturiza la malla. La malla proviene del preview, así que en un refine ai_model elige solo el modelo de textura.

    Valores disponibles:

    • meshy-7: Meshy 7
    • latest: el modelo de textura más reciente, actualmente Meshy 7
    • meshy-6: Meshy 6
    • meshy-6-lite: Meshy 6 Lite
    • meshy-n1: una textura de color base de 2K a partir de una imagen de referencia únicamente. Sin prompt de texto, sin mapas PBR, sin 4K ni 8K.

    Los valores anteriores son modelos de textura. Omítelo para texturizar con el modelo que coincide con el preview. Envía un valor para anularlo.

    Con meshy-n1, Meshy texturiza a partir de texture_image_url. Sin este, Meshy usa la imagen de referencia que almacena un preview meshy-7.1 o latest. Cualquier otro preview devuelve 400 a menos que envíes texture_image_url. El preview puede tener como máximo 7,999,999 triángulos. Un preview con remesh a cuadriláteros devuelve 400.

  • Name
    moderation
    Type
    boolean
    predeterminado false
    Description

    Si se debe filtrar 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

    Si se deben eliminar los brillos y 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 y latest lo aceptan y lo ignoran, al igual que un refine de una preview meshy-t2 o meshy-t2.5 que no establece ai_model. Enviarlo con meshy-6-lite devuelve 400. Con meshy-n1, true 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 solo 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 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

    Si se debe estimar la altura real del objeto con visión de 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:

    • Invalid task ID: preview_task_id no es válido, o no coincide con ninguna de tus tareas de preview.
    • Task not ready: La tarea de preview aún no ha tenido éxito.
    • Model mismatch: El modelo de IA de la tarea de preview no funciona con el modelo de refine solicitado.
    • Unsupported model for remove_lighting: Se envió remove_lighting con ai_model: "meshy-6-lite".
    • No reference image for Meshy N1: Se envió ai_model: meshy-n1 sin texture_image_url, y el preview no tiene ninguna imagen de referencia que Meshy N1 pueda usar. Envía texture_image_url.
    • Quad preview for Meshy N1: Se envió ai_model: meshy-n1 para un preview con remesh a cuadriláteros. Haz refine con otro ai_model.
    • Too many triangles for Meshy N1: Con ai_model: meshy-n1, el preview tiene más de 7,999,999 triángulos. Haz refine con otro ai_model.
    • Unsupported option for Meshy N1: Se envió ai_model: meshy-n1 con una de estas opciones:
      • texture_prompt
      • enable_pbr: true
      • texture_resolution de 4k u 8k
      • hd_texture: true sin texture_resolution
      • remove_lighting: true

    Corrige la solicitud y vuelve a enviarla. 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:

    • Insufficient credits: 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.
    • Free plan: Crear una tarea requiere un plan de pago. Mejora tu plan en tu configuración de 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
    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": null,

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

ModeModelo de ejemplo
PreviewPreview model
RefineRefined model

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": null,

    "consumed_credits": 20
  }
]

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


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

Transmitir una tarea de Texto a 3D

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": null,

"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 de preview genera un modelo 3D que solo contiene la malla, y una tarea de refine genera un modelo 3D con textura 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": null,

  "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 de preview o text-to-3d-refine para una tarea de 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 de refine.

  • 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 de preview, 2k o 4k. El campo está ausente para standard.

  • Name
    texture_image_url
    Type
    string
    Description

    URL de descarga de la imagen que envió para guiar el texturizado.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL de descarga de una imagen en miniatura del modelo 3D.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    URL de descarga de 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
    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
    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

    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. 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.