API de Redimensionar

La API de Redimensionar te permite redimensionar modelos 3D existentes a dimensiones del mundo real. Puedes especificar una altura exacta, una restricción de lado más largo, o dejar que la IA estime automáticamente el tamaño apropiado.

POST/openapi/v1/resize

Crear una tarea de redimensionamiento

Este endpoint crea una nueva tarea de redimensionamiento.

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

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 redimensionar. La tarea debe tener un estado SUCCEEDED. El formato de salida será GLB.

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 los Data URI, usa el MIME type: application/octet-stream. El formato de salida conservará el formato original del modelo de entrada.
Tamaño máximo de archivo: 100 MB.

Se requiere exactamente un mode de redimensionamiento: resize_height, resize_longest_side o auto_size. Estos tres parámetros son mutuamente excluyentes.

Name
resize_height
Type
number
Description
Redimensiona el modelo a una altura específica medida en metros.

Name
resize_longest_side
Type
number
Description
Redimensiona el modelo de modo que su lado más largo coincida con este valor, medido en metros. Se conserva la relación de aspecto.

Name
auto_size
Type
boolean
Description
Cuando se establece en true, el servicio utiliza visión por IA para estimar automáticamente la altura real del objeto en el mundo real y redimensionar el modelo en consecuencia. El origen será bottom de forma predeterminada, a menos que se establezca explícitamente origin_at.

Name
origin_at
Type
string
predeterminado bottom
Description
Posición del origen después del redimensionamiento.
Valores disponibles: bottom, center.

Valores devueltos

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

Modos de fallo

400 - Bad Request

La solicitud era inaceptable. Causas comunes:

Parámetro faltante: Se debe proporcionar model_url o input_task_id.
Falta el mode de redimensionamiento: Se debe especificar al menos uno de resize_height, resize_longest_side o auto_size.
Parámetros mutuamente excluyentes: resize_height, resize_longest_side y auto_size no se pueden combinar.
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 admitida.
URL inaccesible: No se pudo descargar model_url.
Archivo de modelo demasiado grande: El archivo de model_url supera los 100 MB.

401 - Unauthorized

Error de autenticación. Por favor, verifica 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/resize

# Simple: resize to a specific height
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "resize_height": 1.8
  }'

# Advanced: resize longest side with custom origin
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "model_url": "https://example.com/model.glb",
    "resize_longest_side": 2.0,
    "origin_at": "center"
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/resize/:id

Recuperar una tarea de Redimensionar

Este endpoint recupera una tarea de redimensionamiento mediante su ID.

Parámetros

Name
id
Type
path
Description
El ID de la tarea de redimensionamiento a recuperar.

Devuelve

El objeto de la tarea de Redimensionar.

Request

GET

/openapi/v1/resize/:id

curl https://api.meshy.ai/openapi/v1/resize/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "resize",
  "model_urls": {
      "glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

DELETE/openapi/v1/resize/:id

Eliminar una tarea de Redimensionar

Este endpoint elimina permanentemente una tarea de redimensionamiento, 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 redimensionamiento a eliminar.

Estado de la tarea

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

Una tarea que ya está IN_PROGRESS no se puede eliminar: la solicitud es rechazada con 409 Conflict y la tarea sigue ejecutándose. Los créditos de una tarea que el worker ya ha comenzado no son reembolsables, por lo que eliminarla a mitad de la 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/resize/:id

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/resize/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/resize

Listar tareas de redimensionado

Este endpoint le permite obtener una lista de tareas de redimensionado.

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 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 redimensionado.

Request

GET

/openapi/v1/resize

curl https://api.meshy.ai/openapi/v1/resize?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "resize",
    "model_urls": {
      "glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
    "consumed_credits": 1
  }
]

GET/openapi/v1/resize/:id/stream

Transmitir una tarea de redimensionamiento

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

Parámetros

Name
id
Type
path
Description
Identificador único de la tarea de redimensionamiento que se desea transmitir.

Devuelve

Devuelve un flujo de objetos de tarea de redimensionamiento como Server-Sent Events.

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

Request

GET

/openapi/v1/resize/:id/stream

curl -N https://api.meshy.ai/openapi/v1/resize/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": "resize",
  "model_urls": {
    "glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

The Resize Task Object

El objeto Resize Task representa una tarea de redimensionamiento.

Properties

id · string

Identificador único de la tarea.

type · string

Tipo de la tarea. El valor es resize.

model_urls · object

URL descargable para el archivo del modelo redimensionado. Cuando se usa input_task_id, la salida siempre es GLB. Cuando se usa model_url, la salida conserva el formato original.

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 recuento 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

La cantidad de créditos consumidos por esta tarea (1 crédito por tarea de redimensionamiento). Devuelve 0 para tareas FAILED.