API de Redimensionar

Redimensione um modelo 3D para um tamanho real, em metros. Defina sua altura ou o comprimento do seu lado mais longo, ou deixe que o Meshy estime 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 geralmente leva, 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 você envie model_url. O ID da tarefa do Meshy cujo modelo você deseja redimensionar. A tarefa deve ter o status SUCCEEDED. O Meshy retorna o modelo redimensionado como um arquivo GLB.

Name
model_url
Type
string
Obrigatório
Description
Obrigatório, a menos que você envie input_task_id. O modelo a ser redimensionado, como uma URL pública ou um data URI. Se você enviar ambos, o Meshy usa input_task_id.
O modelo deve ser um arquivo GLB, glTF, OBJ, FBX ou STL de no máximo 400 MB a partir de uma URL http ou https, ou 100 MB como data URI. Para um data URI, use o MIME type application/octet-stream.
Um arquivo acima de 100 MB também deve seguir estas regras:
- Um arquivo GLB, glTF, FBX ou OBJ pode ter no máximo 10.000.000 faces. O Meshy conta as faces como triângulos, então um quad conta como 2, e uma malha desenhada mais de uma vez conta uma vez por cópia.
- Um arquivo FBX deve ser FBX binário 7.1 ou mais recente.
- Um arquivo GLB ou glTF não pode usar compressão Draco.
Um arquivo GLB, OBJ, FBX ou STL mantém seu formato no resultado. Um arquivo .gltf ou um data URI retorna como GLB.

Envie exatamente um dos parâmetros resize_height, resize_longest_side ou auto_size. Não enviar nenhum deles, ou enviar mais de um, retorna 400.

Name
resize_height
Type
number
Description
A nova altura do modelo em metros, maior que 0. Um valor negativo retorna 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 retorna 400. O Meshy mantém a proporção do modelo.

Name
auto_size
Type
boolean
Description
Se deve estimar a altura real do objeto no mundo real com visão de IA e redimensionar o modelo para essa altura. A menos que você defina origin_at, o Meshy coloca a origem na parte inferior.

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

Retornos

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

Modos de falha

Name
400 - Bad Request
Description
A requisição não pode ser executada. A mensagem de erro indica qual problema foi encontrado. Por exemplo:
- Parâmetro ausente: Nem model_url nem input_task_id foram enviados.
- Modo de redimensionamento ausente: Nenhum dos parâmetros resize_height, resize_longest_side e auto_size foi enviado.
- Parâmetros mutuamente exclusivos: A requisição tem mais de um dos parâmetros 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 bem-sucedida.
- Formato de modelo inválido: O arquivo em model_url tem uma extensão não suportada.
- URL inacessível: O Meshy não consegue baixar o arquivo em model_url.
- Arquivo de modelo muito grande: O arquivo em model_url tem mais de 400 MB a partir de uma URL http ou https, ou mais de 100 MB como data URI.
- Faces em excesso: O arquivo em model_url tem mais de 100 MB e mais de 10.000.000 faces. Reduza a contagem de faces e envie o arquivo novamente.
- FBX ASCII acima de 100 MB: O arquivo em model_url é um FBX ASCII com mais de 100 MB. Envie-o como FBX binário ou GLB.
- Arquivo de modelo ilegível: O arquivo em model_url tem mais de 100 MB, e o Meshy não consegue ler 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 muito complexo: O arquivo em model_url tem mais de 100 MB, e seu cabeçalho tem malhas, nós ou registros demais para verificar. Reduza o número de objetos no arquivo e envie-o novamente.
Corrija a requisição e envie-a novamente. Consulte Erros.
Name
401 - Unauthorized
Description
A chave de API está ausente 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 seu saldo de créditos e tente novamente.
- Plano gratuito: Criar uma tarefa requer um plano pago. Faça upgrade do seu plano nas configurações de assinatura 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 de suas tarefas. Verifique o ID da tarefa e envie a requisição novamente.
Name
429 - Too Many Requests
Description
Você excedeu seu limite de taxa. Aguarde e tente novamente. Consulte Limites de taxa.

GET/openapi/v1/resize/:id

Get a Resize task

Retorna uma tarefa de Redimensionar pelo 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 retornado na resposta de criação.

Retornos

O objeto de tarefa de Redimensionar.

DELETE/openapi/v1/resize/:id

Excluir uma tarefa de Redimensionar

Exclui permanentemente uma tarefa de Redimensionar, incluindo seus modelos e dados. Você não pode desfazer uma exclusã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 de caminho

Name
id
Type
path
Description
O ID da tarefa a ser excluída.

Status da tarefa

Excluir uma tarefa PENDING reembolsa os créditos usados na sua criação.

Uma tarefa IN_PROGRESS não pode ser excluída. A requisição retorna 409 Conflict, e a tarefa continua em execução. A Meshy não reembolsa uma tarefa que já foi iniciada, então excluí-la custaria tanto os créditos quanto o resultado. Aguarde até que ela chegue a SUCCEEDED, FAILED ou CANCELED, e então a exclua.

Excluir uma tarefa em um status final (SUCCEEDED, FAILED ou CANCELED) não reembolsa seus créditos.

Retornos

200 OK quando a tarefa é excluída, ou 409 Conflict quando a tarefa está IN_PROGRESS.

GET/openapi/v1/resize

Listar tarefas de Redimensionar

Retorna uma lista das suas tarefas 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
padrão 1
Description
O número da página a ser retornada.

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

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

Retornos

Uma lista paginada de objetos de tarefa de Redimensionar.

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 retornado na 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 retornado pelo endpoint Get. Enquanto a tarefa está PENDING ou IN_PROGRESS, 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. Ele contém o status, o progress e o arquivo de 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 download para o arquivo de modelo redimensionado. Para input_task_id, o arquivo é sempre GLB. Para model_url, um arquivo GLB, OBJ, FBX ou STL mantém seu formato, e um arquivo .gltf ou um Data URI retorna como GLB.
Name
progress
Type
integer
Description
Quanto da tarefa foi concluído, em porcentagem. É 0 até a tarefa começar e 100 quando é bem-sucedida.
Name
status
Type
string
Description
O status da tarefa, um de 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ó é significativo enquanto a tarefa está PENDING.
Name
created_at
Type
timestamp
Description
Horário em que a tarefa foi criada, em milissegundos Unix.
Name
started_at
Type
timestamp
Description
Horário em que a tarefa começou, em milissegundos Unix. É 0 até a tarefa começar.
Name
finished_at
Type
timestamp
Description
Horário em que a tarefa terminou, em milissegundos Unix. É 0 até a tarefa terminar.
Name
task_error
Type
object
Description
Os detalhes do erro quando a tarefa falha. Veja Erros.
Name
consumed_credits
Type
integer
Description
O número de créditos que a tarefa usou, que é 1 para uma tarefa Resize. É 0 para uma tarefa FAILED.