API de Desdobramento UV

A API de Desdobramento UV gera automaticamente um desdobramento UV de alta qualidade para um modelo 3D existente. Use-a como a etapa pré-requisito antes de aplicar texturas — ou sempre que você precisar de um layout UV limpo, sem sobreposições, para ferramentas downstream (Blender, Substance Painter, Unreal).

A saída é um "modelo branco UV" — mesma forma da entrada, mas com coordenadas UV totalmente novas e sem textura real (um material cinza 2×2 de marcador de posição é incluído para manter o slot de material glTF válido; ferramentas padrão tratam isso como sem textura).

Limitações. O Auto UV atualmente aceita malhas de até 40.000 faces — modelos maiores são rejeitados com um 400; execute Remesh primeiro para reduzir a contagem de polígonos. Malhas quad e n-gon são trianguladas durante a geração UV, portanto a saída é sempre uma malha triangular.

POST/openapi/v1/uv-unwrap

Criar uma tarefa de Desdobramento UV

Este endpoint cria uma nova tarefa de Desdobramento UV.

Parâmetros

Exatamente um de input_task_id ou model_url é obrigatório. Se ambos forem fornecidos, input_task_id terá prioridade.

  • Name
    input_task_id
    Type
    string
    Obrigatório
    Description

    O ID de uma tarefa concluída da Meshy API cujo output GLB você deseja desdobrar em UV (por exemplo, um resultado de Imagem para 3D, Texto para 3D ou Remesh). A tarefa de origem deve ter um status de SUCCEEDED e ter produzido um arquivo GLB.

    Se a malha de origem exceder o limite máximo de 40.000 faces, a solicitação será rejeitada com um 400 e você deverá executar Remesh primeiro para reduzir a contagem de polígonos.

  • Name
    model_url
    Type
    string
    Obrigatório
    Description

    Forneça um modelo 3D diretamente por meio de uma URL publicamente acessível ou Data URI. Somente .glb é suportado — a API lê binário glTF e não processa outros formatos. Para desdobrar em UV um modelo em outro formato (.fbx, .obj, .stl, .gltf), converta-o para .glb primeiro por meio da API Converter e, em seguida, passe o ID da tarefa resultante como input_task_id ou a URL de output GLB dela aqui.

    Para Data URIs, use o MIME type application/octet-stream.

    O mesmo limite máximo de 40.000 faces se aplica a input_task_id: malhas grandes demais são rejeitadas com um 400 — execute Remesh primeiro.

Retorna

A propriedade result da resposta contém o id da tarefa de Desdobramento UV recém-criada.

Modos de falha

  • Name
    400 - Bad Request
    Description

    A solicitação era inaceitável. Causas comuns:

    • Parâmetro ausente: É necessário fornecer input_task_id ou model_url.
    • Tarefa de entrada inválida: O input_task_id deve se referir a uma tarefa bem-sucedida com um resultado GLB.
    • Contagem de faces excedida: A malha de origem tem mais faces do que o limite máximo de Desdobramento UV. Execute Remesh primeiro.
    • Formato de modelo inválido: O model_url aponta para um arquivo com uma extensão não suportada.
    • URL inacessível: Não foi possível baixar o model_url.
  • Name
    401 - Unauthorized
    Description

    A autenticação falhou. Verifique sua chave de API.

  • Name
    402 - Payment Required
    Description

    Créditos insuficientes para executar esta tarefa. O Desdobramento UV custa 5 créditos por chamada.

  • Name
    404 - Not Found
    Description

    O recurso não está habilitado para sua conta. O Desdobramento UV é controlado por uma flag Statsig durante o lançamento — entre em contato com o suporte da Meshy se precisar de acesso.

  • Name
    429 - Too Many Requests
    Description

    Você excedeu seu limite de taxa.

Request

POST
/openapi/v1/uv-unwrap
# Chain from an existing Meshy task
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
      "input_task_id": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
    }'

# Or from a publicly accessible model URL
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
      "model_url": "https://example.com/path/to/model.glb"
    }'

Response

{
  "result": "019361c6-9b34-7b23-bef2-d0107c4d92e2"
}
GET/openapi/v1/uv-unwrap/:id

Recuperar uma tarefa de Desdobramento UV

Este endpoint recupera o estado atual de uma tarefa de Desdobramento UV por ID.

Retorna

Retorna um objeto de Tarefa de Desdobramento UV.

Request

GET
/openapi/v1/uv-unwrap/:id
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Veja o objeto de tarefa de exemplo abaixo.

DELETE/openapi/v1/uv-unwrap/:id

Excluir uma tarefa de Desdobramento UV

Exclua permanentemente uma tarefa de Desdobramento UV. A tarefa e seus resultados ficam inacessíveis.

Request

DELETE
/openapi/v1/uv-unwrap/:id
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-X DELETE \
-H "Authorization: Bearer ${YOUR_API_KEY}"
GET/openapi/v1/uv-unwrap

Listar tarefas de Desdobramento UV

Retorna uma lista paginada das tarefas de Desdobramento UV do solicitante, começando pelas mais recentes. Paginação padrão via page_num e page_size.

Request

GET
/openapi/v1/uv-unwrap
curl "https://api.meshy.ai/openapi/v1/uv-unwrap?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"
GET/openapi/v1/uv-unwrap/:id/stream

Transmitir uma tarefa de Desdobramento UV

Inscreva-se no progress da tarefa como Server-Sent Events. Cada evento message carrega um objeto de tarefa de Desdobramento UV; o fluxo é fechado quando a tarefa atinge SUCCEEDED, FAILED ou CANCELED.

Use isso em vez de fazer polling de GET /openapi/v1/uv-unwrap/:id para obter menor latência na conclusão.

Request

GET
/openapi/v1/uv-unwrap/:id/stream
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-N

O objeto de tarefa de Desdobramento UV

  • Name
    id
    Type
    string
    Description

    Identificador exclusivo da tarefa.

  • Name
    type
    Type
    string
    Description

    Sempre uv-unwrap.

  • Name
    model_urls
    Type
    object
    Description

    URLs de download pré-assinadas para o modelo branco UV gerado. O Desdobramento UV sempre retorna uma única entrada glb — a saída preserva a geometria de entrada, troca por novas coordenadas UV e usa um material cinza padrão no lugar de qualquer textura.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL pré-assinada para uma prévia PNG do modelo branco UV.

  • Name
    progress
    Type
    integer
    Description

    progress da tarefa, de 0 a 100.

  • Name
    status
    Type
    string
    Description

    Um de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Número de tarefas na fila antes desta. Presente enquanto o status é PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Carimbo de data/hora de criação da tarefa, em milissegundos.

  • Name
    started_at
    Type
    timestamp
    Description

    Carimbo de data/hora de quando o processamento começou, em milissegundos. 0 até ser iniciado.

  • Name
    finished_at
    Type
    timestamp
    Description

    Carimbo de data/hora de conclusão, em milissegundos. 0 até ser finalizado.

  • Name
    expires_at
    Type
    timestamp
    Description

    Carimbo de data/hora após o qual as URLs de download assinadas expiram, em milissegundos.

  • Name
    task_error
    Type
    object
    Description

    Detalhes de erro para tarefas com falha. Consulte Erros para a referência completa do objeto task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Créditos consumidos por esta tarefa. Retorna 0 para tarefas FAILED (os créditos são reembolsados em caso de falha). O Desdobramento UV cobra 5 créditos em caso de sucesso.

Example UV Unwrap Task Object

{
  "id": "019361c6-9b34-7b23-bef2-d0107c4d92e2",
  "type": "uv-unwrap",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1716579120000,
  "started_at": 1716579122000,
  "finished_at": 1716579180000,
  "expires_at": 1716665580000,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 5
}