lowpoly será descontinuado em 30 de out. de 2026. meshy-7 como modelo de geração 3D será descontinuado em 31 de dez. de 2026; como modelo de textura continua disponível. Troque de modelo antes dessas datas para evitar erros nas solicitações. Ver todas as descontinuações

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 de uma tarefa que produziu um modelo 3D, por exemplo, uma tarefa de Texto para 3D, Imagem para 3D, Remesh ou Retexturizar. A tarefa deve vir da API e ter o status SUCCEEDED. 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, 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 de faces. Meshy conta 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 deve 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 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. 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 de IA e redimensionar o modelo para ela. A menos que você defina origin_at, 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 solicitação não pode ser executada. A mensagem de erro informa 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 solicitaçã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 de API bem-sucedida com um arquivo de modelo.
    • Formato de modelo inválido: O arquivo model_url tem uma extensão não suportada.
    • URL inacessível: Meshy não consegue baixar o arquivo model_url.
    • Arquivo de modelo muito grande: O arquivo 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 model_url tem mais de 100 MB e mais de 10.000.000 de faces. Reduza o número de faces e envie o arquivo novamente.
    • FBX ASCII acima de 100 MB: O arquivo model_url é um FBX ASCII acima de 100 MB. Envie-o como FBX binário ou GLB.
    • Arquivo de modelo ilegível: O arquivo model_url tem mais de 100 MB, e 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 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 solicitaçã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 pode 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 a solicitaçã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 retornar, até 255. Um valor maior retorna 400.

  • 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 antigos 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 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 download para o arquivo do 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

    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 as URLs de download da tarefa expiram, em milissegundos Unix. É 0 até a tarefa terminar.

  • Name
    texture_urls
    Type
    array
    Description

    URLs de download para os mapas de textura do modelo, quando a tarefa é bem-sucedida: um array de objetos, um por conjunto de texturas. Cada objeto tem uma URL base_color, e também pode 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. 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.