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 o passo pré-requisito antes de aplicar texturas — ou sempre que precisar de uma disposição UV limpa e sem sobreposições para ferramentas subsequentes (Blender, Substance Painter, Unreal).

O resultado é um "modelo branco UV" — mesma forma que a entrada, mas com novas coordenadas UV e sem textura real (um material de espaço reservado cinza 2×2 é incluído para manter o slot de material glTF válido; ferramentas padrão tratam isto como não texturizado).

Limitações. O Auto UV atualmente suporta 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, o resultado é sempre uma malha de triângulos.

POST/openapi/v1/uv-unwrap

Criar uma tarefa de Desdobramento UV

Este endpoint cria uma nova tarefa de Desdobramento UV.

A tarefa é executada em segundo plano. Para saber quanto tempo normalmente demora, consulte Tempos de Processamento.

Parâmetros

É obrigatório fornecer exatamente um de input_task_id ou model_url. Se ambos forem fornecidos, input_task_id tem prioridade.

Name
input_task_id
Type
string
Obrigatório
Description
O ID de uma tarefa da Meshy API concluída cujo resultado GLB pretende desdobrar em UV (por exemplo, um resultado de Imagem para 3D, Texto para 3D ou Remesh). A tarefa de origem deve ter o estado SUCCEEDED e ter produzido um ficheiro GLB.
Se a malha de origem exceder o limite de 40.000 faces, o pedido será rejeitado com um 400 e deverá executar primeiro o Remesh para reduzir a contagem de polígonos.

Name
model_url
Type
string
Obrigatório
Description
Forneça um modelo 3D diretamente através de um URL publicamente acessível ou de um data URI. Só é suportado .glb — a API lê glTF binário e não analisa outros formatos. Para desdobrar em UV um modelo noutro formato (.fbx, .obj, .stl, .gltf), converta-o primeiro para .glb através da Convert API e passe aqui o ID da tarefa resultante como input_task_id ou o URL do seu resultado GLB.
Para Data URIs, utilize o MIME type application/octet-stream.
Tamanho máximo de ficheiro: 400 MB para um URL http ou https, 100 MB para um URI data:. Um GLB com mais de 100 MB não pode usar compressão Draco.
Aplica-se o mesmo limite de 40.000 faces que para input_task_id: malhas de tamanho excessivo são rejeitadas com um 400 — execute primeiro o Remesh.

Resultados

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

Modos de Falha

Name
400 - Bad Request
Description
O pedido foi inaceitável. Causas comuns:
- Parâmetro em falta: É necessário fornecer input_task_id ou model_url.
- Tarefa de entrada inválida: O input_task_id deve referir-se a uma tarefa bem-sucedida com um resultado GLB.
- Contagem de faces excedida: A malha de origem tem mais faces do que o limite do Desdobramento UV. Execute primeiro o Remesh.
- Formato de modelo inválido: O model_url aponta para um ficheiro com uma extensão não suportada.
- URL inacessível: Não foi possível transferir o model_url.
- Ficheiro de modelo demasiado grande: O ficheiro de model_url excede 400 MB (URL http ou https) ou 100 MB (URI data:).
- Demasiadas faces: O ficheiro de model_url tem mais de 100 MB e mais de 10.000.000 de faces. Reduza a contagem de faces e envie novamente o ficheiro.
- Ficheiro de modelo ilegível: O ficheiro de model_url tem mais de 100 MB e o seu cabeçalho não pode ser lido, por exemplo, um GLB comprimido com Draco.
- 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.
Name
401 - Unauthorized
Description
Falha na autenticação. Por favor, verifique a sua chave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarefa. O Desdobramento UV custa 5 créditos por chamada.
Name
404 - Not Found
Description
A funcionalidade não está ativada na sua conta. O Desdobramento UV está sujeito a um sinalizador Statsig durante o lançamento — contacte o suporte da Meshy se precisar de acesso.
Name
429 - Too Many Requests
Description
Excedeu o 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 Tarefa de Desdobramento UV.

Pedido

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 exemplo de objeto de tarefa abaixo.

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

Eliminar uma Tarefa de Desdobramento UV

Elimina permanentemente uma tarefa de Desdobramento UV. A tarefa e os seus resultados tornam-se inacessíveis.

Uma tarefa que ainda esteja PENDING é eliminada e os créditos consumidos no momento da criação são reembolsados.

Uma tarefa que já esteja IN_PROGRESS não pode ser eliminada: o pedido é rejeitado com 409 Conflict e a tarefa continua em execução. Os créditos de uma tarefa que o worker já começou a processar não são reembolsáveis, pelo que eliminá-la a meio da execução far-lhe-ia perder tanto os créditos como o resultado. Aguarde até que atinja SUCCEEDED, FAILED ou CANCELED e só depois a elimine.

Uma tarefa num estado terminal (SUCCEEDED, FAILED ou CANCELED) é eliminada sem reembolso.

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

Devolve uma lista paginada das tarefas de Desdobramento UV do chamador, da mais recente para a mais antiga. 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

Subscreva o progresso da tarefa como Eventos Enviados pelo Servidor. Cada evento message transporta um objeto Tarefa de Desdobramento UV; o fluxo fecha assim que a tarefa atinge SUCCEEDED, FAILED ou CANCELED.

Use isto em vez de sondar GET /openapi/v1/uv-unwrap/:id para 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 Tarefa de Desdobramento UV

Name
id
Type
string
Description
Identificador único para a 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 retorna sempre uma única entrada glb — a saída preserva a geometria de entrada, substitui por novas coordenadas UV e utiliza um material cinza padrão em vez de qualquer textura.
Name
thumbnail_url
Type
string
Description
URL pré-assinada para uma pré-visualização PNG do modelo branco UV.
Name
progress
Type
integer
Description
Progresso 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 da 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é começar.
Name
finished_at
Type
timestamp
Description
Carimbo de data/hora de conclusão, em milissegundos. 0 até terminar.
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 do erro para tarefas falhadas. 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.

Exemplo de Objeto Tarefa de Desdobramento UV

{
  "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
}