lowpoly será descontinuado em 30 de out. de 2026. meshy-7 como modelo de geração 3D será descontinuado em 31 de dez. de 2026; como modelo de textura continua disponível. Troque de modelo antes dessas datas para evitar erros nas solicitações. Ver todas as descontinuações

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

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 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 status SUCCEEDED.

  • 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 usa input_task_id.

    O modelo deve ser um arquivo GLB, glTF, OBJ, FBX ou STL de no máximo 400 MB vindo de uma URL http ou https, ou 100 MB como Data URI. Para um Data URI, use o MIME type application/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:

    • glb
    • fbx
    • obj
    • usdz
    • blend
    • stl
    • 3mf

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_url nem input_task_id foram enviados.
    • target_formats ausente: target_formats está ausente ou não lista nenhum formato.
    • Tarefa de entrada inválida: input_task_id não é uma tarefa de API bem-sucedida com um arquivo de modelo.
    • Formato de modelo inválido: O arquivo model_url tem 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_url tem mais de 400 MB vindo de uma URL http ou https, ou mais de 100 MB como Data URI.
    • Excesso de faces: O arquivo model_url tem 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_url tem 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_url tem 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.

  • 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_id nã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.


GET/openapi/v1/convert/:id

Obter uma tarefa de Converter

Retorna uma tarefa de Converter pelo seu 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 obtido na resposta de criação.

Retornos

O objeto de tarefa de Converter.


DELETE/openapi/v1/convert/:id

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

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


GET/openapi/v1/convert

Listar tarefas de Converter

Retorna 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
    padrão 1
    Description

    O número da página a ser retornada, até 255. Um valor maior retorna 400.

  • 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.


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

Transmitir uma tarefa de conversão (Convert)

Transmite as atualizações de uma tarefa de Convert 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 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_formats tê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. É 0 até a tarefa começar e 100 quando ela é bem-sucedida.

  • Name
    status
    Type
    string
    Description

    O status da tarefa, um dos valores 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

    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. É 0 até a tarefa começar.

  • Name
    finished_at
    Type
    timestamp
    Description

    Horário em que a tarefa terminou, em milissegundos Unix. É 0 até a tarefa terminar.

  • Name
    expires_at
    Type
    timestamp
    Description

    Horário em que as URLs de download da tarefa expiram, em milissegundos Unix. É 0 até 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_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 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 é 1 para uma tarefa Convert. É 0 para uma tarefa FAILED.