API de Convertir
Convierte un modelo 3D a otros formatos de archivo, a partir de una tarea de Meshy o de un archivo de modelo.
Crear una tarea de Convertir
Crea una tarea de Convertir. La tarea se ejecuta en segundo plano. Para saber cuánto suele tardar una tarea, consulta Tiempos de procesamiento.
Request
curl https://api.meshy.ai/openapi/v1/convert \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"target_formats": ["fbx", "stl"]
}'
Response
{
"result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}
Parámetros
- Name
- input_task_id
- Type
- string
- Requerido
- Description
Obligatorio a menos que envíes
model_url. El ID de una tarea que produjo un modelo 3D, por ejemplo una tarea de Texto a 3D, Imagen a 3D, Remallado, Redimensionar o Retexturizar. La tarea debe provenir de la API y tener el estadoSUCCEEDED.
- Name
- model_url
- Type
- string
- Requerido
- Description
Obligatorio a menos que envíes
input_task_id. El modelo a convertir, como una URL pública o un Data URI. Si envías ambos, Meshy usainput_task_id.El modelo debe ser un archivo GLB, glTF, OBJ, FBX o STL de como máximo 400 MB desde una URL
httpohttps, o 100 MB como Data URI. Para un Data URI, usa el MIME typeapplication/octet-stream.Un archivo de más de 100 MB también debe cumplir estas reglas:
- Un archivo GLB, glTF, FBX u OBJ puede tener como máximo 10,000,000 caras. Meshy cuenta las caras como triángulos, por lo que un cuadrilátero cuenta como 2, y una malla dibujada más de una vez cuenta una vez por cada copia.
- Un archivo FBX debe ser FBX binario 7.1 o más reciente.
- Un archivo GLB o glTF no debe usar compresión Draco.
- Name
- target_formats
- Type
- string[]
- Requerido
- Description
Los formatos de archivo a generar. Indica al menos uno. Una lista faltante o vacía devuelve
400.Valores disponibles:
glbfbxobjusdzblendstl3mf
Devuelve
El campo result de la respuesta contiene el ID de la nueva tarea de Convertir.
Modos de fallo
- Name
400 - Bad Request- Description
La solicitud no puede ejecutarse. El mensaje de error indica qué problema se encontró. Por ejemplo:
- Falta un parámetro: No se envió ni
model_urlniinput_task_id. - Falta
target_formats:target_formatsfalta o no incluye ningún formato. - Tarea de entrada no válida:
input_task_idno es una tarea de API exitosa con un archivo de modelo. - Formato de modelo no válido: El archivo de
model_urltiene una extensión no admitida. - URL inalcanzable: Meshy no puede descargar el archivo de
model_url. - Archivo de modelo demasiado grande: El archivo de
model_urlsupera los 400 MB desde una URLhttpohttps, o supera los 100 MB como Data URI. - Demasiadas caras: El archivo de
model_urlsupera los 100 MB y tiene más de 10,000,000 caras. Reduce el número de caras y vuelve a enviar el archivo. - FBX ASCII de más de 100 MB: El archivo de
model_urles un FBX ASCII de más de 100 MB. Envíalo como FBX binario o GLB. - Archivo de modelo ilegible: El archivo de
model_urlsupera los 100 MB y Meshy no puede leer su encabezado. Por ejemplo, es un GLB o glTF comprimido con Draco, o un FBX binario anterior a la versión 7.1. - Encabezado del modelo demasiado complejo: El archivo de
model_urlsupera los 100 MB y su encabezado tiene demasiadas mallas, nodos o registros para verificar. Reduce el número de objetos en el archivo y vuelve a enviarlo.
Corrige la solicitud y envíala de nuevo. Consulta Errores.
- Falta un parámetro: No se envió ni
- 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. Mejora tu plan en la configuración de tu suscripción y vuelve a intentarlo.
- Name
403 - Forbidden- Description
input_task_ides un modelo de bajorrelieve, que este endpoint no puede convertir. El mensaje esThis model type does not support this operation. Envía un modelo diferente.
- Name
404 - Not Found- Description
input_task_idno coincide con ninguna de tus tareas. Verifica el ID de la tarea y vuelve a enviar la solicitud.
- Name
429 - Too Many Requests- Description
Superaste tu límite de tasa. Espera y vuelve a intentarlo. Consulta Límites de tasa.
Obtener una tarea de Convertir
Devuelve una tarea de Convertir por su ID.
Request
curl https://api.meshy.ai/openapi/v1/convert/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "convert",
"model_urls": {
"fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
"stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
},
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000001000,
"task_error": null,
"consumed_credits": 1
}
Parámetros
- Name
- id
- Type
- path
- Description
El ID de la tarea de la respuesta de creación.
Devuelve
Eliminar una tarea de Convertir
Elimina permanentemente una tarea de Convertir, incluidos sus modelos y datos. No puedes deshacer una eliminación.
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v1/convert/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-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 utilizó al crearla.
Una tarea IN_PROGRESS no se puede eliminar. La solicitud devuelve 409 Conflict,
y la tarea sigue ejecutándose. Meshy no reembolsa una tarea que ya ha comenzado,
así que eliminarla te costaría tanto los créditos como el resultado. Espera a que
alcance el estado SUCCEEDED, FAILED o CANCELED, y luego elimínala.
Eliminar una tarea en un estado final (SUCCEEDED, FAILED o CANCELED)
no reembolsa sus créditos.
Devuelve
200 OK cuando la tarea se elimina, o 409 Conflict cuando la tarea está
IN_PROGRESS.
Listar tareas de Convertir
Devuelve una lista de tus tareas de Convertir.
Request
curl https://api.meshy.ai/openapi/v1/convert?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "convert",
"model_urls": {
"fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
"stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
},
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000001000,
"task_error": null,
"consumed_credits": 1
}
]
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
El número de tareas por página, hasta
100.
- Name
- sort_by
- Type
- string
- Description
El orden de clasificación.
Valores disponibles:
+created_at: las más antiguas primero-created_at: las más recientes primero
Devuelve
Una lista paginada de objetos de tarea de Convertir.
Transmitir una tarea de Convertir
Transmite las actualizaciones de una tarea de Convertir como eventos enviados por el servidor (SSE).
Request
curl -N https://api.meshy.ai/openapi/v1/convert/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response Stream
// Message event examples illustrate task progress.
event: message
data: {
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"progress": 0,
"status": "PENDING"
}
event: message
data: {
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "convert",
"model_urls": {
"fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
"stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
},
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000001000,
"task_error": null,
"consumed_credits": 1
}
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 Convertir 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 Convert
Un objeto de tarea Convert describe una conversión de formato de un modelo 3D. Contiene el estado, el progress y los archivos del modelo cuando la tarea se completa con éxito.
Propiedades
- Name
- id
- Type
- string
- Description
El ID de la tarea. Trátelo como una cadena opaca y no dependa de su formato.
- Name
- type
- Type
- string
- Description
El tipo de tarea, siempre
convert.
- Name
- model_urls
- Type
- object
- Description
URLs de descarga para el modelo convertido, una por formato de archivo. Solo los formatos en
target_formatstienen URLs. Un formato que no solicitó no tiene clave, en lugar de tener una cadena vacía.
- Name
- progress
- Type
- integer
- Description
Cuánto de la tarea está completado, como un porcentaje. Es
0hasta que la tarea comienza y100cuando se completa con éxito.
- Name
- status
- Type
- string
- Description
El estado de la tarea, uno de
PENDING,IN_PROGRESS,SUCCEEDED,FAILEDoCANCELED.
- 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á en
PENDING.
- Name
- created_at
- Type
- timestamp
- Description
Hora en que se creó la tarea, en milisegundos Unix.
- Name
- started_at
- Type
- timestamp
- Description
Hora en que comenzó la tarea, en milisegundos Unix. Es
0hasta que la tarea comienza.
- Name
- finished_at
- Type
- timestamp
- Description
Hora en que finalizó la tarea, en milisegundos Unix. Es
0hasta que la tarea finaliza.
- Name
- expires_at
- Type
- timestamp
- Description
Hora en que expiran las URLs de descarga de la tarea, en milisegundos Unix. Es
0hasta que la tarea finaliza.
- Name
- texture_urls
- Type
- array
- Description
URLs de descarga para los mapas de textura del modelo, cuando la tarea se completa con éxito: un arreglo de objetos, uno por conjunto de texturas. Cada objeto tiene una URL
base_color, y también puede tener URLsmetallic,roughness,normal,emissionymetallic_roughness. Esnullhasta que la tarea se completa con éxito, y un arreglo vacío cuando el modelo no tiene mapas de textura.
- 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, que es
1para una tarea Convert. Es0para una tareaFAILED.