API de Reparar Imprimibilidade
Reparar um modelo 3D para imprimibilidade FDM — corrigir arestas non-manifold, faces degeneradas, buracos e outros problemas de topology para que a malha esteja pronta para impressão.
Criar uma Tarefa de Reparar Imprimibilidade
Este endpoint cria uma nova tarefa de reparar imprimibilidade. A tarefa executa a reparação de topology num modelo 3D e devolve uma versão estanque e pronta para impressão.
O formato de saída corresponde ao formato de entrada. Se submeter um .stl via model_url, o model_urls.stl da resposta conterá a malha reparada e os outros campos de formato estarão vazios. O caminho input_task_id lê sempre o GLB da tarefa de origem, portanto a saída é .glb.
Parâmetros
Apenas um de input_task_id ou model_url é obrigatório. Se ambos forem fornecidos, input_task_id tem prioridade.
As texturas existentes são removidas durante a reparação devido a alterações na geometria. Para adicionar texturas novamente, use a API de Retexturizar no modelo reparado.
- Name
- input_task_id
- Type
- string
- Obrigatório
- Description
O ID de uma tarefa concluída com sucesso que você possui. Tipos de tarefa suportados: Imagem para 3D, Multi-imagem para 3D, Texto para 3D, Remesh e Retexturizar. A tarefa deve ter o estado
SUCCEEDEDe deve ter produzido um asset GLB.
- Name
- model_url
- Type
- string
- Obrigatório
- Description
URL de um modelo 3D a reparar. Formatos suportados:
.glb,.gltf,.obj,.fbx,.stl. Tamanho máximo do ficheiro: 100 MB. Deve usarhttp,httpsou um URLdata:(URLs de dados ignoram verificações de extensão).
- Name
- alpha_thumbnail
- Type
- boolean
- predefinição false
- Description
Quando definido como
true, a tarefa renderiza adicionalmente uma versão de fundo transparente (RGBA) da pré-visualização e devolve-a comoalpha_thumbnail_urlna resposta GET. O campothumbnail_urlexistente permanece inalterado.
Retornos
A propriedade result da resposta contém o id da nova tarefa de reparar imprimibilidade criada.
Modos de Falha
- Name
400 - Bad Request- Description
O pedido foi inaceitável. Causas comuns:
- Parâmetro em falta: nem
input_task_idnemmodel_urlforam fornecidos. - UUID inválido:
input_task_idnão é um UUID válido. - URL do modelo inválida:
model_urlestá malformada, usa um esquema não suportado ou tem uma extensão de ficheiro não suportada. - Ficheiro do modelo demasiado grande: o corpo de
model_urlexcedeu 100 MB. - Tarefa não concluída com sucesso: a tarefa referenciada ainda está pendente, em progresso ou falhou.
- GLB em falta: a tarefa referenciada não tem um asset GLB para reparar.
- Parâmetro em falta: nem
- Name
401 - Unauthorized- Description
A autenticação falhou. Por favor, verifique a sua chave de API.
- Name
402 - Payment Required- Description
Causas comuns:
- Plano gratuito: a criação de tarefas requer um plano pago. Faça o upgrade na página de subscrição.
- Créditos insuficientes: o limite de créditos do espaço de trabalho foi atingido.
- Name
404 - Not Found- Description
A tarefa referenciada não existe ou é propriedade de um utilizador diferente.
- Name
429 - Too Many Requests- Description
Excedeu a sua quota de tarefas pendentes ou limite de taxa.
Request
# Repair an existing task
curl https://api.meshy.ai/openapi/v1/print/repair \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
}'
# Or repair a model URL directly
curl https://api.meshy.ai/openapi/v1/print/repair \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"model_url": "https://example.com/model.stl"
}'
Response
{
"result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}
Recuperar uma Tarefa de Reparar Imprimibilidade
Este endpoint recupera uma tarefa de reparar imprimibilidade pelo seu ID.
Parâmetros
- Name
- id
- Type
- path
- Description
O ID da tarefa de reparar imprimibilidade a recuperar.
Retornos
O Objeto Tarefa de Reparar Imprimibilidade. O bloco model_urls está vazio até que a tarefa atinja SUCCEEDED. Apenas o campo model_urls correspondente ao formato de entrada é preenchido.
Request
curl https://api.meshy.ai/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "print-repair",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000030000,
"expires_at": 1715725401000,
"task_error": null,
"model_urls": {
"glb": "",
"gltf": "",
"fbx": "",
"obj": "",
"stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***",
"usdz": "",
"3mf": "",
"mtl": ""
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
"texture_urls": [],
"consumed_credits": 10
}
Eliminar uma Tarefa de Reparar Imprimibilidade
Este endpoint elimina permanentemente uma tarefa de reparar imprimibilidade e o seu resultado reparado. Esta ação é irreversível.
Parâmetros de Caminho
- Name
- id
- Type
- path
- Description
O ID da tarefa de reparar imprimibilidade a eliminar.
Retornos
Retorna 200 OK em caso de sucesso.
Pedido
curl --request DELETE \
--url https://api.meshy.ai/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Resposta
// Returns 200 Ok on success.
Listar Tarefas de Reparar Imprimibilidade
Este endpoint permite-lhe obter uma lista de tarefas de reparar imprimibilidade.
Parâmetros
Atributos opcionais
- Name
- page_num
- Type
- integer
- Description
Número da página para paginação. Começa e por defeito é
1.
- Name
- page_size
- Type
- integer
- Description
Limite do tamanho da página. Por defeito é
10itens. O máximo permitido é50itens.
- Name
- sort_by
- Type
- string
- Description
Campo para ordenar. Valores disponíveis:
+created_at: Ordenar por tempo de criação em ordem ascendente.-created_at: Ordenar por tempo de criação em ordem descendente.
Retornos
Retorna uma lista paginada de Objetos de Tarefa de Reparar Imprimibilidade.
Pedido
curl https://api.meshy.ai/openapi/v1/print/repair?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Resposta
[
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "print-repair",
"status": "SUCCEEDED",
"progress": 100,
"preceding_tasks": 0,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000030000,
"expires_at": 1715725401000,
"task_error": null,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
"gltf": "",
"fbx": "",
"obj": "",
"stl": "",
"usdz": "",
"3mf": "",
"mtl": ""
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
"texture_urls": [],
"consumed_credits": 10
}
]
Transmitir uma Tarefa de Reparar Imprimibilidade
Este endpoint transmite atualizações em tempo real para uma tarefa de reparar imprimibilidade usando Server-Sent Events (SSE).
Parâmetros
- Name
- id
- Type
- path
- Description
Identificador único para a tarefa de reparar imprimibilidade a transmitir.
Retornos
Retorna um fluxo de Objetos de Tarefa de Reparar Imprimibilidade como Server-Sent Events.
Para tarefas PENDING ou IN_PROGRESS, o fluxo de resposta incluirá apenas os campos necessários progress e status. O bloco model_urls é enviado apenas quando a tarefa atinge SUCCEEDED.
Request
curl -N https://api.meshy.ai/openapi/v1/print/repair/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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
"id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
"progress": 0,
"status": "PENDING"
}
event: message
data: {
"id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
"type": "print-repair",
"status": "SUCCEEDED",
"progress": 100,
"preceding_tasks": 0,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000030000,
"expires_at": 1715725401000,
"task_error": null,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***",
"gltf": "",
"fbx": "",
"obj": "",
"stl": "",
"usdz": "",
"3mf": "",
"mtl": ""
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/preview.png?Expires=***",
"texture_urls": [],
"consumed_credits": 10
}
O Objeto da Tarefa de Reparar Imprimibilidade
- Name
- id
- Type
- string
- Description
Identificador único para a tarefa. Embora utilizemos um UUID k-sortable para ids de tarefas como detalhe de implementação, não deves assumir nada sobre o formato do id.
- Name
- type
- Type
- string
- Description
Tipo da tarefa de reparar-imprimibilidade. O valor é
print-repair.
- Name
- status
- Type
- string
- Description
Estado da tarefa. Os valores possíveis são um de
PENDING,IN_PROGRESS,SUCCEEDED,FAILED,CANCELED.
- Name
- progress
- Type
- integer
- Description
Progresso da tarefa. Se a tarefa ainda não foi iniciada, esta propriedade será
0. Uma vez que a tarefa tenha sido concluída com sucesso, isto passará a ser100.
- Name
- preceding_tasks
- Type
- integer
- Description
A contagem de tarefas precedentes.
O valor deste campo é significativo apenas se o estado 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, esta propriedade será
0.
- Name
- finished_at
- Type
- timestamp
- Description
Carimbo de data/hora de quando a tarefa foi concluída, em milissegundos. Se a tarefa ainda não foi concluída, esta 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.
0se a tarefa ainda não foi concluída.
- Name
- task_error
- Type
- object
- Description
Informação de erro se a tarefa falhou. Esta propriedade é
nullse a tarefa não falhou. Veja Erros para mais detalhes.- Name
message- Type
- string
- Description
Mensagem de erro descrevendo o que correu mal.
- Name
- model_urls
- Type
- object
- Description
URLs descarregáveis para o modelo 3D reparado. Apenas o campo correspondente ao formato de entrada é preenchido; os outros campos de formato são strings vazias.
- Name
glb- Type
- string
- Description
URL descarregável para o GLB reparado. Preenchido quando a entrada foi um GLB ou quando
input_task_idfoi usado.
- Name
gltf- Type
- string
- Description
URL descarregável para o GLTF reparado. Preenchido quando a entrada foi um carregamento GLTF.
- Name
fbx- Type
- string
- Description
URL descarregável para o FBX reparado. Preenchido quando a entrada foi um carregamento FBX.
- Name
obj- Type
- string
- Description
URL descarregável para o OBJ reparado. Preenchido quando a entrada foi um carregamento OBJ.
- Name
stl- Type
- string
- Description
URL descarregável para o STL reparado. Preenchido quando a entrada foi um carregamento STL.
- Name
usdz- Type
- string
- Description
Reservado para saída USDZ. Sempre uma string vazia para tarefas de reparar-imprimibilidade.
- Name
3mf- Type
- string
- Description
Reservado para saída 3MF. Sempre uma string vazia para tarefas de reparar-imprimibilidade.
- Name
mtl- Type
- string
- Description
Reservado para saída MTL. Sempre uma string vazia para tarefas de reparar-imprimibilidade.
- Name
- thumbnail_url
- Type
- string
- Description
URL de uma imagem de pré-visualização renderizada a partir do modelo reparado.
- Name
- alpha_thumbnail_url
- Type
- string
- Description
URL descarregável para uma versão com fundo transparente (RGBA) de
thumbnail_url. Apenas presente quando a tarefa foi criada comalpha_thumbnail: truee a pré-visualização transparente foi renderizada com sucesso; caso contrário, este campo é omitido.
- Name
- texture_urls
- Type
- array
- Description
Sempre um array vazio. A reparação preserva apenas a geometria de entrada e não reprocessa texturas.
- Name
- consumed_credits
- Type
- integer
- Description
O número de créditos consumidos por esta tarefa.
10uma vez que a tarefa tenha atingidoSUCCEEDED. Retorna0para tarefasFAILED(os créditos são reembolsados em caso de falha).
O Objeto da Tarefa de Reparar Imprimibilidade
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "print-repair",
"status": "SUCCEEDED",
"progress": 100,
"preceding_tasks": 0,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000030000,
"expires_at": 1715725401000,
"task_error": null,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
"gltf": "",
"fbx": "",
"obj": "",
"stl": "",
"usdz": "",
"3mf": "",
"mtl": ""
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
"texture_urls": [],
"consumed_credits": 10
}