API Redimensionar

Redimensionar um modelo 3D para um tamanho real, em metros. Defina a sua altura ou o comprimento do seu lado mais longo, ou deixe o Meshy estimar a altura real do objeto.

POST/openapi/v1/resize

Criar uma tarefa de Redimensionar

Cria uma tarefa de Redimensionar. A tarefa é executada em segundo plano. Para saber quanto tempo uma tarefa normalmente demora, consulte Tempos de processamento.

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
Obrigatório
Description
Obrigatório, a menos que envie model_url. O ID de uma tarefa que produziu um modelo 3D, por exemplo, uma tarefa de Texto para 3D, Imagem para 3D, Remesh ou Retexturizar. A tarefa tem de vir da API e ter o estado SUCCEEDED. A Meshy devolve o modelo redimensionado como um ficheiro GLB.

Name
model_url
Type
string
Obrigatório
Description
Obrigatório, a menos que envie input_task_id. O modelo a redimensionar, como um URL público ou um Data URI. Se enviar ambos, a Meshy utiliza input_task_id.
O modelo tem de ser um ficheiro GLB, glTF, OBJ, FBX ou STL de, no máximo, 400 MB a partir de um URL http ou https, ou 100 MB como Data URI. Para um Data URI, utilize o MIME type application/octet-stream.
Um ficheiro com mais de 100 MB também tem de respeitar as seguintes regras:
- Um ficheiro GLB, glTF, FBX ou OBJ pode ter, no máximo, 10 000 000 de faces. A Meshy conta as faces como triângulos, pelo que um quadrilátero conta como 2, e uma malha desenhada mais do que uma vez conta uma vez por cópia.
- Um ficheiro FBX tem de ser FBX binário 7.1 ou mais recente.
- Um ficheiro GLB ou glTF não pode utilizar compressão Draco.
Um ficheiro GLB, OBJ, FBX ou STL mantém o seu formato no resultado. Um ficheiro .gltf ou um Data URI é devolvido como GLB.

Envie exatamente um de resize_height, resize_longest_side ou auto_size. Não enviar nenhum deles, ou enviar mais do que um, devolve 400.

Name
resize_height
Type
number
Description
A nova altura do modelo em metros, maior que 0. Um valor negativo devolve 400.

Name
resize_longest_side
Type
number
Description
O novo comprimento do lado mais longo do modelo em metros, maior que 0. Um valor negativo devolve 400. A Meshy mantém a proporção do modelo.

Name
auto_size
Type
boolean
Description
Se deve estimar a altura real do objeto com visão por IA e redimensionar o modelo em conformidade. A menos que defina origin_at, a Meshy coloca a origem na base.

Name
origin_at
Type
string
predefinição bottom
Description
Onde colocar a origem do modelo após o redimensionamento, bottom ou center.

Retorno

O campo result da resposta contém o ID da nova tarefa de Redimensionar.

Modos de falha

Name
400 - Bad Request
Description
O pedido não pode ser executado. A mensagem de erro indica qual o problema encontrado. Por exemplo:
- Parâmetro em falta: Nem model_url nem input_task_id foram enviados.
- Modo de redimensionamento em falta: Nenhum de resize_height, resize_longest_side e auto_size foi enviado.
- Parâmetros mutuamente exclusivos: O pedido tem mais do que um de resize_height, resize_longest_side e auto_size. Envie apenas um.
- Tamanho negativo: resize_height ou resize_longest_side é negativo.
- Tarefa de entrada inválida: input_task_id não é uma tarefa da API bem-sucedida com um ficheiro de modelo.
- Formato de modelo inválido: O ficheiro model_url tem uma extensão não suportada.
- URL inacessível: A Meshy não consegue transferir o ficheiro model_url.
- Ficheiro de modelo demasiado grande: O ficheiro model_url tem mais de 400 MB a partir de um URL http ou https, ou mais de 100 MB como Data URI.
- Demasiadas faces: O ficheiro model_url tem mais de 100 MB e mais de 10 000 000 de faces. Reduza o número de faces e envie o ficheiro novamente.
- FBX ASCII com mais de 100 MB: O ficheiro model_url é um FBX ASCII com mais de 100 MB. Envie-o como FBX binário ou GLB.
- Ficheiro de modelo ilegível: O ficheiro model_url tem mais de 100 MB e a Meshy não consegue ler o seu cabeçalho. Por exemplo, é um GLB ou glTF comprimido com Draco, ou um FBX binário anterior à versão 7.1.
- Cabeçalho do modelo demasiado complexo: O ficheiro model_url tem mais de 100 MB e o seu cabeçalho tem demasiadas malhas, nós ou registos para verificar. Reduza o número de objetos no ficheiro e envie-o novamente.
Corrija o pedido e envie-o novamente. Consulte Erros.
Name
401 - Unauthorized
Description
A chave de API está em falta ou é inválida. Verifique o cabeçalho Authorization.
Name
402 - Payment Required
Description
Por exemplo:
- Créditos insuficientes: A conta não tem créditos suficientes para esta tarefa, ou a conta atingiu um limite de créditos. Verifique o seu saldo de créditos e tente novamente.
- Plano gratuito: Criar uma tarefa requer um plano pago. Atualize o seu plano nas definições de subscrição e tente novamente.
Name
403 - Forbidden
Description
input_task_id é um modelo de baixo-relevo, que este endpoint não consegue redimensionar. A mensagem é This model type does not support this operation. Envie um modelo diferente.
Name
404 - Not Found
Description
input_task_id não corresponde a nenhuma das suas tarefas. Verifique o ID da tarefa e envie o pedido novamente.
Name
429 - Too Many Requests
Description
Excedeu o seu limite de taxa. Aguarde e tente novamente. Consulte Limites de taxa.

GET/openapi/v1/resize/:id

Obter uma tarefa de Redimensionar

Devolve uma tarefa de Redimensionar através do seu 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
O ID da tarefa proveniente da resposta de criação.

Devolve

O objeto de tarefa de Redimensionar.

DELETE/openapi/v1/resize/:id

Eliminar uma tarefa de Redimensionar

Elimina permanentemente uma tarefa de Redimensionar, incluindo os seus modelos e dados. Não é possível anular uma eliminação.

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 do caminho

Name
id
Type
path
Description
O ID da tarefa a eliminar.

Estado da tarefa

Eliminar uma tarefa PENDING reembolsa os créditos utilizados na sua criação.

Uma tarefa IN_PROGRESS não pode ser eliminada. O pedido devolve 409 Conflict, e a tarefa continua em execução. A Meshy não reembolsa uma tarefa que já foi iniciada, pelo que eliminá-la custaria tanto os créditos como o resultado. Aguarde até que atinja o estado SUCCEEDED, FAILED ou CANCELED, e só depois a elimine.

Eliminar uma tarefa num estado final (SUCCEEDED, FAILED ou CANCELED) não reembolsa os seus créditos.

Devolve

200 OK quando a tarefa é eliminada, ou 409 Conflict quando a tarefa está IN_PROGRESS.

GET/openapi/v1/resize

Listar tarefas de Resize

Devolve uma lista das suas tarefas de Resize.

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
predefinição 1
Description
O número da página a devolver, até 255. Um valor superior devolve 400.

Name
page_size
Type
integer
predefinição 10
Description
O número de tarefas por página, até 100.

Name
sort_by
Type
string
Description
A ordem de ordenação.
Valores disponíveis:
- +created_at: mais antigas primeiro
- -created_at: mais recentes primeiro

Devolve

Uma lista paginada de objetos de tarefa Resize.

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

Transmitir uma tarefa de Redimensionar

Transmite as atualizações de uma tarefa de Redimensionar como Server-Sent Events (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
O ID da tarefa proveniente da resposta de criação.

Retornos

Um stream de objetos de tarefa de Redimensionar como Server-Sent Events.

Cada evento contém o objeto de tarefa completo, no mesmo formato devolvido pelo endpoint Get. Enquanto a tarefa estiver PENDING ou IN_PROGRESS, os seus campos de resultado ainda não têm valores.

O objeto de tarefa Resize

Um objeto de tarefa Resize descreve um redimensionamento de um modelo 3D. Contém o estado, o progresso e o ficheiro do modelo quando a tarefa é bem-sucedida.

Propriedades

Name
id
Type
string
Description
O ID da tarefa. Trate-o como uma string opaca e não dependa do seu formato.
Name
type
Type
string
Description
O tipo da tarefa, sempre resize.
Name
model_urls
Type
object
Description
URL de transferência do ficheiro do modelo redimensionado. Para input_task_id, o ficheiro é sempre GLB. Para model_url, um ficheiro GLB, OBJ, FBX ou STL mantém o seu formato, e um ficheiro .gltf ou um Data URI são devolvidos como GLB.
Name
progress
Type
integer
Description
A percentagem da tarefa já concluída. É 0 até a tarefa começar e 100 quando é bem-sucedida.
Name
status
Type
string
Description
O estado da tarefa, um dos seguintes: PENDING, IN_PROGRESS, SUCCEEDED, FAILED ou CANCELED.
Name
preceding_tasks
Type
integer
Description
O número de tarefas à frente desta na fila. O valor só é relevante enquanto a tarefa está PENDING.
Name
created_at
Type
timestamp
Description
Hora em que a tarefa foi criada, em milissegundos Unix.
Name
started_at
Type
timestamp
Description
Hora em que a tarefa começou, em milissegundos Unix. É 0 até a tarefa começar.
Name
finished_at
Type
timestamp
Description
Hora em que a tarefa terminou, em milissegundos Unix. É 0 até a tarefa terminar.
Name
expires_at
Type
timestamp
Description
Hora em que os URLs de transferência da tarefa expiram, em milissegundos Unix. É 0 até a tarefa terminar.
Name
texture_urls
Type
array
Description
URLs de transferência dos mapas de textura do modelo, quando a tarefa é bem-sucedida: um array de objetos, um por cada conjunto de texturas. Cada objeto tem um URL base_color, e pode também ter URLs metallic, roughness, normal, emission e metallic_roughness. É null até a tarefa ser bem-sucedida, e um array vazio quando o modelo não tem mapas de textura.
Name
task_error
Type
object
Description
Os detalhes do erro quando a tarefa falha. Consulte Erros.
Name
consumed_credits
Type
integer
Description
O número de créditos que a tarefa utilizou, que é 1 para uma tarefa Resize. É 0 para uma tarefa FAILED.