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.
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
# 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
previewpara 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 detallesmart-topology: una malla de Smart Topology. Elige el modelo conai_model(meshy-t2omeshy-t2.5).
Con
smart-topology, Meshy ignorashould_remeshydecimation_mode, y solo aceptatopology: 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-litemeshy-6meshy-7.1latest: Meshy 7.1meshy-7(obsoleto): envíameshy-7.1en 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 contarget_polycountmeshy-t2.5(predeterminado): detalle más nítido para assets de juegos, salida en triángulos y un número de caras que configuras contarget_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:
standard2k: ejecuta el pase Ultra a 2048³4k: ejecuta el pase Ultra a 4096³, para un detalle de superficie más fino
2knecesitameshy-7.1,latest, o el obsoletomeshy-7.4knecesitameshy-7.1olatest. Otros modelos devuelven400.
- Name
- ultra_mode
- Type
- boolean
- ⚠ obsoleto
- predeterminado false
- Description
Envía
geometry_resolutionen su lugar.ultra_mode: truees lo mismo quegeometry_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.
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áterostriangle: una malla de triángulos diezmada
La salida de Smart Topology es solo de triángulos. Enviar
quadconai_modelmeshy-t2omeshy-t2.5devuelve400.
- Name
- decimation_mode
- Type
- integer
- Description
Número de caras adaptativo, por nivel. Cuando lo configuras, Meshy ignora
target_polycount.Valores disponibles:
1: ultra2: alto3: medio4: 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: trueen un modelostandard. Meshy remalla (diezma) la malla hasta aproximadamente este número. Si configurasdecimation_mode, Meshy lo usa e ignoratarget_polycount. - Smart Topology: con
model_type: smart-topologyyai_modelmeshy-t2omeshy-t2.5. Meshy genera el modelo directamente con este número de caras. No se ejecuta ningún remallado, y no necesitasshould_remesh.
La siguiente tabla muestra el rango y el valor predeterminado para cada caso:
Caso Rango Predeterminado Remallado 100a30000030000meshy-t2100a150004000meshy-t2.5100a3000015000Un 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.
- Remallado: con
- Name
- symmetry_mode
- Type
- string
- ⚠ obsoleto
- predeterminado auto
- Description
Omítelo. Este parámetro no afecta la salida.
Valores disponibles:
off: desactiva la simetríaauto: aplica simetría según la geometría de entradaon: impone simetría durante la generación
- Name
- pose_mode
- Type
- string
- Description
La pose para un modelo de personaje,
a-poseot-pose. Para no tener pose, omitepose_modeeis_a_t_pose.
- Name
- is_a_t_pose
- Type
- boolean
- ⚠ obsoleto
- predeterminado false
- Description
Envía
pose_modeen 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
prompten busca de contenido dañino antes de generar. Si Meshy detecta contenido dañino, la solicitud devuelve400y 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:
glbobjfbxstlusdz3mf
- 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_urlcuando obtienes la tarea.thumbnail_urlno 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.
auto_size = true- Name
- origin_at
- Type
- string
- predeterminado bottom
- Description
Dónde colocar el origen del modelo,
bottomocenter.
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
promptomode. - Prompt demasiado largo:
promptsupera el límite de caracteres. - Modelo no compatible con Ultra:
geometry_resolutiones2ko4k, con unai_modelque no puede ejecutarlo.
Corrige la solicitud y envíala de nuevo. Consulta Errores.
- Falta un parámetro: Falta un parámetro requerido, como
- 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.
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
# 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
refinepara 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_modelmeshy-6, Meshy también genera un mapa de emisión, excepto contexture_resolution: 8k.meshy-6-lite,meshy-7ylatestno generan un mapa de emisión. Tampoco lo hace un refine de una previewmeshy-t2omeshy-t2.5que no estableceai_model. Conai_model: meshy-n1,truedevuelve400.
- 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×20484k: 4096×40968k: 8192×8192
Las resoluciones más altas capturan más detalle de la superficie.
4ky8knecesitanai_modelmeshy-6,meshy-7olatest. Conmeshy-n1, devuelven400. A8k, Meshy no genera un mapa de emisión.
- Name
- hd_texture
- Type
- boolean
- ⚠ obsoleto
- predeterminado false
- Description
Envía
texture_resolutionen su lugar.hd_texture: truees lo mismo quetexture_resolution: "4k". Si envías ambos, Meshy usatexture_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íatexture_promptotexture_image_url, no ambos. Si envías ambos, Meshy usatexture_prompt. Conai_model: meshy-n1, enviarlo devuelve400.
- 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,.pngo.webpde 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.Texturizar a partir de una imagen podría no funcionar bien cuando la forma en 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. La malla proviene del preview, así que en un refine
ai_modelelige solo el modelo de textura.Valores disponibles:
meshy-7: Meshy 7latest: el modelo de textura más reciente, actualmente Meshy 7meshy-6: Meshy 6meshy-6-lite: Meshy 6 Litemeshy-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 detexture_image_url. Sin este, Meshy usa la imagen de referencia que almacena un previewmeshy-7.1olatest. Cualquier otro preview devuelve400a menos que envíestexture_image_url. El preview puede tener como máximo 7,999,999 triángulos. Un preview con remesh a cuadriláteros devuelve400.
- Name
- moderation
- Type
- boolean
- predeterminado false
- Description
Si se debe filtrar
texture_promptytexture_image_urlen busca de contenido dañino antes de generar. Si Meshy detecta contenido dañino, la solicitud devuelve400y 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_modelesmeshy-6.meshy-7ylatestlo aceptan y lo ignoran, al igual que un refine de una previewmeshy-t2omeshy-t2.5que no estableceai_model. Enviarlo conmeshy-6-litedevuelve400. Conmeshy-n1,truedevuelve400.
- 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:
glbobjfbxstlusdz3mf
- 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_urlal obtener la tarea.thumbnail_urlno 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.
auto_size = true- Name
- origin_at
- Type
- string
- predeterminado bottom
- Description
Dónde colocar el origen del modelo,
bottomocenter.
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_idno 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_lightingconai_model: "meshy-6-lite". - No reference image for Meshy N1: Se envió
ai_model: meshy-n1sintexture_image_url, y el preview no tiene ninguna imagen de referencia que Meshy N1 pueda usar. Envíatexture_image_url. - Quad preview for Meshy N1: Se envió
ai_model: meshy-n1para un preview con remesh a cuadriláteros. Haz refine con otroai_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 otroai_model. - Unsupported option for Meshy N1: Se envió
ai_model: meshy-n1con una de estas opciones:texture_promptenable_pbr: truetexture_resolutionde4ku8khd_texture: truesintexture_resolutionremove_lighting: true
Corrige la solicitud y vuelve a enviarla. Consulta Errores.
- Invalid task ID:
- 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.
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
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.
| Mode | Modelo de ejemplo |
|---|---|
| Preview | ![]() |
| Refine | ![]() |
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
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.
Listar tareas de Texto a 3D
Devuelve una lista de tus tareas de Texto a 3D.
Request
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 devuelve400.
- 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.
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
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-previewpara una tarea de preview otext-to-3d-refinepara 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_formatsincluye3mf.
- Name
- prompt
- Type
- string
- Description
El
promptque 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_resolutionen su lugar.
- Name
- geometry_resolution
- Type
- string
- Description
El nivel Ultra con el que se ejecutó la tarea de preview,
2ko4k. El campo está ausente parastandard.
- 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_urlcon fondo transparente (RGBA). Presente solo cuando creó la tarea conalpha_thumbnail: truey Meshy renderizó la vista previa transparente.
- Name
- progress
- Type
- integer
- Description
Cuánto de la tarea está completado, como porcentaje. Es
0hasta que la tarea comienza y100cuando tiene éxito.
- Name
- started_at
- Type
- timestamp
- Description
Hora en que comenzó la tarea, en milisegundos Unix. Es
0hasta 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
0hasta que la tarea finaliza.
- Name
- status
- Type
- string
- Description
El estado de la tarea, uno de
PENDING,IN_PROGRESS,SUCCEEDED,FAILEDoCANCELED.
- 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_modelesmeshy-6-lite,meshy-7,meshy-7.1olatest.texture_resolutiones8k.- La tarea refina un preview de
meshy-t2omeshy-t2.5sin establecerai_model.
- Creó la tarea con
- 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
nulla menos que el estado seaFAILED. 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_PROGRESSoSUCCEEDED. Es0para una tareaFAILED, porque Meshy reembolsa los créditos cuando una tarea falla.

