lowpoly será descontinuado a 30/10/2026. meshy-7 como modelo de geração 3D será descontinuado a 31/12/2026; como modelo de textura continua disponível. Mude de modelo antes destas datas para evitar erros nos pedidos. Ver todas as descontinuações

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.