API de Redimensionar

Redimensiona un modelo 3D a un tamaño real, en metros. Define su altura o la longitud de su lado más largo, o deja que Meshy estime la altura real del objeto.

POST/openapi/v1/resize

Crear una tarea de Resize

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

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

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 deseas redimensionar. La tarea debe tener el estado SUCCEEDED. Meshy devuelve el modelo redimensionado como un archivo GLB.

Name
model_url
Type
string
Requerido
Description
Obligatorio a menos que envíes input_task_id. El modelo a redimensionar, 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 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 seguir estas reglas:
- Un archivo GLB, glTF, FBX u OBJ puede tener como máximo 10,000,000 de caras. Meshy cuenta las caras como triángulos, así 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.
Un archivo GLB, OBJ, FBX o STL conserva su formato en el resultado. Un archivo .gltf o un data URI se devuelve como GLB.

Envía exactamente uno de resize_height, resize_longest_side o auto_size. Si no envías ninguno, o envías más de uno, se devuelve 400.

Name
resize_height
Type
number
Description
La nueva altura del modelo en metros, mayor que 0. Un valor negativo devuelve 400.

Name
resize_longest_side
Type
number
Description
La nueva longitud del lado más largo del modelo en metros, mayor que 0. Un valor negativo devuelve 400. Meshy mantiene la relación de aspecto del modelo.

Name
auto_size
Type
boolean
Description
Indica si se debe estimar la altura real del objeto en el mundo real con visión por IA y redimensionar el modelo a ese valor. A menos que establezcas origin_at, Meshy coloca el origen en la parte inferior.

Name
origin_at
Type
string
predeterminado bottom
Description
Dónde colocar el origen del modelo después de redimensionar, bottom o center.

Devuelve

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

Modos de fallo

Name
400 - Bad Request
Description
La solicitud no se puede ejecutar. El mensaje de error indica qué problema encontró. Por ejemplo:
- Parámetro faltante: No se envió ni model_url ni input_task_id.
- Modo de redimensionado faltante: No se envió ninguno de resize_height, resize_longest_side ni auto_size.
- Parámetros mutuamente excluyentes: La solicitud tiene más de uno de resize_height, resize_longest_side y auto_size. Envía solo uno.
- Tamaño negativo: resize_height o resize_longest_side es negativo.
- Tarea de entrada inválida: input_task_id no es una tarea exitosa.
- Formato de modelo inválido: El archivo de model_url tiene una extensión no compatible.
- 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 de 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 de 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 suficientes créditos 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. Actualiza 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 redimensionar. 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. Revisa 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/resize/:id

Obtener una tarea de Redimensionar

Devuelve una tarea de Redimensionar por su ID.

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
}

Parámetros

Name
id
Type
path
Description
El ID de la tarea proveniente de la respuesta de creación.

Devuelve

El objeto de tarea de Redimensionar.

DELETE/openapi/v1/resize/:id

Eliminar una tarea de Redimensionar

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

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 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 a eliminar.

Estado de la tarea

Eliminar una tarea PENDING reembolsa los créditos que usó 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/resize

Listar tareas de Redimensionar

Devuelve una lista de tus tareas de Redimensionar.

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

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

Devuelve

Una lista paginada de objetos de tarea de Redimensionar.

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

Transmitir una tarea de Redimensionar en streaming

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

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
}

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 Redimensionar 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 estado PENDING o IN_PROGRESS, sus campos de resultado aún no tienen valores.

El objeto de tarea Resize

Un objeto de tarea Resize describe un redimensionado de un modelo 3D. Contiene el estado, el progress y el archivo 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 resize.
Name
model_urls
Type
object
Description
URL de descarga del archivo del modelo redimensionado. Para input_task_id, el archivo siempre es GLB. Para model_url, un archivo GLB, OBJ, FBX o STL conserva su formato, y un archivo .gltf o un Data URI se devuelve como GLB.
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 con éxito.
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 tiene sentido 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 Resize. Es 0 para una tarea FAILED.