API Converter
Converta um modelo 3D para outros formatos de arquivo, a partir de uma tarefa do Meshy ou de um arquivo de modelo.
Criar uma tarefa de Converter
Cria uma tarefa de Converter. A tarefa é executada em segundo plano. Para saber quanto tempo uma tarefa costuma levar, consulte Tempos de processamento.
Request
curl https://api.meshy.ai/openapi/v1/convert \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"target_formats": ["fbx", "stl"]
}'
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 gerou um modelo 3D, por exemplo, uma tarefa de Texto para 3D, Imagem para 3D, Remesh, Redimensionar ou Retexturizar. A tarefa deve vir da API e ter o statusSUCCEEDED.
- Name
- model_url
- Type
- string
- Obrigatório
- Description
Obrigatório, a menos que você envie
input_task_id. O modelo a converter, como uma URL pública ou um Data URI. Se você enviar ambos, o Meshy usainput_task_id.O modelo deve ser um arquivo GLB, glTF, OBJ, FBX ou STL de no máximo 400 MB vindo de uma URL
httpouhttps, ou 100 MB como Data URI. Para um Data URI, use o MIME typeapplication/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. O Meshy conta faces como triângulos, então um quadrilátero conta como 2, e uma malha desenhada mais de uma vez conta uma vez por cópia.
- Um arquivo FBX deve ser binário, FBX 7.1 ou mais recente.
- Um arquivo GLB ou glTF não pode usar compressão Draco.
- Name
- target_formats
- Type
- string[]
- Obrigatório
- Description
Os formatos de arquivo a gerar. Liste pelo menos um. Uma lista ausente ou vazia retorna
400.Valores disponíveis:
glbfbxobjusdzblendstl3mf
Retornos
O campo result da resposta contém o ID da nova tarefa de Converter.
Modos de falha
- Name
400 - Bad Request- Description
A solicitação não pode ser executada. A mensagem de erro indica qual problema foi encontrado. Por exemplo:
- Parâmetro ausente: Nem
model_urlneminput_task_idforam enviados. target_formatsausente:target_formatsestá ausente ou não lista nenhum formato.- Tarefa de entrada inválida:
input_task_idnão é uma tarefa de API bem-sucedida com um arquivo de modelo. - Formato de modelo inválido: O arquivo
model_urltem uma extensão não suportada. - URL inacessível: O Meshy não consegue baixar o arquivo
model_url. - Arquivo de modelo muito grande: O arquivo
model_urltem mais de 400 MB vindo de uma URLhttpouhttps, ou mais de 100 MB como Data URI. - Excesso de faces: O arquivo
model_urltem 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 com mais de 100 MB. Envie-o como FBX binário ou GLB. - Arquivo de modelo ilegível: O arquivo
model_urltem mais de 100 MB, e o 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_urltem 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.
- Parâmetro ausente: Nem
- 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 em baixo-relevo, que este endpoint não consegue converter. A mensagem éThis model type does not support this operation. Envie um modelo diferente.
- Name
404 - Not Found- Description
input_task_idnã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.
Obter uma tarefa de Converter
Retorna uma tarefa de Converter pelo seu ID.
Request
curl https://api.meshy.ai/openapi/v1/convert/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "convert",
"model_urls": {
"fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
"stl": "https://assets.meshy.ai/.../model.stl?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 obtido na resposta de criação.
Retornos
Excluir uma tarefa de Convert
Exclui permanentemente uma tarefa de Convert, incluindo seus modelos e dados. Você não pode desfazer uma exclusão.
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v1/convert/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 rota
- 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 quando ela foi criada.
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
atinja o status SUCCEEDED, FAILED ou CANCELED, e então exclua-a.
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.
Listar tarefas de Converter
Retorna uma lista das suas tarefas de Converter.
Request
curl https://api.meshy.ai/openapi/v1/convert?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "convert",
"model_urls": {
"fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
"stl": "https://assets.meshy.ai/.../model.stl?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 ser retornada, até
255. Um valor maior retorna400.
- 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 Converter.
Transmitir uma tarefa de conversão (Convert)
Transmite as atualizações de uma tarefa de Convert como Server-Sent Events (SSE).
Request
curl -N https://api.meshy.ai/openapi/v1/convert/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": "convert",
"model_urls": {
"fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
"stl": "https://assets.meshy.ai/.../model.stl?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 Convert como Server-Sent Events.
Cada evento contém o objeto de tarefa completo, no mesmo formato retornado pelo endpoint Get. Enquanto a tarefa estiver PENDING ou IN_PROGRESS, seus campos de resultado ainda não têm valores.
O objeto de tarefa Convert
Um objeto de tarefa Convert descreve uma conversão de formato de um modelo 3D. Ele armazena o status, o progress e os arquivos 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
convert.
- Name
- model_urls
- Type
- object
- Description
URLs de download para o modelo convertido, uma por formato de arquivo. Apenas os formatos em
target_formatstêm URLs. Um formato que você não solicitou não tem chave, em vez de uma string vazia.
- Name
- progress
- Type
- integer
- Description
O quanto da tarefa já foi concluído, como uma porcentagem. É
0até a tarefa começar e100quando ela é bem-sucedida.
- Name
- status
- Type
- string
- Description
O status da tarefa, um dos valores
PENDING,IN_PROGRESS,SUCCEEDED,FAILEDouCANCELED.
- 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
Horário em que a tarefa foi criada, em milissegundos Unix.
- Name
- started_at
- Type
- timestamp
- Description
Horário em que a tarefa foi iniciada, em milissegundos Unix. É
0até a tarefa começar.
- Name
- finished_at
- Type
- timestamp
- Description
Horário em que a tarefa terminou, em milissegundos Unix. É
0até a tarefa terminar.
- Name
- expires_at
- Type
- timestamp
- Description
Horário em que as URLs de download da tarefa expiram, em milissegundos Unix. É
0até 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_colore também pode ter URLsmetallic,roughness,normal,emissionemetallic_roughness. Énullaté 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 é
1para uma tarefa Convert. É0para uma tarefaFAILED.