API Reparar imprimibilidade
Repare um modelo 3D para imprimibilidade FDM — corrija 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 através de model_url, o model_urls.stl da resposta conterá a malha reparada e os outros campos de formato ficarão vazios. O caminho input_task_id lê sempre o GLB da tarefa de origem, pelo que 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 voltar a adicionar texturas, utilize a API Retexturizar no modelo reparado.
- Name
- input_task_id
- Type
- string
- Obrigatório
- Description
O ID de uma tarefa SUCCEEDED sua. Tipos de tarefa suportados: Imagem para 3D, Multi-imagem para 3D, Texto para 3D, Remesh e Retexturizar. A tarefa tem de ter um estado de
SUCCEEDEDe tem de ter produzido um asset GLB.
- Name
- model_url
- Type
- string
- Obrigatório
- Description
URL de um modelo 3D a reparar. Formatos suportados:
.glb,.stl,.obj. Tamanho máximo do ficheiro: 100 MB. Tem de usarhttp,httpsou um URLdata:(os URLs de dados ignoram as 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 com fundo transparente (RGBA) da pré-visualização e devolve-a comoalpha_thumbnail_urlna resposta GET. O campothumbnail_urlexistente permanece inalterado.
Devoluções
A propriedade result da resposta contém o id da tarefa de reparar imprimibilidade recém-criada.
Modos de falha
- Name
400 - Bad Request- Description
O pedido não era aceitá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 de modelo inválido:
model_urlestá malformado, utiliza um esquema não suportado ou tem uma extensão de ficheiro não suportada. - Ficheiro de modelo demasiado grande: o corpo de
model_urlexcedeu 100 MB. - Tarefa não concluída com sucesso: a tarefa referenciada ainda está pendente, em curso ou falhou.
- GLB em falta: a tarefa referenciada não tem nenhum asset GLB para reparar.
- Parâmetro em falta: nem
- Name
401 - Unauthorized- Description
A autenticação falhou. 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 pertence a um utilizador diferente.
- Name
429 - Too Many Requests- Description
Excedeu a sua quota de tarefas pendentes ou o 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"
}
Obter uma tarefa de Reparar imprimibilidade
Este endpoint obtém uma tarefa de Reparar imprimibilidade pelo respetivo ID.
Parâmetros
- Name
- id
- Type
- path
- Description
O ID da tarefa de Reparar imprimibilidade a obter.
Devolve
O Objeto de tarefa de Reparar imprimibilidade. O bloco model_urls fica vazio até a tarefa atingir 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": "",
"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 a sua saída reparada. Esta ação é irreversível.
Parâmetros do caminho
- Name
- id
- Type
- path
- Description
O ID da tarefa de Reparar imprimibilidade a eliminar.
Devolve
Devolve 200 OK em caso de sucesso.
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
// 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 tem como predefinição
1.
- Name
- page_size
- Type
- integer
- Description
Limite do tamanho da página. A predefinição é
10itens. O máximo permitido é50itens.
- Name
- sort_by
- Type
- string
- Description
Campo pelo qual ordenar. Valores disponíveis:
+created_at: Ordenar por hora de criação por ordem ascendente.-created_at: Ordenar por hora de criação por ordem descendente.
Devolve
Devolve uma lista paginada de Objetos de tarefa de Reparar imprimibilidade.
Request
curl https://api.meshy.ai/openapi/v1/print/repair?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"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=***",
"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 reparação de imprimibilidade usando Server-Sent Events (SSE).
Parâmetros
- Name
- id
- Type
- path
- Description
Identificador único da tarefa de reparação de imprimibilidade a transmitir.
Devolve
Devolve um stream de Objetos de tarefa de Reparar imprimibilidade como Server-Sent Events.
Para tarefas PENDING ou IN_PROGRESS, o stream 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=***",
"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 Reparar imprimibilidade
- Name
- id
- Type
- string
- Description
Identificador único da tarefa. Embora usemos um UUID k-ordenável para os ids das tarefas como detalhe de implementação, não deve fazer quaisquer suposições sobre o formato do id.
- Name
- type
- Type
- string
- Description
Tipo da tarefa de reparação de 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
Progress da tarefa. Se a tarefa ainda não tiver sido iniciada, esta propriedade será
0. Assim que a tarefa for concluída com êxito, isto passará a100.
- Name
- preceding_tasks
- Type
- integer
- Description
A contagem de tarefas precedentes.
O valor deste campo só é significativo 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 tiver sido iniciada, esta propriedade será
0.
- Name
- finished_at
- Type
- timestamp
- Description
Carimbo de data/hora de quando a tarefa foi terminada, em milissegundos. Se a tarefa ainda não tiver terminado, esta propriedade será
0.
- Name
- expires_at
- Type
- timestamp
- Description
Carimbo de data/hora de quando o resultado da tarefa expirará no sistema, em milissegundos.
0se a tarefa ainda não tiver terminado.
- Name
- task_error
- Type
- object
- Description
Informações de erro se a tarefa tiver falhado. Esta propriedade é
nullse a tarefa não tiver falhado. Consulte Erros para obter mais detalhes.- Name
message- Type
- string
- Description
Mensagem de erro que descreve o que correu mal.
- Name
- model_urls
- Type
- object
- Description
URLs transferíveis para o modelo 3D reparado. Apenas o campo que corresponde ao formato de entrada é preenchido; os outros campos de formato são strings vazias.
- Name
glb- Type
- string
- Description
URL transferível para o GLB reparado. Preenchido quando a entrada era um GLB ou quando
input_task_idfoi usado.
- Name
fbx- Type
- string
- Description
Reservado para saída FBX. Sempre uma string vazia para tarefas de reparação de imprimibilidade.
- Name
obj- Type
- string
- Description
URL transferível para o OBJ reparado. Preenchido quando a entrada era um carregamento OBJ.
- Name
stl- Type
- string
- Description
URL transferível para o STL reparado. Preenchido quando a entrada era um carregamento STL.
- Name
usdz- Type
- string
- Description
Reservado para saída USDZ. Sempre uma string vazia para tarefas de reparação de imprimibilidade.
- Name
3mf- Type
- string
- Description
Reservado para saída 3MF. Sempre uma string vazia para tarefas de reparação de imprimibilidade.
- Name
mtl- Type
- string
- Description
Reservado para saída MTL. Sempre uma string vazia para tarefas de reparação de 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 transferível para uma versão com fundo transparente (RGBA) de
thumbnail_url. Presente apenas quando a tarefa foi criada comalpha_thumbnail: truee a pré-visualização transparente foi renderizada com êxito; 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 volta a gerar texturas.
- Name
- consumed_credits
- Type
- integer
- Description
O número de créditos consumidos por esta tarefa.
10assim que a tarefa atingirSUCCEEDED. Devolve0para tarefasFAILED(os créditos são reembolsados em caso de falha).
The Repair Printability Task Object
{
"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=***",
"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
}