API de Convertir

La API de Convertir te permite convertir modelos 3D existentes a diferentes formatos de archivo.

POST/openapi/v1/convert

Crear una tarea de conversión

Este endpoint crea una nueva tarea de conversión de formato.

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

Parámetros

Solo se requiere uno de input_task_id o model_url. Si se proporcionan ambos, input_task_id tiene prioridad.

Name
input_task_id
Type
string
Requerido
Description
El ID de una tarea de Meshy completada cuyo modelo deseas convertir. La tarea debe tener un estado SUCCEEDED.

Name
model_url
Type
string
Requerido
Description
Una URL de acceso público o un data URI que apunte a un archivo de modelo 3D. Formatos admitidos: .glb, .gltf, .obj, .fbx, .stl. Para Data URIs, usa el MIME type: application/octet-stream.
Tamaño máximo de archivo: 100 MB.

Name
target_formats
Type
string[]
Requerido
Description
Una lista de formatos de salida para el modelo convertido. Valores disponibles: glb, fbx, obj, usdz, blend, stl, 3mf.

Devuelve

La propiedad result de la respuesta contiene el id de la tarea de conversión recién creada.

Modos de fallo

400 - Bad Request

La solicitud fue inaceptable. Causas comunes:

Parámetro faltante: Se debe proporcionar model_url o input_task_id.
target_formats faltante: Se debe especificar al menos un formato de destino.
Tarea de entrada inválida: input_task_id debe hacer referencia a una tarea exitosa.
Formato de modelo inválido: model_url apunta a un archivo con una extensión no compatible.
URL inaccesible: No se pudo descargar model_url.
Archivo de modelo demasiado grande: El archivo de model_url supera los 100 MB.

401 - Unauthorized

Falló la autenticación. Por favor, verifica tu clave de API.

402 - Payment Required

Créditos insuficientes para realizar esta tarea.

429 - Too Many Requests

Has excedido tu límite de tasa.

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

GET/openapi/v1/convert/:id

Recuperar una tarea de conversión

Este endpoint recupera una tarea de conversión por su ID.

Parámetros

Name
id
Type
path
Description
El ID de la tarea de conversión que se va a recuperar.

Devuelve

El objeto de la tarea de conversión.

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": {
      "glb": "",
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "obj": "",
      "usdz": "",
      "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
}

DELETE/openapi/v1/convert/:id

Eliminar una tarea de conversión

Este endpoint elimina permanentemente una tarea de conversión, incluyendo todos los modelos y datos asociados. Esta acción es irreversible.

Parámetros de ruta

Name
id
Type
path
Description
El ID de la tarea de conversión que se desea eliminar.

Estado de la tarea

Una tarea que aún está en PENDING se elimina y se reembolsan los créditos consumidos en el momento de su creación.

Una tarea que ya está IN_PROGRESS no se puede eliminar: la solicitud se rechaza con 409 Conflict y la tarea sigue ejecutándose. Los créditos de una tarea que el worker ya ha comenzado a procesar no son reembolsables, por lo que eliminarla a mitad de ejecución te haría perder tanto los créditos como el resultado. Espera a que alcance el estado SUCCEEDED, FAILED o CANCELED, y luego elimínala.

Una tarea en un estado terminal (SUCCEEDED, FAILED o CANCELED) se elimina sin reembolso.

Devuelve

Devuelve 200 OK en caso de éxito, o 409 Conflict cuando la tarea está IN_PROGRESS.

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 is left 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."
}

GET/openapi/v1/convert

Listar tareas de conversión

Este endpoint le permite recuperar una lista de tareas de conversión.

Parámetros

Name
page_num
Type
integer
predeterminado 1
Description
Número de página para la paginación.

Name
page_size
Type
integer
predeterminado 10
Description
Límite de tamaño de página. El máximo permitido es 100 elementos.

Name
sort_by
Type
string
Description
Campo por el cual ordenar. Valores disponibles:
- +created_at: Ordenar por fecha de creación en orden ascendente.
- -created_at: Ordenar por fecha de creación en orden descendente.

Devuelve

Devuelve una lista paginada de Los Objetos de Tarea de Conversión.

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
  }
]

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

Transmitir una Tarea de Conversión

Este endpoint transmite actualizaciones en tiempo real de una tarea de conversión mediante Server-Sent Events (SSE).

Parámetros

Name
id
Type
path
Description
Identificador único de la tarea de conversión a transmitir.

Devuelve

Devuelve un flujo de Los Objetos de Tarea de Conversión como Server-Sent Events.

Para tareas PENDING o IN_PROGRESS, el flujo de respuesta solo incluirá los campos necesarios progress y status.

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
}

El objeto Convert Task

El objeto Convert Task representa un trabajo de conversión de formato.

Propiedades

id · string

Identificador único de la tarea.

type · string

Tipo de la tarea. El valor es convert.

model_urls · object

URLs descargables para los archivos del modelo convertido. Solo los formatos especificados en target_formats tendrán URLs. Las demás propiedades de formato estarán vacías.

progress · integer

Progreso de la tarea (0-100).

status · string

Estado de la tarea. Valores posibles: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

preceding_tasks · integer

El número de tareas precedentes. Solo tiene sentido cuando el estado es PENDING.

created_at · timestamp

Marca de tiempo de cuándo se creó la tarea, en milisegundos.

started_at · timestamp

Marca de tiempo de cuándo se inició la tarea, en milisegundos. 0 si no se ha iniciado.

finished_at · timestamp

Marca de tiempo de cuándo finalizó la tarea, en milisegundos. 0 si no ha finalizado.

task_error · object

Objeto de error si la tarea falló. Consulta Errores para más detalles.

consumed_credits · integer

El número de créditos consumidos por esta tarea (1 crédito por tarea de conversión). Devuelve 0 para las tareas FAILED.