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.

POST/openapi/v1/convert

Crear una tarea de Convert

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

Request

POST

/openapi/v1/convert

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 la tarea de Meshy cuyo modelo quieres convertir. La tarea debe tener el estado SUCCEEDED.

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 usa input_task_id.
El modelo debe ser un archivo GLB, glTF, OBJ, FBX o STL de como máximo 400 MB desde una URL http o https, o de 100 MB como Data URI. Para un Data URI, usa el MIME type application/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, de modo que un cuadrilátero cuenta como 2, y una malla dibujada más de una vez cuenta una vez por 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:
- glb
- fbx
- obj
- usdz
- blend
- stl
- 3mf

Devuelve

El campo result de la respuesta contiene el ID de la nueva tarea de Convert.

Modos de fallo

Name
400 - Bad Request
Description
La solicitud no puede ejecutarse. El mensaje de error indica qué problema se encontró. Por ejemplo:
- Parámetro faltante: No se envió ni model_url ni input_task_id.
- Falta target_formats: target_formats falta o no lista ningún formato.
- Tarea de entrada no válida: input_task_id no corresponde a una tarea exitosa.
- Formato de modelo no válido: El archivo de model_url tiene una extensión no admitida.
- URL inaccesible: Meshy no puede descargar el archivo de model_url.
- Archivo de modelo demasiado grande: El archivo de model_url supera los 400 MB desde una URL http o https, o supera los 100 MB como Data URI.
- Demasiadas caras: El archivo de model_url supera 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_url es un FBX ASCII de más de 100 MB. Envíalo como FBX binario o GLB.
- Archivo de modelo ilegible: El archivo de model_url supera 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 7.1.
- Encabezado del modelo demasiado complejo: El archivo de model_url supera 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 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:
- 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 suscripción y vuelve a intentarlo.
Name
403 - Forbidden
Description
input_task_id es un modelo de bajorrelieve, que este endpoint no puede convertir. El mensaje es This model type does not support this operation. Envía un modelo diferente.
Name
404 - Not Found
Description
input_task_id no 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.

GET/openapi/v1/convert/:id

Obtener una tarea de Convertir

Devuelve una tarea de Convertir por su ID.

Request

GET

/openapi/v1/convert/:id

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

El objeto de tarea de Convertir.

DELETE/openapi/v1/convert/:id

Eliminar una tarea de Convertir

Elimina permanentemente una tarea de Convertir, incluidos sus modelos y datos. No puedes deshacer una eliminación.

Request

DELETE

/openapi/v1/convert/:id

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.

GET/openapi/v1/convert

Listar tareas de Convert

Devuelve una lista de tus tareas de Convert.

Request

GET

/openapi/v1/convert

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.

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

Devuelve

Una lista paginada de objetos de tarea de Convert.

GET/openapi/v1/convert/:id/stream

Transmitir una tarea de Convertir

Transmite las actualizaciones de una tarea de Convertir como eventos enviados por el servidor (SSE).

Request

GET

/openapi/v1/convert/:id/stream

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 Convertir

Un objeto de tarea Convertir 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 correctamente.

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 cada formato de archivo. Solo los formatos en target_formats tienen URLs. Un formato que no solicitó no tiene clave, en lugar de una cadena vacía.
Name
progress
Type
integer
Description
Cuánto se ha completado de la tarea, como porcentaje. Es 0 hasta que la tarea comienza y 100 cuando se completa correctamente.
Name
status
Type
string
Description
El estado de la tarea, uno de PENDING, IN_PROGRESS, SUCCEEDED, FAILED o CANCELED.
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 0 hasta que la tarea comienza.
Name
finished_at
Type
timestamp
Description
Hora en que finalizó la tarea, en milisegundos Unix. Es 0 hasta que la tarea finaliza.
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 1 para una tarea Convertir. Es 0 para una tarea FAILED.