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 Convertir

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

Parámetros

Solo uno de input_task_id o model_url es obligatorio. 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 de SUCCEEDED.

Name
model_url
Type
string
Requerido
Description
Una URL de acceso público o Data URI que apunta a un archivo de modelo 3D. Formatos compatibles: .glb, .gltf, .obj, .fbx, .stl. Para Data URI, usa el MIME type: application/octet-stream.

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 Convertir recién creada.

Modos de fallo

400 - Bad Request

La solicitud no fue aceptable. 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 no válida: input_task_id debe hacer referencia a una tarea exitosa.
Formato de modelo no válido: model_url apunta a un archivo con una extensión no compatible.
URL inaccesible: No se pudo descargar model_url.

401 - Unauthorized

La autenticación falló. Comprueba tu clave de API.

402 - Payment Required

Créditos insuficientes para realizar esta tarea.

429 - Too Many Requests

Has superado 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 Convertir

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

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 Convertir

Este endpoint elimina permanentemente una tarea de Convertir, incluidos 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 Convertir que se va a eliminar.

Devuelve

Devuelve 200 OK en caso de éxito.

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

// Returns 200 Ok on success.

GET/openapi/v1/convert

Listar tareas de Convertir

Este endpoint te permite recuperar una lista de tareas de convertir.

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 de 50 elementos.

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

Devuelve

Devuelve una lista paginada de los objetos de tarea de Convertir.

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 Convertir

Este endpoint transmite actualizaciones en tiempo real para una tarea de Convertir mediante Server-Sent Events (SSE).

Parámetros

Name
id
Type
path
Description
Identificador único de la tarea de Convertir que se va a transmitir.

Devuelve

Devuelve un flujo de los objetos de tarea de Convertir 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 de tarea de Convertir

El objeto de tarea de Convertir 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

URL descargables para los archivos de modelo convertidos. Solo los formatos especificados en target_formats tendrán URL. Las propiedades de otros formatos serán cadenas vacías.

progress · integer

progress 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 es significativo cuando el estado es PENDING.

created_at · marca de tiempo

Marca de tiempo de cuando se creó la tarea, en milisegundos.

started_at · marca de tiempo

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

finished_at · marca de tiempo

Marca de tiempo de cuando se finalizó la tarea, en milisegundos. 0 si no ha finalizado.

task_error · object

Objeto de error si la tarea falló. Consulta Errores para obtener 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 tareas FAILED.