API Converter

Converta um modelo 3D para outros formatos de ficheiro, a partir de uma tarefa Meshy ou de um ficheiro de modelo.

POST/openapi/v1/convert

Criar uma tarefa de Convert

Cria uma tarefa de Convert. A tarefa é executada em segundo plano. Para saber quanto tempo uma tarefa normalmente demora, consulte Tempos de processamento.

Request

POST

/openapi/v1/convert

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 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, Redimensionar ou Retexturizar. A tarefa deve ter origem na API e ter o estado SUCCEEDED.

Name
model_url
Type
string
Obrigatório
Description
Obrigatório, a menos que envie input_task_id. O modelo a converter, como um URL público ou um Data URI. Se enviar ambos, o Meshy utiliza input_task_id.
O modelo deve ser um ficheiro GLB, glTF, OBJ, FBX ou STL com 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 deve também seguir estas regras:
- Um ficheiro GLB, glTF, FBX ou OBJ pode ter no máximo 10 000 000 faces. O 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 deve ser binário FBX 7.1 ou mais recente.
- Um ficheiro GLB ou glTF não deve utilizar compressão Draco.

Name
target_formats
Type
string[]
Obrigatório
Description
Os formatos de ficheiro a gerar. Indique pelo menos um. Uma lista em falta ou vazia devolve 400.
Valores disponíveis:
- glb
- fbx
- obj
- usdz
- blend
- stl
- 3mf

Resultados

O campo result da resposta contém o ID da nova tarefa de Convert.

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.
- target_formats em falta: target_formats está em falta ou não lista nenhum formato.
- 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 de model_url tem uma extensão não suportada.
- URL inacessível: O Meshy não consegue transferir o ficheiro de model_url.
- Ficheiro de modelo demasiado grande: O ficheiro de 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 de model_url tem mais de 100 MB e mais de 10 000 000 faces. Reduza o número de faces e envie o ficheiro novamente.
- FBX ASCII com mais de 100 MB: O ficheiro de 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 de model_url tem mais de 100 MB e o 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 de 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 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_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/convert/:id

Obter uma tarefa de Converter

Devolve uma tarefa de Converter através do respetivo ID.

Request

GET

/openapi/v1/convert/:id

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 proveniente da resposta de criação.

Devolve

O objeto de tarefa de Converter.

DELETE/openapi/v1/convert/:id

Eliminar uma tarefa de Convert

Elimina permanentemente uma tarefa de Convert, incluindo os seus modelos e dados. Não é possível anular uma eliminação.

Request

DELETE

/openapi/v1/convert/:id

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 caminho

Name
id
Type
path
Description
O ID da tarefa a eliminar.

Estado da tarefa

Eliminar uma tarefa PENDING reembolsa os créditos utilizados quando a criou.

Uma tarefa IN_PROGRESS não pode ser eliminada. O pedido devolve 409 Conflict, e a tarefa continua a ser executada. A Meshy não reembolsa uma tarefa que já foi iniciada, pelo que eliminá-la custar-lhe-ia 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/convert

Listar tarefas de Converter

Devolve uma lista das suas tarefas de Converter.

Request

GET

/openapi/v1/convert

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
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 de Converter.

GET/openapi/v1/convert/:id/stream

Transmitir uma tarefa de Converter

Transmite as atualizações de uma tarefa de Converter como Server-Sent Events (SSE).

Request

GET

/openapi/v1/convert/:id/stream

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 proveniente da resposta de criação.

Retorna

Um stream de objetos de tarefa de Converter como Server-Sent Events.

Cada evento contém o objeto de tarefa completo, com o mesmo formato devolvido pelo endpoint Get. Enquanto a tarefa estiver PENDING ou IN_PROGRESS, os 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. Contém o estado, o progress e os ficheiros 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 de tarefa, sempre convert.
Name
model_urls
Type
object
Description
URLs de download para o modelo convertido, um por cada formato de ficheiro. Apenas os formatos em target_formats têm URLs. Um formato que não tenha sido solicitado não tem chave, em vez de ter uma string vazia.
Name
progress
Type
integer
Description
Quanto da tarefa está concluído, em percentagem. É 0 até a tarefa começar e 100 quando é bem-sucedida.
Name
status
Type
string
Description
O estado da tarefa, um de 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ó é significativo 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 download da tarefa expiram, em milissegundos Unix. É 0 até a tarefa terminar.
Name
texture_urls
Type
array
Description
URLs de download para as texturas 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 também pode 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 texturas.
Name
task_error
Type
object
Description
Os detalhes do erro quando a tarefa falha. Ver Erros.
Name
consumed_credits
Type
integer
Description
O número de créditos que a tarefa utilizou, que é 1 para uma tarefa Convert. É 0 para uma tarefa FAILED.