API de Analisar imprimibilidade

Analise um modelo 3D quanto à imprimibilidade — estanqueidade, volume, furos, arestas non-manifold e faces degeneradas. Opcionalmente, também verifique a espessura de parede no tamanho em que você planeja imprimir.

POST/openapi/v1/print/analyze

Create an Analyze Printability Task

Este endpoint cria uma nova tarefa de análise de imprimibilidade. A tarefa avalia um modelo 3D e reporta suas métricas de imprimibilidade.

A tarefa é executada em segundo plano. Para saber quanto tempo normalmente leva, consulte Tempos de Processamento.

Se a tarefa de entrada já tiver imprimibilidade em cache, a tarefa retornada estará imediatamente pronta e o primeiro GET nela retornará o resultado da análise sem passar pelo worker.

Para também verificar a espessura de parede no tamanho em que você planeja imprimir, envie printer_type, um tamanho de impressão, ou ambos. O resultado é retornado em printability.thin_walls. Verificar a espessura de parede demora mais, então a tarefa normalmente não fica pronta de imediato, mesmo que o modelo já tenha sido analisado antes.

Parâmetros

Apenas um dos parâmetros input_task_id ou model_url é obrigatório. Se ambos forem fornecidos, input_task_id tem prioridade.

Name
input_task_id
Type
string
Obrigatório
Description
O ID de uma tarefa bem-sucedida que você possui. Tipos de tarefa suportados: Imagem para 3D, Multi-imagem para 3D, Texto para 3D, Remesh e Retexturizar. A tarefa deve usar Meshy 6 ou mais recente (incluindo Meshy 7) e deve ter o status SUCCEEDED. Tarefas de Reparar imprimibilidade também são aceitas.

Name
model_url
Type
string
Obrigatório
Description
URL de um modelo 3D para analisar. Formatos suportados: .glb, .gltf, .obj, .fbx, .stl. Tamanho máximo de arquivo: 100 MB. Deve usar http, https, ou uma URL data: (URLs de dados ignoram as verificações de extensão).
URLs de download da Meshy (assets.meshy.ai/…?Expires=…&Signature=…) são assinadas e param de funcionar no expires_at da tarefa; buscar a tarefa novamente não as renova. Para um modelo gerado com a Meshy, envie input_task_id em vez disso. Isso funciona enquanto a tarefa de origem for retida (veja Retenção de Recursos). Para reutilizar um modelo depois disso, baixe-o antes do expires_at e envie sua própria cópia.

Envie no máximo um dos dois campos de tamanho de impressão. Se você enviar printer_type sem um tamanho, o tamanho padrão é:

.glb e qualquer input_task_id: 150 mm de altura.
.stl: o maior lado do próprio arquivo, interpretado em milímetros. Para um STL em outras unidades, envie intended_print_longest_side_mm.
.obj, .fbx, .gltf: 150 mm no lado mais longo.

Name
printer_type
Type
string
Description
A impressora que você planeja usar. Ela define a espessura mínima de parede para a verificação de espessura de parede. O padrão é fdm quando você envia um tamanho de impressão sem especificá-lo.
Valores disponíveis:
- fdm: filamento, 1,0 mm de parede mínima.
- sla: resina, 0,8 mm de parede mínima.
- full_color: colorido, 2,0 mm de parede mínima.
Name
intended_print_height_mm
Type
number
Description
Altura da impressão, em milímetros. Intervalo: [1, 1000]. Arredondado para o milímetro mais próximo. Somente para entrada GLB.
Name
intended_print_longest_side_mm
Type
number
Description
Comprimento do lado mais longo da impressão, em milímetros. Intervalo: [1, 1000]. Arredondado para o milímetro mais próximo. Funciona com todos os formatos de entrada.

Retornos

A propriedade result da resposta contém o id da tarefa de análise de imprimibilidade recém-criada.

Modos de Falha

Name
400 - Bad Request
Description
A solicitação foi inaceitável. Causas comuns:
- Parâmetro ausente: nem input_task_id nem model_url foram fornecidos.
- UUID inválido: input_task_id não é um UUID válido.
- URL de modelo inválida: model_url está malformada, usa um esquema não suportado, ou tem uma extensão de arquivo não suportada.
- Arquivo de modelo muito grande: o corpo de model_url excedeu 100 MB.
- Não foi possível baixar o arquivo do modelo: model_url retornou um erro, geralmente porque uma URL de download assinada da Meshy expirou. Buscar a tarefa novamente retorna a mesma URL com o mesmo prazo de expiração, então envie sua própria cópia do arquivo, ou use input_task_id enquanto a tarefa de origem ainda estiver retida.
- Tarefa não bem-sucedida: a tarefa referenciada ainda está pendente, em andamento, ou falhou.
- Tamanho de impressão inválido: intended_print_height_mm ou intended_print_longest_side_mm está fora de [1, 1000], ou ambos foram enviados.
- Tipo de impressora desconhecido: printer_type não é fdm, sla, ou full_color.
- Altura em um modelo não GLB: intended_print_height_mm foi enviado com um model_url que não é .glb. Use intended_print_longest_side_mm em vez disso.
- Não é possível dimensionar este modelo pela altura: na altura solicitada (ou o padrão de 150 mm), o lado mais longo do modelo ficaria fora de [1, 1000] mm, o modelo é plano, ou seu tamanho não pode ser determinado. Use intended_print_longest_side_mm em vez disso. Para um model_url .glb e algumas tarefas input_task_id, isso só é descoberto depois que a tarefa é iniciada, e a tarefa termina com FAILED em vez disso.
- Tamanho de STL inutilizável: printer_type foi enviado sem um tamanho, e o próprio lado mais longo do .stl não pode ser lido ou está fora de [1, 1000] mm. Envie intended_print_longest_side_mm.
Name
401 - Unauthorized
Description
A autenticação falhou. Por favor, verifique sua chave de API.
Name
403 - Forbidden
Description
A tarefa existe, mas pertence a um usuário diferente.
Name
404 - Not Found
Description
Causas comuns:
- A tarefa não existe ou foi excluída.
- A tarefa usa um modelo mais antigo que o Meshy 6, ou seu mode não produz um asset 3D.
- O arquivo de modelo subjacente não está mais disponível no armazenamento.
Name
429 - Too Many Requests
Description
Você excedeu sua cota de tarefas pendentes ou limite de taxa.

Request

POST

/openapi/v1/print/analyze

# Analyze an existing task
curl https://api.meshy.ai/openapi/v1/print/analyze \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

# Or analyze a model URL directly
curl https://api.meshy.ai/openapi/v1/print/analyze \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "model_url": "https://example.com/model.glb"
  }'

# Also check wall thickness for a 100 mm tall SLA print
curl https://api.meshy.ai/openapi/v1/print/analyze \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "printer_type": "sla",
    "intended_print_height_mm": 100
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/print/analyze/:id

Recuperar uma Tarefa de Analisar Imprimibilidade

Este endpoint recupera uma tarefa de analisar imprimibilidade pelo seu ID.

Parâmetros

Name
id
Type
path
Description
O ID da tarefa de analisar imprimibilidade a ser recuperada.

Retornos

O Objeto de Tarefa de Analisar Imprimibilidade. O campo printability é null até que a tarefa atinja SUCCEEDED. Quando a espessura de parede foi verificada, printability também inclui intended_print e thin_walls.

Request

GET

/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl https://api.meshy.ai/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

Response (wall thickness checked)

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000012000,
  "expires_at": 1715725412000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "error",
    "issue_count": 2,
    "error_count": 1,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "intended_print": {
      "printer_type": "sla",
      "height_mm": 100,
      "longest_side_mm": 118,
      "wall_thickness_mm": 0.8,
      "dimensions_mm": [118, 72.41, 99.87]
    },
    "thin_walls": {
      "thin_area_ratio": 0.083,
      "has_thin_walls": true,
      "status": "error"
    },
    "evaluated_at": 1700000012000
  },
  "consumed_credits": 0
}

DELETE/openapi/v1/print/analyze/:id

Excluir uma tarefa de Analisar imprimibilidade

Este endpoint exclui permanentemente uma tarefa de análise de imprimibilidade e seu resultado em cache. Essa ação é irreversível.

Parâmetros de Caminho

Name
id
Type
path
Description
O ID da tarefa de análise de imprimibilidade a ser excluída.

Status da Tarefa

Uma tarefa que ainda está PENDING é excluída e os créditos consumidos no momento da criação são reembolsados.

Uma tarefa que já está IN_PROGRESS não pode ser excluída: a solicitação é rejeitada com 409 Conflict e a tarefa continua em execução. Os créditos de uma tarefa que o worker já iniciou não são reembolsáveis, portanto excluí-la no meio da execução custaria tanto os créditos quanto o resultado. Aguarde até que ela atinja SUCCEEDED, FAILED ou CANCELED, e então a exclua.

Uma tarefa em um estado terminal (SUCCEEDED, FAILED ou CANCELED) é excluída sem reembolso.

Retornos

Retorna 200 OK em caso de sucesso, ou 409 Conflict quando a tarefa está IN_PROGRESS.

Request

DELETE

/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/analyze/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 is left 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."
}

GET/openapi/v1/print/analyze

Listar tarefas de Analisar imprimibilidade

Este endpoint permite recuperar uma lista de tarefas de análise de imprimibilidade.

Parâmetros

Atributos opcionais

Name
page_num
Type
integer
Description
Número da página para paginação. Começa e tem como padrão 1.
Name
page_size
Type
integer
Description
Limite de itens por página. O padrão é 10 itens. O máximo permitido é 100 itens.
Name
sort_by
Type
string
Description
Campo pelo qual ordenar. Valores disponíveis:
- +created_at: Ordena pelo horário de criação em ordem crescente.
- -created_at: Ordena pelo horário de criação em ordem decrescente.

Retornos

Retorna uma lista paginada de Objetos de Tarefa de Analisar imprimibilidade.

Request

GET

/openapi/v1/print/analyze

curl https://api.meshy.ai/openapi/v1/print/analyze?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-analyze",
    "status": "SUCCEEDED",
    "progress": 100,
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "expires_at": 1715725401000,
    "task_error": null,
    "printability": {
      "_version": "v1",
      "status": "warning",
      "issue_count": 1,
      "error_count": 0,
      "warning_count": 1,
      "metrics": {
        "is_watertight": true,
        "volume": 1.316167354292668,
        "non_manifold_edges": 0,
        "degenerate_faces": 43242,
        "holes": 0
      },
      "evaluated_at": 1700000001000
    },
    "consumed_credits": 0
  }
]

GET/openapi/v1/print/analyze/:id/stream

Analisar imprimibilidade em stream

Este endpoint transmite atualizações em tempo real de uma tarefa de análise de imprimibilidade usando Server-Sent Events (SSE).

Parâmetros

Name
id
Type
path
Description
Identificador único da tarefa de análise de imprimibilidade a ser transmitida.

Retornos

Retorna um stream de Objetos de Tarefa de Análise de imprimibilidade como Server-Sent Events.

Cada quadro carrega o objeto de tarefa completo referente ao estágio — o mesmo formato retornado pelo endpoint Get — portanto, enquanto a tarefa estiver PENDING ou IN_PROGRESS, os campos de saída simplesmente ainda não estão preenchidos (null, [] ou {}) e finished_at é null. O bloco printability é enviado somente quando a tarefa atinge SUCCEEDED.

Request

GET

/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.ai/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// Every frame is the full task object; fields not yet populated are null / empty.
// The PENDING frame below is abbreviated to the fields that change.
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

The Analyze Printability Task Object

Name
id
Type
string
Description
Identificador único para a tarefa. Embora usemos um UUID k-sortable para ids de tarefa como detalhe de implementação, você não deve fazer suposições sobre o formato do id.
Name
type
Type
string
Description
Tipo da tarefa de analisar imprimibilidade. O valor é print-analyze.
Name
status
Type
string
Description
Status da tarefa. Os valores possíveis são PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progresso da tarefa. Se a tarefa ainda não foi iniciada, essa propriedade será 0. Assim que a tarefa for concluída com sucesso, ela passará a ser 100.
Name
preceding_tasks
Type
integer
Description
A contagem de tarefas precedentes.
O valor deste campo só é significativo se o status da tarefa for PENDING.
Name
created_at
Type
timestamp
Description
Carimbo de data/hora de quando a tarefa foi criada, em milissegundos.
Name
started_at
Type
timestamp
Description
Carimbo de data/hora de quando a tarefa foi iniciada, em milissegundos. Se a tarefa ainda não foi iniciada, essa propriedade será 0.
Name
finished_at
Type
timestamp
Description
Carimbo de data/hora de quando a tarefa foi finalizada, em milissegundos. Se a tarefa ainda não foi finalizada, essa propriedade será 0.
Name
expires_at
Type
timestamp
Description
Carimbo de data/hora de quando o resultado da tarefa irá expirar do sistema, em milissegundos. 0 se a tarefa ainda não foi finalizada.
Name
task_error
Type
object
Description
Informações de erro, caso a tarefa tenha falhado. Esta propriedade é null se a tarefa não falhou. Consulte Erros para mais detalhes.
- Name
  message
  Type
  string
  Description
  Mensagem de erro descrevendo o que deu errado.
Name
printability
Type
object
Description
Resultado da avaliação de imprimibilidade. null até que a tarefa alcance SUCCEEDED.
- Name
  _version
  Type
  string
  Description
  Versão do esquema do resultado de imprimibilidade. Atualmente v1.
- Name
  status
  Type
  string
  Description
  Status geral. Um dos seguintes:
  
  healthy: sem erros e sem avisos.
  
  warning: pelo menos um aviso, sem erros.
  
  error: pelo menos um erro.
  
  unknown: o modelo não pôde ser analisado.
  
  Quando a espessura de parede foi verificada, este é o pior entre as verificações acima e thin_walls.status. Do pior para o melhor: error, warning, unknown, healthy.
- Name
  issue_count
  Type
  integer
  Description
  Contagem total de problemas, igual a error_count + warning_count.
- Name
  error_count
  Type
  integer
  Description
  Número de problemas de nível de erro. Erros são gerados quando o modelo não é watertight, tem volume não positivo, ou tem arestas non-manifold. Quando a espessura de parede foi verificada, paredes muito finas (thin_walls.status é error) contam como mais um erro.
- Name
  warning_count
  Type
  integer
  Description
  Número de problemas de nível de aviso. Avisos são gerados quando o modelo contém faces degeneradas ou buracos.
- Name
  metrics
  Type
  object
  Description
  Métricas brutas de geometria retornadas pelo avaliador.
  Name
  is_watertight
  Type
  boolean
  Description
  true quando a malha não tem arestas de contorno (ou seja, é fechada).
  Name
  volume
  Type
  number
  Description
  Volume do modelo em metros cúbicos.
  Name
  non_manifold_edges
  Type
  integer
  Description
  Contagem de arestas non-manifold.
  Name
  degenerate_faces
  Type
  integer
  Description
  Contagem de faces degeneradas (faces com área zero ou inválidas).
  Name
  holes
  Type
  integer
  Description
  Contagem de buracos (laços de contorno) na malha.
- Name
  intended_print
  Type
  object
  Description
  A impressora e o tamanho que a verificação de espessura de parede usou. Presente apenas quando a espessura de parede foi verificada.
  Name
  printer_type
  Type
  string
  Description
  fdm, sla ou full_color.
  Name
  height_mm
  Type
  number
  Description
  A altura de impressão em milímetros, se a impressão foi dimensionada por altura. Caso contrário, null.
  Name
  longest_side_mm
  Type
  number
  Description
  O lado mais longo da impressão em milímetros. Quando dimensionado por altura, é calculado a partir das proporções do modelo.
  Name
  wall_thickness_mm
  Type
  number
  Description
  A espessura de parede mínima para printer_type, em milímetros. Paredes mais finas que isso são reportadas como muito finas.
  Name
  dimensions_mm
  Type
  array
  Description
  As dimensões [width, depth, height] da impressão em milímetros. A altura pode diferir de height_mm por uma fração de milímetro. null para entrada que não seja GLB, ou se o tamanho do modelo não puder ser determinado.
- Name
  thin_walls
  Type
  object
  Description
  O resultado da espessura de parede. Presente apenas quando a espessura de parede foi verificada.
  Name
  thin_area_ratio
  Type
  number
  Description
  Proporção da superfície, de 0 a 1, que é mais fina que intended_print.wall_thickness_mm. null se o modelo não pôde ser medido.
  Name
  has_thin_walls
  Type
  boolean
  Description
  true se qualquer parte da superfície for muito fina. Cantos agudos sozinhos podem definir isso, então use status para decidir se as paredes precisam ser engrossadas. null se o modelo não pôde ser medido.
  Name
  status
  Type
  string
  Description
  O veredito da espessura de parede. Um dos seguintes:
  
  healthy: 5% ou menos da superfície é muito fina.
  
  error: mais de 5% da superfície é muito fina. Para engrossar as paredes, passe o id desta tarefa para Reparar imprimibilidade como input_task_id (para um model_url .stl, .fbx ou .gltf, envie o arquivo como model_url em vez disso).
  
  unknown: o modelo não pôde ser medido. Se a própria verificação de espessura de parede falhar, a tarefa termina FAILED.
- Name
  evaluated_at
  Type
  timestamp
  Description
  Carimbo de data/hora de quando a análise foi calculada, em milissegundos desde a epoch.
Name
consumed_credits
Type
integer
Description
Sempre 0. Este endpoint é gratuito.

The Analyze Printability Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

The Analyze Printability Task Object (wall thickness checked)

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000012000,
  "expires_at": 1715725412000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "error",
    "issue_count": 2,
    "error_count": 1,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "intended_print": {
      "printer_type": "sla",
      "height_mm": 100,
      "longest_side_mm": 118,
      "wall_thickness_mm": 0.8,
      "dimensions_mm": [118, 72.41, 99.87]
    },
    "thin_walls": {
      "thin_area_ratio": 0.083,
      "has_thin_walls": true,
      "status": "error"
    },
    "evaluated_at": 1700000012000
  },
  "consumed_credits": 0
}